Bug or misdocumented feature in pthread_setaffinity_np.3

Bug or misdocumented feature in pthread_setaffinity_np.3

[Alejandro Colomar]

Hello Michael,

pthread_setaffinity_np() and pthread_getaffinity_np(), "on error, return 
a non-zero error number".  Usually that kind of library functions return 
-1, and I don't know if this case is different.  The RETURN VALUE 
section doesn't specify. Actually the words "error number" hint that it 
is an `errno` value, because it's the same words in errno.3, but it 
could be clearer, and maybe also point to errno(3) in that page.

In the EXAMPLES section, however, the return value is used as if it were 
an `errno` value, printing the corresponding string with perror().

Is that example printing random strings (a bug)?

Or is it that those functions return an error code that corresponds to a 
valid `errno` error number?  In that case it could be documented better 
IMHO.

If that is the case, do those functions set `errno` and also return that 
same `errno` value redundantly?


Thanks,

Alex.

Re: Bug or misdocumented feature in pthread_setaffinity_np.3

[Samuel Thibault]

Hello,

Alejandro Colomar via Libc-alpha, le lun. 07 sept. 2020 11:00:05 +0200, a ecrit:
> Or is it that those functions return an error code that corresponds to a
> valid `errno` error number?  In that case it could be documented better
> IMHO.
> 
> If that is the case, do those functions set `errno` and also return that
> same `errno` value redundantly?

All pthread functions return E* values on errors, and do not touch
errno.

Samuel

Re: Bug or misdocumented feature in pthread_setaffinity_np.3

[Michael Kerrisk (man-pages)]

Hi Alex,

On Mon, 7 Sep 2020 at 11:00, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Hello Michael,
>
> pthread_setaffinity_np() and pthread_getaffinity_np(), "on error, return
> a non-zero error number".  Usually that kind of library functions return
> -1, and I don't know if this case is different.  The RETURN VALUE
> section doesn't specify. Actually the words "error number" hint that it
> is an `errno` value, because it's the same words in errno.3, but it
> could be clearer, and maybe also point to errno(3) in that page.

All of the pthreads APIs do this: return 0 on success, or an
errno-style error number on failure.
>
> In the EXAMPLES section, however, the return value is used as if it were
> an `errno` value, printing the corresponding string with perror().
>
> Is that example printing random strings (a bug)?

No, it's correct :-).

> Or is it that those functions return an error code that corresponds to a
> valid `errno` error number?  In that case it could be documented better
> IMHO.

Yes, probably you are right. The thing is, when you use pthreads you
have to know they are different from the conventional APIs. The
pthreads(7) page hints at this:

       Most  pthreads  functions return 0 on success, and an error number
       on failure.  Note that the pthreads functions do  not  set  errno.

> If that is the case, do those functions set `errno` and also return that
> same `errno` value redundantly?

No, they don't use errno at all.

So, I exp[anded the text in pthreads(7), to make the point more explicit:

       Most  pthreads  functions return 0 on success, and an error number
       on failure.  The error numbers that can be returned have the  same
       meaning  as  the  error  numbers returned in errno by conventional
       system calls and C library  functions.   Note  that  the  pthreads
       functions  do  not  set errno.

Note that the various pthreads manual pages (should) all refer to
pthreads(7) in SEE ALSO. I'm reluctant to add a note like this to
every pthreads page, since it seems verbose, but I have also added
this note to errno(3):

       Note  that  the  POSIX  threads  APIs  do  not set errno on error.
       Instead, on failure they return an error number  as  the  function
       result.   These  error numbers have the same meanings as the error
       numbers returned in errno by other APIs.

Perhaps that suffices for you?

Thanks,

Michael

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

Re: Bug or misdocumented feature in pthread_setaffinity_np.3

[Alejandro Colomar]

Hi Michael,

On 2020-09-07 11:21, Michael Kerrisk (man-pages) wrote:
>> Or is it that those functions return an error code that corresponds to a
>> valid `errno` error number?  In that case it could be documented better
>> IMHO.
> 
> Yes, probably you are right. The thing is, when you use pthreads you
> have to know they are different from the conventional APIs. The
> pthreads(7) page hints at this:
> 
>         Most  pthreads  functions return 0 on success, and an error number
>         on failure.  Note that the pthreads functions do  not  set  errno.
> 
>> If that is the case, do those functions set `errno` and also return that
>> same `errno` value redundantly?
> 
> No, they don't use errno at all.
> 
> So, I exp[anded the text in pthreads(7), to make the point more explicit:
> 
>         Most  pthreads  functions return 0 on success, and an error number
>         on failure.  The error numbers that can be returned have the  same
>         meaning  as  the  error  numbers returned in errno by conventional
>         system calls and C library  functions.   Note  that  the  pthreads
>         functions  do  not  set errno.
> 
> Note that the various pthreads manual pages (should) all refer to
> pthreads(7) in SEE ALSO. I'm reluctant to add a note like this to
> every pthreads page, since it seems verbose, but I have also added
> this note to errno(3):
> 
>         Note  that  the  POSIX  threads  APIs  do  not set errno on error.
>         Instead, on failure they return an error number  as  the  function
>         result.   These  error numbers have the same meanings as the error
>         numbers returned in errno by other APIs.
> 
> Perhaps that suffices for you?

Yes, that is much clearer now.

Thanks,

Alex

Re: Bug or misdocumented feature in pthread_setaffinity_np.3

[Florian Weimer]

* Alejandro Colomar via Libc-alpha:

> pthread_setaffinity_np() and pthread_getaffinity_np(), "on error,
> return a non-zero error number".  Usually that kind of library
> functions return -1, and I don't know if this case is different.  The
> RETURN VALUE section doesn't specify. Actually the words "error
> number" hint that it is an `errno` value, because it's the same words
> in errno.3, but it could be clearer, and maybe also point to errno(3)
> in that page.

Most libpthread functions return errno codes instead of in addition to
setting errno.  This is something that POSIX requires.  The asymmetry is
annoying.  I think it dates back to the days where libpthread was purely
a library in some implementations, to be used with a C library that was
not even aware of threads and did not have a per-thread errno variable.
(Of course, that didn't work too well, but people tried.)

Thanks,
Florian
-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: Bug or misdocumented feature in pthread_setaffinity_np.3

[Michael Kerrisk (man-pages)]

On Mon, 7 Sep 2020 at 11:24, Florian Weimer <fweimer@redhat.com> wrote:
>
> * Alejandro Colomar via Libc-alpha:
>
> > pthread_setaffinity_np() and pthread_getaffinity_np(), "on error,
> > return a non-zero error number".  Usually that kind of library
> > functions return -1, and I don't know if this case is different.  The
> > RETURN VALUE section doesn't specify. Actually the words "error
> > number" hint that it is an `errno` value, because it's the same words
> > in errno.3, but it could be clearer, and maybe also point to errno(3)
> > in that page.
>
> Most libpthread functions return errno codes instead of in addition to
> setting errno.  This is something that POSIX requires.  The asymmetry is
> annoying.  I think it dates back to the days where libpthread was purely
> a library in some implementations, to be used with a C library that was
> not even aware of threads and did not have a per-thread errno variable.
> (Of course, that didn't work too well, but people tried.)

I had always understood that it was POSIX's attempt to address the
design fault inherent in traditional APIs whereby there weresometimes
conflicts in the dual purpose of the return value to indicate both
success/failure and to return valid information. Thus, for example,
the mess with getpriority(2) and one or other APIs where a return
value of -1 becomes ambiguous. See also posix_fadvise(),
posix_fallocate(), posix_madvise(), which are APIs created by POSIX
that do the same thing (though on the other hand, posix_openpt() does
not).

But, your explanation also sounds plausible, Florian. I wonder which is correct.

Cheers,

Michael