Hi Alex,
On Mon, 7 Sep 2020 at 11:00, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> 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/
