Hi Michael, Michael Kerrisk said the following on 2010-11-14 14:40: > Sorry for the very long delay in following up on this. I'm reflecting > on this a little more. My idea is that the ATTRIBUTES section might > eventually contain multiple subsections, but for now, we have just > "Multithreading", which mentions thread safety, cancellation safety, > and async-cancel-safety. And I think it might be better to place this > section just above (rather than just below) VERSIONS. So, I'd fine > tune things a little, with a patch something like this for > man-pages(7). > > === > @@ -180,6 +180,7 @@ > .\" SECURITY, > ENVIRONMENT > FILES > +ATTRIBUTES [Normally only in Sections 2, 3] > VERSIONS [Normally only in Sections 2, 3] > CONFORMING TO > NOTES > @@ -202,7 +203,7 @@ > > The following list elaborates on the contents of each of > the above sections. > -.TP 14 > +.TP 10 > .B NAME > The name of this manual page. > See > @@ -316,6 +317,28 @@ > .\" section). > .\" However, please include security information somewhere! > .TP > +.B ATTRIBUTES > +A summary of various attributes of the function(s) documented on this page, > +broken into subsections. > +The following subsections are defined: > +.sp > +.RS > +.TP > +.B "Multithreading (see pthreads(7))" > +This subsection notes attributes relating to multithreaded applications: > +.RS > +.IP * 3 > +Whether the function is thread-safe. > +.IP * > +Whether the function is a cancellation point. > +.IP * > +Whether the function is async-cancel-safe. > +.RE > +.IP > +Details of these attributes can be found in > +.BR pthreads (7). > +.RE > +.TP > .B VERSIONS > A brief summary of the Linux kernel or glibc versions where a > system call or library function appeared, > === > > Then for the individual pages, the patches might look like this: > === > --- a64l.3 2010-11-01 08:07:38.000000000 +0100 > +++ a64l.3.attr 2010-11-14 07:34:42.000000000 +0100 > @@ -56,6 +56,15 @@ > .fi > .RE > So 123 = 59*64^0 + 1*64^1 = "v/". > +.SH ATTRIBUTES > +.SS Multithreading (see pthreads(7)) > +The > +.BR l64a () > +function is not thread-safe. > +.LP > +The > +.BR a64l () > +function is thread-safe. > .SH "CONFORMING TO" > POSIX.1-2001. > .SH NOTES > === > > How does that sound? > It sounds good. I will post more patches in this format. > Now, before we apply a vast number of patches, it might be good to > build a list of pages and the kinds of changes that would be needed > for each (look at the latest pthreads(7) page in git for some starting > points on functions that fall into the various categories; possibly > your research has revealed additional information about the actual > details in glibc). Could you come up with such lists? (They don't need > to be complete or comprehensive, but it could be helpful to have a > picture of where we might start making changes.) > Do you mean the attached list? > Thanks, > > Michael > -- Best Regards, Peng Haitao
Safe functions' list: closelog dladdr endutent endutxent _flushlbf gai_cancel initstate lckpwdf openlog putchar rand random setstate srand srandom ulckpwdf unsetenv Safe with exceptions functions' list: dl_iterate_phdr getutent_r getutid_r getutline_r pututline pututxline setutent setutxent Unsafe functions' list: abort bindresvport bsd_signal clearerr_unlocked drand48 ecvt erand48 ether_aton fcloseall feof_unlocked ferror_unlocked fflush_unlocked fputc_unlocked fread_unlocked __fsetlocking hsearch jrand48 l64a lcong48 localeconv longjmp lrand48 mrand48 nrand48 profil pthread_exit pthread_setcancelstate pthread_setcanceltype pthread_testcancel ptsname putchar_unlocked putc_unlocked seed48 setjmp siginterrupt siglongjmp srand48 ssignal strfry strtok MT-Safe functions' list: a64l abs adjtime aio_error aio_return alloca argz_count argz_extract argz_next argz_stringify asinh asinhf asinhl atan atanf atanl backtrace_symbols_fd basename bcmp bcopy bzero catgets cbc_crypt cbrt cbrtf cbrtl ceil ceilf ceill cexp cexpf cexpl cfgetispeed cfgetospeed cfmakeraw cfsetispeed cfsetospeed cfsetspeed cimag cimagf cimagl clearerr clnt_control clnt_geterr clock_getcpuclockid clock_getres clock_gettime clock_settime conj conjf conjl copysign copysignf copysignl cos cosf cosl cproj cprojf cprojl creal crealf creall daemon des_setparity difftime dirfd dirname div dn_comp drand48_r dysize eaccess ecb_crypt ecvt_r envz_entry envz_get envz_strip erand48_r erf erfc erfcf erfcl erff erfl ether_aton_r ether_line euidaccess eventfd_read eventfd_write execv expm1 expm1f expm1l fabs fabsf fabsl __fbufsize FD_CLR fdim fdimf fdiml FD_ISSET feclearexcept fedisableexcept feenableexcept fegetenv fegetexcept fegetexceptflag fegetround feholdexcept feof feraiseexcept ferror fesetenv fesetexceptflag fesetround fetestexcept feupdateenv fflush ffs ffsl ffsll fileno fileno_unlocked finite finitef finitel __flbf flockfile floor floorf floorl fma fmaf fmal fmax fmaxf fmaxl fmin fminf fminl fpathconf fpclassify __fpending fputc fread __freadable __freading frexp frexpf frexpl fstatvfs ftime ftok ftrylockfile fts_set funlockfile futimens futimes __fwritable __fwriting gai_error getdirentries getloadavg getpt getsubopt getutmp getutmpx getw gnu_dev_major gnu_dev_makedev gnu_dev_minor gnu_get_libc_release gnu_get_libc_version gsignal hasmntopt hsearch_r htonl htons iconv ilogb ilogbf ilogbl imaxabs imaxdiv index inet_lnaof inet_makeaddr inet_netof inet_network inet_pton initstate_r insque isascii isatty isfinite isgreater isgreaterequal isinf isinff isinfl isless islessequal islessgreater isnan isnanf isnanl isnormal isunordered iswctype jrand48_r klogctl labs lcong48_r ldexp ldexpf ldexpl ldiv llabs lldiv llrint llrintf llrintl llround llroundf llroundl lockf log1p log1pf log1pl logb logbf logbl login_tty logwtmp lrand48_r lrint lrintf lrintl lround lroundf lroundl lseek64 lutimes makecontext matherr mbsinit memccpy memchr memcmp memcpy memfrob memmem memmove mempcpy memrchr memset mkdtemp mkfifo mkfifoat mkostemp mkostemps mkstemp mkstemps mktemp mmap64 modf modff modfl mq_close mq_getattr mq_open mq_receive mq_send mq_setattr mq_timedreceive mq_timedsend mq_unlink mrand48_r nearbyint nearbyintf nearbyintl nextafter nextafterf nextafterl nexttoward nexttowardf nexttowardl nrand48_r ntohl ntohs passwd2des pathconf posix_fallocate posix_openpt pthread_attr_getdetachstate pthread_attr_getguardsize pthread_attr_getinheritsched pthread_attr_getschedparam pthread_attr_getschedpolicy pthread_attr_getscope pthread_attr_getstack pthread_attr_getstackaddr pthread_attr_getstacksize pthread_attr_init pthread_attr_setdetachstate pthread_attr_setguardsize pthread_attr_setinheritsched pthread_attr_setschedparam pthread_attr_setschedpolicy pthread_attr_setscope pthread_attr_setstack pthread_attr_setstackaddr pthread_attr_setstacksize pthread_cleanup_push pthread_equal pthread_getaffinity_np pthread_getconcurrency pthread_getcpuclockid pthread_getschedparam pthread_kill pthread_kill_other_threads_np pthread_self pthread_setconcurrency pthread_setschedparam pthread_setschedprio pthread_sigmask pthread_yield ptsname_r putc raise random_r rand_r rawmemchr readdir readdir_r remove remque remquo remquof remquol rewinddir rindex rint rintf rintl round roundf roundl rresvport rtime scalbln scalblnf scalblnl scalbn scalbnf scalbnl sched_getcpu seed48_r seekdir sem_destroy sem_getvalue sem_init sem_post sem_timedwait sem_trywait sem_unlink sem_wait setbuf setbuffer sethostid setlinebuf setlogmask setstate_r setvbuf sigaddset sigandset sigblock sigdelset sigemptyset sigfillset siggetmask sighold sigignore sigisemptyset sigismember signbit significand significandf significandl sigorset sigpause sigrelse sigset sigsetmask sigstack sigvec sigwait sin sincos sincosf sincosl sinf sinl sleep sockatmark srand48_r srandom_r statvfs stpcpy stpncpy strcat strchr strchrnul strcmp strcpy strcspn strdupa strlen strncat strncmp strncpy strndupa strnlen strpbrk strrchr strsep strspn strstr strtok_r strverscmp swab swapcontext system sysv_signal tan tanf tanh tanhf tanhl tanl tcdrain tcflow tcflush tcgetattr tcgetpgrp tcgetsid tcsendbreak tcsetattr tcsetpgrp telldir toascii towctrans trunc truncf truncl ualarm ungetc ungetwc unlockpt updwtmp updwtmpx usleep va_arg va_copy va_end va_start versionsort vlimit vtimes wcpcpy wcpncpy wcscat wcschr wcscmp wcscpy wcscspn wcslen wcsncat wcsncmp wcsncpy wcsnlen wcspbrk wcsrchr wcsspn wcsstr wcstok wmemchr wmemcmp wmemcpy wmemmove wmempcpy wmemset xdrmem_create xdrstdio_create xdr_void MT-Safe with exceptions functions' list: atof atoi atol atoll bsearch clnt_call clnt_destroy clnt_freeres ctermid inet_addr inet_aton isalnum isalpha isblank iscntrl isdigit isgraph islower isprint ispunct isspace isupper iswalnum iswalpha iswblank iswcntrl iswdigit iswgraph iswlower iswprint iswpunct iswspace iswupper iswxdigit isxdigit lfind lsearch mbstowcs nl_langinfo pthread_cleanup_pop sgetspent_r strcasecmp strcasestr strncasecmp strtod strtof strtoimax strtol strtold strtoll strtoq strtoul strtoull strtoumax strtouq svcerr_auth svcerr_decode svcerr_noproc svcerr_noprog svcerr_progvers svcerr_systemerr svcerr_weakauth svc_sendreply tdestroy tfind tolower toupper towlower towupper twalk wcscasecmp wcsncasecmp wcstoimax wcstoumax wcswidth wctrans wctype wcwidth xdr_bool xdr_callhdr xdr_char xdr_double xdr_enum xdr_float xdr_free xdr_int xdr_long xdr_opaque xdr_pmap xdrrec_endofrecord xdrrec_eof xdrrec_skiprecord xdr_rejected_reply xdr_replymsg xdr_short xdr_u_char xdr_u_int xdr_u_long xdr_union xdr_u_short xdr_vector
