Re: man page pthreads(3)

Re: man page pthreads(3)

[Alejandro Colomar]

[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/