Re: Documentation error for "sched_getaffinity"

Re: Documentation error for "sched_getaffinity"

[Michael Kerrisk (man-pages)]

Hello Marc,

On 9/25/19 11:33 AM, Marc Brandis wrote:
> Hello,
> 
> I noticed the following documentation error in the online man pages
> (man7.org) for the "sched_getaffinity(2)" system call. It incorrectly
> says that sched_getaffinity returns 0 on success; instead it returns
> the number of bits in the CPU set, which I assume is the number of


I think you mean "bytes", not "bits"

> CPUs (incl. hyperthreading) the system has.

> I am running on Linux kernel 4.15.0-62 in Ubuntu build 18.04. I came
> across it when debugging a multi-threaded program using the call, and
> that program passing a large buffer for the cpuset parameter (8
> kBytes).
> 
> It is not just a typo or grammar issue, but I still was not sure
> whether this should be reported through Bugzilla.

The explanation for what you are seeing is actually covered 
lower in the page:

   C library/kernel differences
       ...
       On  success,  the  raw sched_getaffinity() system call returns the
       number of bytes placed copied into the mask buffer; this  will  be
       the minimum of cpusetsize and the size (in bytes) of the cpumask_t
       data type that is used internally by the kernel to  represent  the
       CPU set bit mask.

But, you're not the first to miss this detail, so I've just now modified
the RETURN VALUE section to make it easier for people to find that text:

       On  success,  sched_setaffinity() and sched_getaffinity() return 0
       (but see "C library/kernel differences" below,  which  notes  that
       the  underlying  sched_getaffinity() differs in its return value).

Thanks,


Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/