Bug 974685 - Incorrect example for sched_getaffinity relying on EINVAL return.
Incorrect example for sched_getaffinity relying on EINVAL return.
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: man-pages-overrides (Show other bugs)
6.6
Unspecified Unspecified
unspecified Severity unspecified
: rc
: ---
Assigned To: Peter Schiffer
Iveta Wiedermann
: ManPageChange, Patch
Depends On: 974679
Blocks: 1011194
  Show dependency treegraph
 
Reported: 2013-06-14 15:50 EDT by Carlos O'Donell
Modified: 2013-11-21 17:58 EST (History)
5 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Cause: sched_setaffinity(2) man page contained invalid example Consequence: incorrect documentation Fix: remove invalid example from sched_setaffinity(2) man page Result: correct documentation
Story Points: ---
Clone Of: 974679
Environment:
Last Closed: 2013-11-21 17:58:01 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
man-pages-3.22-sched_setaffinity-revert.patch (2.08 KB, patch)
2013-09-20 12:56 EDT, Peter Schiffer
no flags Details | Diff

  None (edit)
Description Carlos O'Donell 2013-06-14 15:50:20 EDT
This bug also applies to the RHEL6 man-pages project.

Version in RHEL6.4 is man-pages-3.22-20.el6.noarch.

+++ This bug was initially created as a clone of Bug #974679 +++

Description of problem:
The man-pages package contains a patch to the sched_getaffinity manual page that includes an example program that incorrectly relies on EINVAL being returned by sched_getaffinity.

Version-Release number of selected component (if applicable):
man-pages-3.35-4.fc17.noarch

How reproducible:
`man 2 sched_getaffinity`

Actual results:
Man page has the example program:
~~~
EXAMPLE
          #define _GNU_SOURCE

          #include <sched.h>
          #include <stdio.h>
          #include <errno.h>

          int main(void)
          {
               cpu_set_t *mask;
               size_t size;
               int i;
               int nrcpus = 1024;

       realloc:
               mask = CPU_ALLOC(nrcpus);
               size = CPU_ALLOC_SIZE(nrcpus);
               CPU_ZERO_S(size, mask);
               if ( sched_getaffinity(0, size, mask) == -1 ) {
                       CPU_FREE(mask);
                       if (errno == EINVAL &&
                           nrcpus < (1024 << 8)) {
                              nrcpus = nrcpus << 2;
                              goto realloc;
                       }
                       perror("sched_getaffinity");
                       return -1;
               }

               for ( i = 0; i < nrcpus; i++ ) {
                       if ( CPU_ISSET_S(i, size, mask) ) {
                               printf("CPU %d is set\n", (i+1));
                       }
               }

               CPU_FREE(mask);

               return 0;
          }
~~~

Expected results:
Should have the example:
~~~
          #define _GNU_SOURCE

          #include <sched.h>
          #include <stdio.h>
          #include <errno.h>
          #include <unistd.h>

          int main(void)
          {
               cpu_set_t *mask;
               size_t size;
               int i;
               int nrcpus = sysconf(_SC_NPROCESSORS_ONLN);

               if (nrcpus == -1) {
                       perror("sysconf");
                       return -1;
               }

               mask = CPU_ALLOC(nrcpus);
               size = CPU_ALLOC_SIZE(nrcpus);
               CPU_ZERO_S(size, mask);
               if ( sched_getaffinity(0, size, mask) == -1 ) {
                       perror("sched_getaffinity");
                       return -1;
               }

               for ( i = 0; i < nrcpus; i++ ) {
                       if ( CPU_ISSET_S(i, size, mask) ) {
                               printf("CPU %d is set\n", (i+1));
                       }
               }

               CPU_FREE(mask);

               return 0;
          }
~~~

Additional info:
The only easy way to determine the online cpus is to use sysconf (_SC_PROCESSORS_ONLN);

The GNU C Library does not guarantee that sched_getaffinity will return EINVAL if the mask is not the right size. Future versions of glibc will never return EINVAL, and will always copy only the cpus that were requested by the user (which has always been the intent of the library).

If you want the affinity for all of the cpus then you must use sysconf to determine how many there might be and then request that amount.

The value returned by sysconf is constant for the lifetime of the process.

The Linux kernel online cpu mask is also constant.

Notes:

This has been fixed in F18, F19, and rawhide.

The example could go upstream, but should not use the EINVAL method to determine kernel's cpu mask size.
Comment 2 Peter Schiffer 2013-09-20 12:56:53 EDT
Created attachment 800573 [details]
man-pages-3.22-sched_setaffinity-revert.patch
Comment 8 errata-xmlrpc 2013-11-21 17:58:01 EST
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2013-1695.html

Note You need to log in before you can comment on or make changes to this bug.