Re: About thread-safety information in library functions' man-pages

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux