Hi Carlos, On Wed, Jun 11, 2014 at 4:59 PM, Carlos O'Donell <carlos@xxxxxxxxxxxxxxxx> wrote: > On Wed, Jun 11, 2014 at 4:30 AM, Michael Kerrisk (man-pages) > <mtk.manpages@xxxxxxxxx> wrote: >> Hi Carlos, Haitao, Qian Lei, Alex, >> >> Following up on this at last. Sorry for the delay. > > I also meant to respond, thanks for taking the initiative. > >> On Tue, Feb 25, 2014 at 6:28 PM, Carlos O'Donell >> <carlos@xxxxxxxxxxxxxxxx> wrote: >>> On Sun, Feb 23, 2014 at 5:16 AM, Michael Kerrisk (man-pages) >>> <mtk.manpages@xxxxxxxxx> wrote: >>>>> 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 >>>> >>>> I realize I could did through a lot of archived mail and answer these >>>> questions, but I hope you can save me some time. >>> >>> My pleasure. >>> >>>> 1. How was the information about MT-Safety etc derived. I'm assuming a >>>> lot of arduous manual inspection, right? (Or was there some automation >>>> involved?) >>> >>> No automation. Manual inspection. It took Alexandre roughly a year to >>> get through ~1000+ functions. After a while though the previous safety >>> notes help you out immensely as you don't need to recurse deeply in a >>> function when you know the properties of the functions you are >>> calling. >>> >>>> 2. Does the glibc manual document the actual or the desired state of >>>> the functions wrt to MT-Safety? Where these differ, does the manual >>>> document that? >>> >>> The noes are preliminary so we make no promises. >>> >>> We document the actual state (not perfectly true, but it's the >>> statement we want to make). >>> >>> We do not presently indicate what is the desired state. >> >> Okay. >> >>> Some interfaces deviate from the standards, and in some cases we have >>> started marking that e.g. !posix. >>> >>> However, we need to do a second pass to ensure that: >>> >>> (a) We transition from preliminary to full guarantees about the API. >>> >>> -- When we do this transition we will look at what the desired >>> guarantee is for each function. >>> >>> For example we may *never* guarantee setlocale is MT-safe, simply >>> because the consequence of making it safe slows down every other >>> function that uses locales. >>> >>> (b) We document the standard requirement for reference. >>> >>> (c) We add texinfo comments when we have notes to describe why we >>> deviate from the standard. >> >> Okay. >> >> Is there a schedule/plan to bring these notes to something more definitive? > > At present there is no schedule to make things more definitive. > > My rough timeline is to block out time for this work in 2016 (as 2015 > is planned out). > > I know it sounds like a long time, but it's serious work to review > these functions and even more serious work to get upstream to commit > to them in their present form. Obviously some functions will be easy > to mark, while others harder. The timeframe is easily understandable to me, actually. It's a big job. [...] >> 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.) > > Would it be OK if Alex just posted a dump of his text (he's and I are > the authors of all the text) with an alternate license such that you > can just copy-edit from that? That'd be perfect. My preference is the verbatim license, but any of the other licenses at https://www.kernel.org/doc/man-pages/licenses.html would also work fine. >> 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 | >> +-------------------+---------------+---------+ > > Looks awesome. I agree Solaris had a good layout. Okay. >> 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 | >> +----------------------------+---------------+----------------+ > > Looks good. Where `locale' means the agreed upon definition in the > attributes(7) section. > >> +--------------------------+---------------------+---------+ >> | Interface | Attribute | Value | >> +--------------------------+---------------------+---------+ >> | pthread_setcancelstate() | Async-cancel-safety | AC-Safe | >> +--------------------------+---------------------+---------+ > > Looks good to me. > >> 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 agree with Peng, I like the first approach of a single table. Alrighty, I need to hack a few of the pages to see that this approach works, and then we can make the change wholesale. > We should also evaluate the approach of adding the glibc version to > the table if and when the version change would change the result e.g. > the table lists the historical values. Good point. I'll give that a little thought. 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
