Bug 60744

Summary:	waitid man page does not document the 5th argument "struct rusage*"
Product:	Documentation	Reporter:	Hannes Landeholm (hannes)
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	mtk.manpages
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:

Description Hannes Landeholm 2013-08-14 16:15:51 UTC

I just spent 5 hours debugging my program and trying to figure out why the kernel overwrote my stack. I had to read the source code to realize that the real syscall took an additional 5th argument.

Wrong signature:
int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);

Correct signature:
int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options, struct rusage* rusage);

The kernel man pages should not assume that the user is using glibc, or at least give enough information for developers to write their own, correct wrappers.

Comment 1 Michael Kerrisk 2013-09-04 13:12:20 UTC

(In reply to Hannes Landeholm from comment #0)
> I just spent 5 hours debugging my program and trying to figure out why the
> kernel overwrote my stack. I had to read the source code to realize that the
> real syscall took an additional 5th argument.
> 
> Wrong signature:
> int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);
> 
> Correct signature:
> int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options, struct
> rusage* rusage);
> 
> The kernel man pages should not assume that the user is using glibc, or at
> least give enough information for developers to write their own, correct
> wrappers.

To be precise, the page is documenting the POSIX waitid() interface (rather than glibc), but you are of course right that the page should make mention of the fifth argument. I've added some text on this.

http://git.kernel.org/cgit/docs/man-pages/man-pages.git/commit/?id=d8b13fb4d939978f02db3d49697cbccff2881a30

Cheers,

Michael