Re: What *is* the API for sched_getaffinity? Should sched_getaffinity always succeed when using cpu_set_t?

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Hello Tolga,

On 06/29/2015 11:40 PM, Tolga Dalman wrote:
> Michael,
> 
> given the approach is accepted by Carlos and Roland, I have
> some minor textual suggestions for the patch itself.
> 
> On 06/26/2015 10:05 PM, Michael Kerrisk (man-pages) wrote:
>> --- a/man2/sched_setaffinity.2
>> +++ b/man2/sched_setaffinity.2
>> @@ -223,6 +223,47 @@ system call returns the size (in bytes) of the
>>  .I cpumask_t
>>  data type that is used internally by the kernel to
>>  represent the CPU set bit mask.
>> +.SS Handling systems with more than 1024 CPUs
> 
> What if the system has exactly 1024 CPUs ?
> Suggestion: systems with 1024 or more CPUs

I think you've missed something here. CPUs are numbered starting at 0.
"more than 1024 CPUs" is correct here, I belive.

> 
>> +The
>> +.I cpu_set_t
>> +data type used by glibc has a fixed size of 128 bytes,
>> +meaning that the maximum CPU number that can be represented is 1023.
>> +.\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
>> +.\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
> 
> No objection, although I have never really noticed external references
> in man-pages (esp. web refs). Shouldn't these be generally avoided ?
> (and yes, I have noticed the FIXME)

Those pieces are comments in the page source (not rendered by man(1)).

>> +If the system has more than 1024 CPUs, then calls of the form:
> 
> 1024 or more CPUs.

See above

>> +
>> +    sched_getaffinity(pid, sizeof(cpu_set_t), &mask);
>> +
>> +will fail with the error
>> +.BR EINVAL ,
>> +the error produced by the underlying system call for the case where the
>> +.I mask
>> +size specified in
>> +.I cpusetsize
>> +is smaller than the size of the affinity mask used by the kernel.
>> +.PP
>> +The underlying system calls (which represent CPU masks as bit masks of type
>> +.IR "unsigned long\ *" )
>> +impose no restriction on the size of the mask.
>> +To handle systems with more than 1024 CPUs, one must dynamically allocate the
>> +.I mask
>> +argument using
>> +.BR CPU_ALLOC (3)
> 
> I would rewrite the sentence to avoid "one must".

This is a "voice" thing. I personally find "one must" is okay.

>> +and manipulate the mask using the "_S" macros described in
> 
> and manipulate the macros ending with "_S" as described in

I think you've misread the text. I think it's okay.

>> +.BR CPU_ALLOC (3).
>> +Using an allocation based on the number of online CPUs:
>> +
>> +    cpu_set_t *mask = CPU_ALLOC(CPU_ALLOC_SIZE(
>> +                                sysconf(_SC_NPROCESSORS_CONF)));
>> +
>> +is probably sufficient, although the value returned by the
>> +.BR sysconf ()
>> +call can in theory change during the lifetime of the process.
>> +Alternatively, one can obtain a value that is guaranteed to be stable for
> 
> Like above, I would replace "one can obtain a value" by "a value can be obtained".

See above.

>> +the lifetime of the process by proby for the size of the required mask using
> 
> s/proby/probing/.

Thanks--I'd already spotted that one and fixed.

>> +.BR sched_getaffinity ()
>> +calls with increasing mask sizes until the call does not fail with the error
>> +.BR EINVAL .
> 
> I would replace "until the call does not fail with error ..." by "while the call succeeds".

I think you've misunderstood the logic here... Take another look at the sentence.

Thanks,

Michael

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