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

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

On 06/11/2014 04:30 PM, Michael Kerrisk (man-pages) wrote:
...
> Practically speaking, I think this means:
> 
> 1. We'd create an attributes(7) man page that has much of the same
> information as in the glibc manual nodes listed above. If needed we
> can rewrite to avoid any licensing issues. On the other hand, if
> Alex(?) wants to make that text available under a suitable license
> (e.g., one of those at
> https://www.kernel.org/doc/man-pages/licenses.html). (Note, GFDL
> doesn't work for man-pages, as explained on that web page.)
> 
> 2. We redesign the ATTRIBUTES section that we use in man-pages. I
> think it would make sense to use something like the Solaris
> attributes(5) approach, where there is a table of safety information.
> That table would be supplemented by notes, as needed. Thus, we might
> have something like:
> 
>     ATTRIBUTES
> 
>         See attributes(7).
> 
>         +-----------+---------------+-----------+
>         | Interface | Attribute     | Value     |
>         +-----------+---------------+-----------+
>         | l64a()    | Thread-safety | MT-Unsafe |
>         +-----------+---------------+-----------+
> 
>         +-------------------+---------------+---------+
>        | Interface         | Attribute     | Value   |
>        +-------------------+---------------+---------+
>         | bindresvport()    | Thread-safety | MT-Safe |
>         +-------------------+---------------+---------+
> 
>         Before glibc 2.17, the bindresvport() function uses a static variable
>         that is not protected, so it is not thread-safe.
>         Since glibc 2.17, it protects the static variable with a lock,
>         and is thus MT-Safe.
> 
>         +----------------------------+---------------+----------------+
>         | Interface                  | Attribute     | Value          |
>         +----------------------------+---------------+----------------+
>         | atoi(), atol(), atoll()    | Thread-safety | MT-Safe locale |
>         +----------------------------+---------------+----------------+
> 
>         +--------------------------+---------------------+---------+
>         | Interface                | Attribute           | Value   |
>         +--------------------------+---------------------+---------+
>         | pthread_setcancelstate() | Async-cancel-safety | AC-Safe |
>         +--------------------------+---------------------+---------+
> 
> An alternative approach would be to have subsections under ATTRIBUES,
> with separate tables for Thread-safety, Async-signal-safety, and
> Async-cancel-safety. Something like this:
> 
>     ATTRIBUTES
> 
>             See attributes(7).
> 
>         Thread-safety
>             +-------------------+---------+
>             | Interface         | Value   |
>             +-------------------+---------+
>             | bindresvport()    | MT-Safe |
>             +-------------------+---------+
> 
>             Before glibc 2.17, the bindresvport() function uses a static
>             variable that is not protected, so it is not thread-safe.
>             Since glibc 2.17, it protects the static variable with a lock,
>             and is thus MT-Safe.
> 
>         Async-cancel-safety
> 
>             +--------------------------+---------+
>             | Interface                | Value   |
>             +--------------------------+---------+
>             | pthread_setcancelstate() | AC-Safe |
>             +--------------------------+---------+
> 
> Does one of those approaches eem okay? Haitao, Qian Lei, what do you
> think? (I appreciate that there's a lot of pages to be fixed to follow
> this new approach: I'd do that, though you could help if you want.)
> 

I select the first approach.
If the approach is decided，Qian and I will help to fix to follow the new approach.
Thanks.


-- 
Best Regards,
Peng

> Cheers,
> 
> 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