[Resend to linux-man@ with correct address.]
On 5/14/22 15:42, Alejandro Colomar wrote:
Hi Youssef,
On 5/7/22 02:25, Youssef Hajjioui wrote:
Good day,
I would like to report what could be a confusing citation in the
manual page |pthreads(3)|
The following citation:
Each of the threads in a process has a unique thread identifier
(stored in a type |pthread_t|). This identifier is returned to the
caller of |pthread_create(3)|, and a thread can obtain its own
thread identifier using |pthread_self(3)|.
However the function |pthread_create(3)| does not return a thread ID
to the caller; it returns 0 on success, or a macro that specifies the
error i.e (E2BIG and such). The function takes a pointer parameter
|pthread_t *thread| which is a pointer to the structure that stores
the thread ID.
I think that it would avoid confusion to rectify the cited behavior.
I understand your confusion. Some pages use the term return strictly to
mean C's `return` keyword (as you suggest doing). Some other pages use
it more freely to mean "pass a value", including both `return` and
"storing a value in a pointer parameter".
If you propose some alternative wording that makes sense, we can
consider it.
My OS is Ubuntu 20.04.
I am reading through many manual pages concerning the Linux
programming interface. Do you think it is a good idea that I report
such confusing occurrences to you. I would like to contribute into
making the manual pages clear and easily understandable.
Please do :-)
Thanks!
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
