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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
