[PATCH] getlogin.3: Reformat thread-safety information

[PATCH] getlogin.3: Reformat thread-safety information

[Peng Haitao]

Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
---
 man3/getlogin.3 | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/man3/getlogin.3 b/man3/getlogin.3
index fcbd0fb..828df2b 100644
--- a/man3/getlogin.3
+++ b/man3/getlogin.3
@@ -138,19 +138,23 @@ password database file
 (traditionally \fI/etc/utmp\fP;
 some libc versions used \fI/var/adm/utmp\fP)
 .SH ATTRIBUTES
-.SS Multithreading (see pthreads(7))
-The
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface	Attribute	Value
+T{
 .BR getlogin ()
-function is not thread-safe.
-.LP
-The
+T}	Thread safety	MT-Unsafe locale
+T{
 .BR getlogin_r ()
-function is thread-safe.
-.LP
-The
+T}	Thread safety	MT-Safe locale
+T{
 .BR cuserid ()
-function is thread-safe with exceptions.
-It is not thread-safe if called with a NULL parameter.
+T}	Thread safety	MT-Unsafe race:cuserid/!string locale
+.TE
 .SH CONFORMING TO
 .BR getlogin ()
 and
-- 
1.9.3

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

Thank you, Haitao. Applied in the attributes_reformat_2 branch.

Cheers,

Michael



On 10/17/2014 05:59 AM, Peng Haitao wrote:
> Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
> ---
>  man3/getlogin.3 | 24 ++++++++++++++----------
>  1 file changed, 14 insertions(+), 10 deletions(-)
> 
> diff --git a/man3/getlogin.3 b/man3/getlogin.3
> index fcbd0fb..828df2b 100644
> --- a/man3/getlogin.3
> +++ b/man3/getlogin.3
> @@ -138,19 +138,23 @@ password database file
>  (traditionally \fI/etc/utmp\fP;
>  some libc versions used \fI/var/adm/utmp\fP)
>  .SH ATTRIBUTES
> -.SS Multithreading (see pthreads(7))
> -The
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lb lb lb
> +l l l.
> +Interface	Attribute	Value
> +T{
>  .BR getlogin ()
> -function is not thread-safe.
> -.LP
> -The
> +T}	Thread safety	MT-Unsafe locale
> +T{
>  .BR getlogin_r ()
> -function is thread-safe.
> -.LP
> -The
> +T}	Thread safety	MT-Safe locale
> +T{
>  .BR cuserid ()
> -function is thread-safe with exceptions.
> -It is not thread-safe if called with a NULL parameter.
> +T}	Thread safety	MT-Unsafe race:cuserid/!string locale
> +.TE
>  .SH CONFORMING TO
>  .BR getlogin ()
>  and
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

Hello Haitao,

Just double checking one point. See below.

On 10/17/2014 05:59 AM, Peng Haitao wrote:
> Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
> ---
>  man3/getlogin.3 | 24 ++++++++++++++----------
>  1 file changed, 14 insertions(+), 10 deletions(-)
> 
> diff --git a/man3/getlogin.3 b/man3/getlogin.3
> index fcbd0fb..828df2b 100644
> --- a/man3/getlogin.3
> +++ b/man3/getlogin.3
> @@ -138,19 +138,23 @@ password database file
>  (traditionally \fI/etc/utmp\fP;
>  some libc versions used \fI/var/adm/utmp\fP)
>  .SH ATTRIBUTES
> -.SS Multithreading (see pthreads(7))
> -The
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lb lb lb
> +l l l.
> +Interface	Attribute	Value
> +T{
>  .BR getlogin ()
> -function is not thread-safe.
> -.LP
> -The
> +T}	Thread safety	MT-Unsafe locale

Should this be "MT-Safe locale"?

Cheers,

Michael


> +T{
>  .BR getlogin_r ()
> -function is thread-safe.
> -.LP
> -The
> +T}	Thread safety	MT-Safe locale
> +T{
>  .BR cuserid ()
> -function is thread-safe with exceptions.
> -It is not thread-safe if called with a NULL parameter.
> +T}	Thread safety	MT-Unsafe race:cuserid/!string locale
> +.TE
>  .SH CONFORMING TO
>  .BR getlogin ()
>  and
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Peng Haitao]

On 10/17/2014 02:05 PM, Michael Kerrisk (man-pages) wrote:
> Hello Haitao,
> 
> Just double checking one point. See below.
> 
> On 10/17/2014 05:59 AM, Peng Haitao wrote:
>> Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
>> ---
>>  man3/getlogin.3 | 24 ++++++++++++++----------
>>  1 file changed, 14 insertions(+), 10 deletions(-)
>>
>> diff --git a/man3/getlogin.3 b/man3/getlogin.3
>> index fcbd0fb..828df2b 100644
>> --- a/man3/getlogin.3
>> +++ b/man3/getlogin.3
>> @@ -138,19 +138,23 @@ password database file
>>  (traditionally \fI/etc/utmp\fP;
>>  some libc versions used \fI/var/adm/utmp\fP)
>>  .SH ATTRIBUTES
>> -.SS Multithreading (see pthreads(7))
>> -The
>> +For an explanation of the terms used in this section, see
>> +.BR attributes (7).
>> +.TS
>> +allbox;
>> +lb lb lb
>> +l l l.
>> +Interface	Attribute	Value
>> +T{
>>  .BR getlogin ()
>> -function is not thread-safe.
>> -.LP
>> -The
>> +T}	Thread safety	MT-Unsafe locale
> 
> Should this be "MT-Safe locale"?
> 

getlogin() is MT-Unsafe and is influenced by setlocale(),
So "MT-Unsafe locale" is right.


-- 
Best Regards,
Peng

> Cheers,
> 
> Michael
> 
> 
>> +T{
>>  .BR getlogin_r ()
>> -function is thread-safe.
>> -.LP
>> -The
>> +T}	Thread safety	MT-Safe locale
>> +T{
>>  .BR cuserid ()
>> -function is thread-safe with exceptions.
>> -It is not thread-safe if called with a NULL parameter.
>> +T}	Thread safety	MT-Unsafe race:cuserid/!string locale
>> +.TE
>>  .SH CONFORMING TO
>>  .BR getlogin ()
>>  and
>>
> 
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

[CC expanded, just in case Carlos and Alexandre have something 
to add]

On 10/17/2014 08:29 AM, Peng Haitao wrote:
> 
> On 10/17/2014 02:05 PM, Michael Kerrisk (man-pages) wrote:
>> Hello Haitao,
>>
>> Just double checking one point. See below.
>>
>> On 10/17/2014 05:59 AM, Peng Haitao wrote:
>>> Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
>>> ---
>>>  man3/getlogin.3 | 24 ++++++++++++++----------
>>>  1 file changed, 14 insertions(+), 10 deletions(-)
>>>
>>> diff --git a/man3/getlogin.3 b/man3/getlogin.3
>>> index fcbd0fb..828df2b 100644
>>> --- a/man3/getlogin.3
>>> +++ b/man3/getlogin.3
>>> @@ -138,19 +138,23 @@ password database file
>>>  (traditionally \fI/etc/utmp\fP;
>>>  some libc versions used \fI/var/adm/utmp\fP)
>>>  .SH ATTRIBUTES
>>> -.SS Multithreading (see pthreads(7))
>>> -The
>>> +For an explanation of the terms used in this section, see
>>> +.BR attributes (7).
>>> +.TS
>>> +allbox;
>>> +lb lb lb
>>> +l l l.
>>> +Interface	Attribute	Value
>>> +T{
>>>  .BR getlogin ()
>>> -function is not thread-safe.
>>> -.LP
>>> -The
>>> +T}	Thread safety	MT-Unsafe locale
>>
>> Should this be "MT-Safe locale"?
>>
> 
> getlogin() is MT-Unsafe and is influenced by setlocale(),
> So "MT-Unsafe locale" is right.

Thank you for the confirmation.

Just by the way, I see that the glibc manual says of getlogin:

    MT-Unsafe race:getlogin race:utent sig:ALRM timer locale

I guess this covers some cases beyond what you document. Is that
correct?

Thanks,

Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Peng Haitao]

On 10/17/2014 02:51 PM, Michael Kerrisk (man-pages) wrote:
> [CC expanded, just in case Carlos and Alexandre have something 
> to add]
> 
> On 10/17/2014 08:29 AM, Peng Haitao wrote:
>>
>> On 10/17/2014 02:05 PM, Michael Kerrisk (man-pages) wrote:
>>> Hello Haitao,
>>>
>>> Just double checking one point. See below.
>>>
>>> On 10/17/2014 05:59 AM, Peng Haitao wrote:
>>>> Signed-off-by: Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>
>>>> ---
>>>>  man3/getlogin.3 | 24 ++++++++++++++----------
>>>>  1 file changed, 14 insertions(+), 10 deletions(-)
>>>>
>>>> diff --git a/man3/getlogin.3 b/man3/getlogin.3
>>>> index fcbd0fb..828df2b 100644
>>>> --- a/man3/getlogin.3
>>>> +++ b/man3/getlogin.3
>>>> @@ -138,19 +138,23 @@ password database file
>>>>  (traditionally \fI/etc/utmp\fP;
>>>>  some libc versions used \fI/var/adm/utmp\fP)
>>>>  .SH ATTRIBUTES
>>>> -.SS Multithreading (see pthreads(7))
>>>> -The
>>>> +For an explanation of the terms used in this section, see
>>>> +.BR attributes (7).
>>>> +.TS
>>>> +allbox;
>>>> +lb lb lb
>>>> +l l l.
>>>> +Interface	Attribute	Value
>>>> +T{
>>>>  .BR getlogin ()
>>>> -function is not thread-safe.
>>>> -.LP
>>>> -The
>>>> +T}	Thread safety	MT-Unsafe locale
>>>
>>> Should this be "MT-Safe locale"?
>>>
>>
>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>> So "MT-Unsafe locale" is right.
> 
> Thank you for the confirmation.
> 
> Just by the way, I see that the glibc manual says of getlogin:
> 
>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
> 
> I guess this covers some cases beyond what you document. Is that
> correct?
> 

Yes.
I think "race:getlogin" result in MT-Unsafe.
"race:getlogin" is equal to the sentences in manpage:
getlogin() returns a pointer to a string containing ...
The string is statically allocated and might be overwritten on
subsequent calls to this function or to cuserid().


-- 
Best Regards,
Peng

> Thanks,
> 
> Michael
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Carlos O'Donell]

On Fri, Oct 17, 2014 at 2:51 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>> So "MT-Unsafe locale" is right.
>
> Thank you for the confirmation.
>
> Just by the way, I see that the glibc manual says of getlogin:
>
>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
>
> I guess this covers some cases beyond what you document. Is that
> correct?

I haven't reviewed the technical details of this issue, but I would be
very worried if the linux-kernel man pages had different annotations
than glibc.

My expectation is that Peng should review the glibc annotations and
come talk to us if they are different from what will be documented in
the man pages.

We should not have any differences. Either we adjust one or the other,
but both should match.

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Peng Haitao]

On 10/20/2014 11:50 PM, Carlos O'Donell wrote:
> On Fri, Oct 17, 2014 at 2:51 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>>> So "MT-Unsafe locale" is right.
>>
>> Thank you for the confirmation.
>>
>> Just by the way, I see that the glibc manual says of getlogin:
>>
>>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
>>
>> I guess this covers some cases beyond what you document. Is that
>> correct?
> 
> I haven't reviewed the technical details of this issue, but I would be
> very worried if the linux-kernel man pages had different annotations
> than glibc.
> 
> My expectation is that Peng should review the glibc annotations and
> come talk to us if they are different from what will be documented in
> the man pages.
> 

We are reviewing the glibc annotations, the next step will
talk to you and Alexandre about the different annotations.

> We should not have any differences. Either we adjust one or the other,
> but both should match.
> 

This is our goal.
Thanks.

-- 
Best Regards,
Peng

> Cheers,
> Carlos.
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Carlos O'Donell]

On Tue, Oct 21, 2014 at 3:48 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
> We are reviewing the glibc annotations, the next step will
> talk to you and Alexandre about the different annotations.

In that case I would ask you to please delay any patches that have issues,
and ask Michael not to apply them, at least until we sort out the issues.

I would like to avoid conflicting documentation reaching users.

Does that make sense?

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Peng Haitao]

On 10/25/2014 07:19 AM, Carlos O'Donell wrote:
> On Tue, Oct 21, 2014 at 3:48 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
>> We are reviewing the glibc annotations, the next step will
>> talk to you and Alexandre about the different annotations.
> 
> In that case I would ask you to please delay any patches that have issues,
> and ask Michael not to apply them, at least until we sort out the issues.
> 
> I would like to avoid conflicting documentation reaching users.
> 
> Does that make sense?
> 

OK.
I has delayed any new patches that have issues and 
will check the applied patches.
Thanks.

-- 
Best Regards,
Peng

> Cheers,
> Carlos.
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

Hi Carlos,

On 10/20/2014 05:50 PM, Carlos O'Donell wrote:
> On Fri, Oct 17, 2014 at 2:51 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>>> So "MT-Unsafe locale" is right.
>>
>> Thank you for the confirmation.
>>
>> Just by the way, I see that the glibc manual says of getlogin:
>>
>>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
>>
>> I guess this covers some cases beyond what you document. Is that
>> correct?
>
> I haven't reviewed the technical details of this issue, but I would be
> very worried if the linux-kernel man pages had different annotations

s/linux-kernel/linux/ (yes, they're housed at kernel.org, but...)

> than glibc.

Agreed. They should be consistent.
 
> My expectation is that Peng should review the glibc annotations and
> come talk to us if they are different from what will be documented in
> the man pages.
> 
> We should not have any differences. Either we adjust one or the other,
> but both should match.

Yes.

By the way, how will the glibc manual maintain this info going forward?
Alexandre did great work, but I suppose he will not want to do this 
forever! How will updates be made in the future? I ask because, of 
course, man-pages has a similar issue ;-).

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

On 10/21/2014 09:48 AM, Peng Haitao wrote:
> 
> On 10/20/2014 11:50 PM, Carlos O'Donell wrote:
>> On Fri, Oct 17, 2014 at 2:51 AM, Michael Kerrisk (man-pages)
>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>>>> So "MT-Unsafe locale" is right.
>>>
>>> Thank you for the confirmation.
>>>
>>> Just by the way, I see that the glibc manual says of getlogin:
>>>
>>>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
>>>
>>> I guess this covers some cases beyond what you document. Is that
>>> correct?
>>
>> I haven't reviewed the technical details of this issue, but I would be
>> very worried if the linux-kernel man pages had different annotations
>> than glibc.
>>
>> My expectation is that Peng should review the glibc annotations and
>> come talk to us if they are different from what will be documented in
>> the man pages.
>>
> 
> We are reviewing the glibc annotations, the next step will
> talk to you and Alexandre about the different annotations.

Thanks for this, Haitao.

>> We should not have any differences. Either we adjust one or the other,
>> but both should match.
>>
> 
> This is our goal.

Good!

Do you have an idea of how long the review process might take?

Thanks,

Micheal


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

On 10/25/2014 01:19 AM, Carlos O'Donell wrote:
> On Tue, Oct 21, 2014 at 3:48 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
>> We are reviewing the glibc annotations, the next step will
>> talk to you and Alexandre about the different annotations.
> 
> In that case I would ask you to please delay any patches that have issues,
> and ask Michael not to apply them, at least until we sort out the issues.

At the moment, all of the recent updates sit in a branch.

> I would like to avoid conflicting documentation reaching users.
> 
> Does that make sense?

Yes. My preference would be to delay merging the branches into mainline
until Haitao and his colleague have a chance to review glibc vs man-pages.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

On 10/27/2014 02:50 AM, Peng Haitao wrote:
> 
> On 10/25/2014 07:19 AM, Carlos O'Donell wrote:
>> On Tue, Oct 21, 2014 at 3:48 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
>>> We are reviewing the glibc annotations, the next step will
>>> talk to you and Alexandre about the different annotations.
>>
>> In that case I would ask you to please delay any patches that have issues,
>> and ask Michael not to apply them, at least until we sort out the issues.
>>
>> I would like to avoid conflicting documentation reaching users.
>>
>> Does that make sense?
>>
> 
> OK.
> I has delayed any new patches that have issues and 
> will check the applied patches.

Thanks, Haitao! What I would like to see at some point
is a checklist of all pages that have ATTRIBUTES with an
indication of whether the markings are the same, or differ,
in man-pages versus the glibc manual.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

Hi Carlos,

Ping on my question at the end of this mail.

Cheers,

Michael


On 10/28/2014 09:34 PM, Michael Kerrisk (man-pages) wrote:
> Hi Carlos,
> 
> On 10/20/2014 05:50 PM, Carlos O'Donell wrote:
>> On Fri, Oct 17, 2014 at 2:51 AM, Michael Kerrisk (man-pages)
>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>>>> So "MT-Unsafe locale" is right.
>>>
>>> Thank you for the confirmation.
>>>
>>> Just by the way, I see that the glibc manual says of getlogin:
>>>
>>>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
>>>
>>> I guess this covers some cases beyond what you document. Is that
>>> correct?
>>
>> I haven't reviewed the technical details of this issue, but I would be
>> very worried if the linux-kernel man pages had different annotations
> 
> s/linux-kernel/linux/ (yes, they're housed at kernel.org, but...)
> 
>> than glibc.
> 
> Agreed. They should be consistent.
>  
>> My expectation is that Peng should review the glibc annotations and
>> come talk to us if they are different from what will be documented in
>> the man pages.
>>
>> We should not have any differences. Either we adjust one or the other,
>> but both should match.
> 
> Yes.
> 
> By the way, how will the glibc manual maintain this info going forward?
> Alexandre did great work, but I suppose he will not want to do this 
> forever! How will updates be made in the future? I ask because, of 
> course, man-pages has a similar issue ;-).
> 
> Cheers,
> 
> Michael
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

Hello Haitao,

Ping on my question at the end of this mail

Thanks,

Michael


On 10/28/2014 09:35 PM, Michael Kerrisk (man-pages) wrote:
> On 10/21/2014 09:48 AM, Peng Haitao wrote:
>>
>> On 10/20/2014 11:50 PM, Carlos O'Donell wrote:
>>> On Fri, Oct 17, 2014 at 2:51 AM, Michael Kerrisk (man-pages)
>>> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>>> getlogin() is MT-Unsafe and is influenced by setlocale(),
>>>>> So "MT-Unsafe locale" is right.
>>>>
>>>> Thank you for the confirmation.
>>>>
>>>> Just by the way, I see that the glibc manual says of getlogin:
>>>>
>>>>     MT-Unsafe race:getlogin race:utent sig:ALRM timer locale
>>>>
>>>> I guess this covers some cases beyond what you document. Is that
>>>> correct?
>>>
>>> I haven't reviewed the technical details of this issue, but I would be
>>> very worried if the linux-kernel man pages had different annotations
>>> than glibc.
>>>
>>> My expectation is that Peng should review the glibc annotations and
>>> come talk to us if they are different from what will be documented in
>>> the man pages.
>>>
>>
>> We are reviewing the glibc annotations, the next step will
>> talk to you and Alexandre about the different annotations.
> 
> Thanks for this, Haitao.
> 
>>> We should not have any differences. Either we adjust one or the other,
>>> but both should match.
>>>
>>
>> This is our goal.
> 
> Good!
> 
> Do you have an idea of how long the review process might take?
> 
> Thanks,
> 
> Micheal
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Carlos O'Donell]

On Tue, Dec 30, 2014 at 8:37 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Ping on my question at the end of this mail.
>> By the way, how will the glibc manual maintain this info going forward?
>> Alexandre did great work, but I suppose he will not want to do this
>> forever! How will updates be made in the future? I ask because, of
>> course, man-pages has a similar issue ;-).

You are correct that Alexandre is not responsible for everything to do
with the safety notations. I want Alex to step back and let the
community step in to support the annotations.

The information will be maintained on a per-function basis as all of
the manual has been maintained.

Developers changing functions must change the notations in the manual for now.

The goal is actually to move to annotations into the source and
extract them from the source to generate the manual. However this
process is complicated by the change in license from LGPLv2 to GFDL.
This same problem exists in GCC and there it is easily fixed by having
someone from the community become an authorized relicensing person for
the purpose of a fixed set of files that need synchronization between
LGPLv2 and GFDL. For example the source could generate a file entirely
full of macros that the texinfo references.

The more interesting question is, could we use this LGPLv2 file in the
linux man pages to keep the glibc-based information in sync?

It is questionable if this information is even copyrightable, so
perhaps the generated file will have no copyright notice nor license
and can be used by both projects?

What do you think?

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Carlos O'Donell]

On Tue, Dec 30, 2014 at 8:39 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Ping on my question at the end of this mail
>> Do you have an idea of how long the review process might take?

Given Alex's work I would estimate anywhere between 6 months and a
year for a single person to review all the functions.

The work had a narrow scope in order to complete on those timelines.
For functions that were known either to be safe, or known to be
unsafe, we made a judgement call at the time to review them or not.
You can see this by looking at the per-function safety comments.
Functions that were not documented were not reviewed, but those
missing functions were added as comments in the documentation i.e.
look for "@c FIXME these are undocumented:". There are 18 functions in
filesys.texi, 9 in libdl.texi, 118 in threads.texi, and 2 in
users.texi which are not documented and thus were skipped in this
first round. I did not want their lack of documentation to stall this
work.

I am happy to see stubs in place in the glibc manual for all of the
undocumented functions, and I'm happy to see the stubs have safety
notations.

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Michael Kerrisk (man-pages)]

On Tue, Dec 30, 2014 at 3:51 PM, Carlos O'Donell
<carlos-v2tUB8YBRSi3e3T8WW9gsA@public.gmane.org> wrote:
> On Tue, Dec 30, 2014 at 8:39 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> Ping on my question at the end of this mail
>>> Do you have an idea of how long the review process might take?
>
> Given Alex's work I would estimate anywhere between 6 months and a
> year for a single person to review all the functions.
>
> The work had a narrow scope in order to complete on those timelines.
> For functions that were known either to be safe, or known to be
> unsafe, we made a judgement call at the time to review them or not.
> You can see this by looking at the per-function safety comments.
> Functions that were not documented were not reviewed, but those
> missing functions were added as comments in the documentation i.e.
> look for "@c FIXME these are undocumented:". There are 18 functions in
> filesys.texi, 9 in libdl.texi, 118 in threads.texi, and 2 in
> users.texi which are not documented and thus were skipped in this
> first round. I did not want their lack of documentation to stall this
> work.
>
> I am happy to see stubs in place in the glibc manual for all of the
> undocumented functions, and I'm happy to see the stubs have safety
> notations.

Hi Carlos,

Maybe you have misunderstood my point. I don't expect Peng Haitao and
his colleagues to repeat Alexandre's work, but I am hoping that he
might compare the glibc annotations with the man-pages annotations,
and account for the differences/make fixes as needed.

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] getlogin.3: Reformat thread-safety information

[Carlos O'Donell]

On Tue, Dec 30, 2014 at 3:39 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Maybe you have misunderstood my point. I don't expect Peng Haitao and
> his colleagues to repeat Alexandre's work, but I am hoping that he
> might compare the glibc annotations with the man-pages annotations,
> and account for the differences/make fixes as needed.

Indeed. I did misundertand your question. Comparing the glibc manual
with the linux kernel man pages is a shorter project.

Relevant to the review is that not all functions are documented in both places.

I would be interested in seeing which functions are documented in one
but not the other, and which functions lack documentation completely
e.g. dlmopen.

Cheers,
Carlos.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html