Re: [PATCH] iswblank.3: ATTRIBUTES: Note function that is thread safe with exceptions

[Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>]

On 02/12/2014 11:31 PM, Carlos O'Donell wrote:
>>>> +The
>>>> +.BR iswblank ()
>>>> +function is thread-safe with exceptions.
>>>> +It can be safely used in multithreaded applications, as long as
>>>> +.BR setlocale (3)
>>>> +is not called to change the locale during its execution.
>>>
>>> Now that glibc 2.19 is out the door and using a standard set of
>>> "exception" markers should we try to standardize the same markers?
>>>
>>
>> Yes, maybe it is better.
>> But in Oracle Solaris's manpages, iswblank is marked "MT-Safe with exceptions".
>> I also think "MT-Safe with exceptions" is OK.
> 
> My suggestion is:
> 
> "The function iswblank() is thread safe with exceptions (locale). See
> "Safety Concepts" for more information."
> 
> Then describe the locale issue once in the "Safety Concepts" section.
> 
> This reduces duplicated text and simplifies each man page.
> 
> Users that know what "locale" means can scroll quickly, users that
> don't can look it up and learn.
> 
> Does that make sense?
> 

Your suggestion can simplify each man page, but our description make each man page clearer.

In Oracle Solaris's manpages and POSIX, when the function has exceptions,
exceptions are described in this function.

In Oracle Solaris's manpages, exceptions are described as follows:
MT-Safe with Exceptions
    See the NOTES or USAGE sections of these pages for a description of the exceptions.

Safe with Exceptions
    See the NOTES or USAGE sections of these pages for a description of the exceptions.

In POSIX, when the function has exceptions, exceptions are described in this function as follows:
The wcrtomb() function need not be thread-safe if called with a NULL ps argument.

The tmpnam() function need not be thread-safe if called with a NULL parameter. 


I don't have strong preference. If Michael and other members prefer
your suggestion, I can modify my patches.


-- 
Best Regards,
Peng

> My further suggestion is to use the same ~20 exception notes as glibc e.g.
> race, const, locale, env, hostid, sigintr, init, lock, corrupt, heap,
> dlopen, plugin, i18ln, fd, mem, sig, term, and cwd (we also have
> !posix to indicate it is known not to conform with posix).
> 
> The glibc manual is marked with them now, you can see iswblank here:
> http://www.gnu.org/software/libc/manual/html_mono/libc.html#index-iswblank-486
> 
> 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