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

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

[Peng Haitao]

[-- Attachment #1: Type: text/plain, Size: 918 bytes --]

Hi Michael and all,

When doing multithreaded programming, it is necessary to know the thread-safety
levels of the library functions. However, there is little thread-safety
information in current man-pages. And the lack of information often makes us
confused when programming in multithreaded environment.

If we could add information about functions' thread-safety levels based on
POSIX standard into man-pages, just like man-pages in Solaris, it will be
more helpful to programmers who are doing multithreaded programming with GLIBC. 

For function whose thread-safety level is clear, I have made several patches
which contain detailed descriptions of the thread-safety levels. The attached
patches can be as samples. If necessary, I will gradually make more patches
to enhance thread-safety information in man-pages. So what do you think?

I am looking forward to your feedback soon!

-- 
Best Regards,
Peng Haitao

[-- Attachment #2: 0002-hsearch.3-Add-description-of-the-functions-are-not.patch --]
[-- Type: text/plain, Size: 1473 bytes --]

From 4463662ef2d9c94803dcdbe3290ad1969a07439b Mon Sep 17 00:00:00 2001
From: Peng Haitao <penght@cn.fujitsu.com>
Date: Tue, 31 Aug 2010 14:13:37 +0800
Subject: [PATCH] hsearch.3: Add description of the functions are not thread-safe

The three functions hcreate(), hdestroy() and hsearch() use a global space
for storing the table, so they are not thread-safe.

Signed-off-by: Peng Haitao <penght@cn.fujitsu.com>
---
 man3/hsearch.3 |    9 ++++++++-
 1 files changed, 8 insertions(+), 1 deletions(-)

diff --git a/man3/hsearch.3 b/man3/hsearch.3
index b392b55..f902aae 100644
--- a/man3/hsearch.3
+++ b/man3/hsearch.3
@@ -32,7 +32,7 @@
 .\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
 .\"     Timothy S. Nelson <wayland@wayland.id.au>
 .\"
-.TH HSEARCH 3 2008-10-06 "GNU" "Linux Programmer's Manual"
+.TH HSEARCH 3 2010-08-31 "GNU" "Linux Programmer's Manual"
 .SH NAME
 hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
 hsearch_r \- hash table management
@@ -270,6 +270,13 @@ rather than creating a single table whose lifetime
 matches that of the program),
 then the program must maintain bookkeeping data structures that
 allow it to free them.
+.PP
+The three functions
+.BR hcreate (),
+.BR hsearch ()
+and
+.BR hdestroy ()
+use a global space for storing the table, so they are not thread-safe.
 .SH BUGS
 SVr4 and POSIX.1-2001 specify that \fIaction\fP
 is significant only for unsuccessful searches, so that an \fBENTER\fP
-- 
1.6.0.1


[-- Attachment #3: 0001-a64l.3-Add-description-of-the-function-is-not-threa.patch --]
[-- Type: text/plain, Size: 1030 bytes --]

From a66a5b7209897b92cf64755edd31b9c77eb7c1aa Mon Sep 17 00:00:00 2001
From: Peng Haitao <penght@cn.fujitsu.com>
Date: Tue, 31 Aug 2010 14:13:28 +0800
Subject: [PATCH] a64l.3: Add description of the function is not thread-safe

The function l64a() uses a static variable "result", so it is not thread-safe.

Signed-off-by: Peng Haitao <penght@cn.fujitsu.com>
---
 man3/a64l.3 |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/man3/a64l.3 b/man3/a64l.3
index 0c10651..b14550d 100644
--- a/man3/a64l.3
+++ b/man3/a64l.3
@@ -3,7 +3,7 @@
 .\"
 .\" Corrected, aeb, 2002-05-30
 .\"
-.TH A64L 3 2010-08-29 "" "Linux Programmer's Manual"
+.TH A64L 3 2010-08-31 "" "Linux Programmer's Manual"
 .SH NAME
 a64l, l64a \- convert between long and base-64
 .SH SYNOPSIS
@@ -72,6 +72,10 @@ These functions are broken in glibc before 2.2.5
 .LP
 This is not the encoding used by
 .BR uuencode (1).
+.LP
+The
+.BR l64a ()
+function is not thread-safe.
 .SH "SEE ALSO"
 .BR uuencode (1),
 .\" .BR itoa (3),
-- 
1.6.0.1

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

[Michael Kerrisk]

Hello Peng Haitao,

On Tue, Aug 31, 2010 at 8:18 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
> Hi Michael and all,
>
> When doing multithreaded programming, it is necessary to know the thread-safety
> levels of the library functions.

Yes.

> However, there is little thread-safety
> information in current man-pages.

At the moment, there is just pthreads(7), really.

> And the lack of information often makes us
> confused when programming in multithreaded environment.
>
> If we could add information about functions' thread-safety levels based on
> POSIX standard into man-pages, just like man-pages in Solaris, it will be
> more helpful to programmers who are doing multithreaded programming with GLIBC.
>
> For function whose thread-safety level is clear, I have made several patches
> which contain detailed descriptions of the thread-safety levels. The attached
> patches can be as samples. If necessary, I will gradually make more patches
> to enhance thread-safety information in man-pages. So what do you think?
>
> I am looking forward to your feedback soon!

The idea is good, but clearly there'd be a lot of work to do. Looking
at Sun's attr(5) page
http://docs.sun.com/app/docs/doc/816-0220/6m6nkoroc?l=en&a=view
suggests to me that we might be better to do this more formally, since
there are a number of attributes that may be of interest to
programmers, e.g.,

thread-safetcy
reentrant/nonreentrant
async-signal-safety
cancelation safety

By "formal" I mean that we could have a section "ATTRIBUTES" that
lists such attributes. That section could fall between VERSIONS and
CONFORMING TO (see man-pages(7)). To start with, you might write
patches that document just thread-safety, but later other pieces might
get added as well (e.g., async-signal-safety).

What do you think? If this sounds sensible, write one or two patches
in the style I suggest, and then we can discuss furtehr.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
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

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

[Peng Haitao]

[-- Attachment #1: Type: text/plain, Size: 821 bytes --]

Hi Michael,

Michael Kerrisk said the following on 2010-9-11 12:06:
> By "formal" I mean that we could have a section "ATTRIBUTES" that
> lists such attributes. That section could fall between VERSIONS and
> CONFORMING TO (see man-pages(7)). To start with, you might write
> patches that document just thread-safety, but later other pieces might
> get added as well (e.g., async-signal-safety).
> 
> What do you think? If this sounds sensible, write one or two patches
> in the style I suggest, and then we can discuss furtehr.
>  

  I think your proposal is good. So, I make two patches in your style, 
they are 0001* and 0002*. The third patch is used to add description
of "ATTRIBUTES" into man-pages(7).

  What's your opinion? If you agree with me, I'll gradually make more
patches. 

-- 
Best Regards,
Peng Haitao

[-- Attachment #2: 0001-a64l.3-Add-description-of-the-function-thread-safe.patch --]
[-- Type: text/plain, Size: 1043 bytes --]

From b30252c8e766779449f5d6ffea57c0fca6ec6d71 Mon Sep 17 00:00:00 2001
From: Peng Haitao <penght@cn.fujitsu.com>
Date: Mon, 13 Sep 2010 16:31:00 +0800
Subject: [PATCH] a64l.3: Add description of the function' thread-safety

The function l64a() uses a static variable "result", so it is not thread-safe.

Signed-off-by: Peng Haitao <penght@cn.fujitsu.com>
---
 man3/a64l.3 |   10 +++++++++-
 1 files changed, 9 insertions(+), 1 deletions(-)

diff --git a/man3/a64l.3 b/man3/a64l.3
index 0c10651..6b9b7f1 100644
--- a/man3/a64l.3
+++ b/man3/a64l.3
@@ -3,7 +3,7 @@
 .\"
 .\" Corrected, aeb, 2002-05-30
 .\"
-.TH A64L 3 2010-08-29 "" "Linux Programmer's Manual"
+.TH A64L 3 2010-09-13 "" "Linux Programmer's Manual"
 .SH NAME
 a64l, l64a \- convert between long and base-64
 .SH SYNOPSIS
@@ -50,6 +50,14 @@ a-z	represent 38-63
 .fi
 .RE
 So 123 = 59*64^0 + 1*64^1 = "v/".
+.SH "ATTRIBUTES"
+The
+.BR l64a ()
+function is not thread-safe.
+.LP
+The
+.BR a64l ()
+function is thread-safe.
 .SH "CONFORMING TO"
 POSIX.1-2001.
 .SH NOTES
-- 
1.6.0.1


[-- Attachment #3: 0002-hsearch.3-Add-description-of-the-functions-thread.patch --]
[-- Type: text/plain, Size: 1428 bytes --]

From 3573157bcf2a6e7bfd412d6eb8944eb04f194dbf Mon Sep 17 00:00:00 2001
From: Peng Haitao <penght@cn.fujitsu.com>
Date: Mon, 13 Sep 2010 16:31:09 +0800
Subject: [PATCH] hsearch.3: Add description of the functions' thread-safety

The three functions hcreate(), hdestroy() and hsearch() use a global space
for storing the table, so they are not thread-safe.

Signed-off-by: Peng Haitao <penght@cn.fujitsu.com>
---
 man3/hsearch.3 |   16 +++++++++++++++-
 1 files changed, 15 insertions(+), 1 deletions(-)

diff --git a/man3/hsearch.3 b/man3/hsearch.3
index b392b55..3a448d8 100644
--- a/man3/hsearch.3
+++ b/man3/hsearch.3
@@ -32,7 +32,7 @@
 .\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
 .\"     Timothy S. Nelson <wayland@wayland.id.au>
 .\"
-.TH HSEARCH 3 2008-10-06 "GNU" "Linux Programmer's Manual"
+.TH HSEARCH 3 2010-09-13 "GNU" "Linux Programmer's Manual"
 .SH NAME
 hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
 hsearch_r \- hash table management
@@ -232,6 +232,20 @@ was not found in the table.
 POSIX.1-2001 only specifies the
 .B ENOMEM
 error.
+.SH "ATTRIBUTES"
+The three functions
+.BR hcreate (),
+.BR hsearch (),
+and
+.BR hdestroy ()
+use a global space for storing the table, so they are not thread-safe.
+.PP
+The three functions
+.BR hcreate_r (),
+.BR hsearch_r (),
+and
+.BR hdestroy_r ()
+are thread-safe.
 .SH "CONFORMING TO"
 The functions
 .BR hcreate (),
-- 
1.6.0.1


[-- Attachment #4: 0003-man-pages.7-Add-description-of-ATTRIBUTES.patch --]
[-- Type: text/plain, Size: 1609 bytes --]

From 5b65eaf185fdd1966b34531fb8f68cfcaa76ef76 Mon Sep 17 00:00:00 2001
From: Peng Haitao <penght@cn.fujitsu.com>
Date: Mon, 13 Sep 2010 16:31:17 +0800
Subject: [PATCH] man-pages.7: Add description of "ATTRIBUTES"

"ATTRIBUTES" section gives the information of thread-safety.

Signed-off-by: Peng Haitao <penght@cn.fujitsu.com>
---
 man7/man-pages.7 |   18 +++++++++++++++++-
 1 files changed, 17 insertions(+), 1 deletions(-)

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 261e556..59004d6 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -25,7 +25,7 @@
 .\" 2007-05-30 created by mtk, using text from old man.7 plus
 .\" rewrites and additional text.
 .\"
-.TH MAN-PAGES 7 2008-10-28 "Linux" "Linux Programmer's Manual"
+.TH MAN-PAGES 7 2010-09-13 "Linux" "Linux Programmer's Manual"
 .SH NAME
 man-pages \- conventions for writing Linux man pages
 .SH SYNOPSIS
@@ -181,6 +181,7 @@ ERRORS             [Typically only in Sections 2, 3]
 ENVIRONMENT
 FILES
 VERSIONS           [Normally only in Sections 2, 3]
+ATTRIBUTES         [Normally only in Sections 2, 3]
 CONFORMING TO
 NOTES
 BUGS
@@ -338,6 +339,21 @@ The
 manual page also provides information about kernel versions
 in which various system calls first appeared.
 .TP
+.B ATTRIBUTES
+For Section 2 and 3 manual pages, this section gives a
+number of attributes, e.g.,
+.RS
+.TS
+allbox;
+c.
+thread-safety
+reentrant/non-reentrant
+async-signal-safety
+cancelation safety
+.TE
+.RE
+.TP
+.sp
 .B CONFORMING TO
 describes any standards or conventions that relate to the function
 or command described by the manual page.
-- 
1.6.0.1

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

[Peng Haitao]

Hi Michael,

Peng Haitao said the following on 2010-9-13 17:19:
> 
>   I think your proposal is good. So, I make two patches in your style, 
> they are 0001* and 0002*. The third patch is used to add description
> of "ATTRIBUTES" into man-pages(7).
> 

any feedback?
Thanks.

-- 
Best Regards,
Peng Haitao

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

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

[Michael Kerrisk]

Hello Peng,

On Mon, Sep 13, 2010 at 11:19 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
> Hi Michael,
>
> Michael Kerrisk said the following on 2010-9-11 12:06:
>> By "formal" I mean that we could have a section "ATTRIBUTES" that
>> lists such attributes. That section could fall between VERSIONS and
>> CONFORMING TO (see man-pages(7)). To start with, you might write
>> patches that document just thread-safety, but later other pieces might
>> get added as well (e.g., async-signal-safety).
>>
>> What do you think? If this sounds sensible, write one or two patches
>> in the style I suggest, and then we can discuss furtehr.
>>
>
>  I think your proposal is good. So, I make two patches in your style,
> they are 0001* and 0002*. The third patch is used to add description
> of "ATTRIBUTES" into man-pages(7).
>
>  What's your opinion? If you agree with me, I'll gradually make more
> patches.

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?

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.)

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
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

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

[Peng Haitao]

[-- Attachment #1: Type: text/plain, Size: 2976 bytes --]

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

[-- Attachment #2: man3_list --]
[-- Type: text/plain, Size: 7255 bytes --]

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

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

[Michael Kerrisk]

Hi Peng.

On Mon, Nov 15, 2010 at 7:37 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
> Hi Michael,
>
> Michael Kerrisk said the following on 2010-11-14 14:40:

[...]

>> 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. That looks promising. Could you elaborate on the meanings of
the headings, and also explain how you came up with the lists?

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
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

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

[Peng Haitao]

Hi Michael,

> Thanks. That looks promising. Could you elaborate on the meanings of
> the headings, and also explain how you came up with the lists?
> 

Because we have classified lots of the functions into following 
classifications: Unsafe, Safe, Safe with Exceptions, MT-Safe, 
MT-Safe with Exceptions.

The classifications are Based on the thread-safety levels defined in  
Solaris operating system, the meanings are as follows:

- Unsafe: The function contains global or static data that is not 
protected. Accesses by multiple threads will produce unpredictable 
(and probably incorrect) results.

- Safe: The function can be called by multiple threads and will return 
correct results. The function is still allowed to have global effects 
that are seen by all threads, however. It is also allowed to serialize 
all accesses, by protecting the entire function with a lock.

- Safe with Exceptions: The function is safe, except under certain 
circumstances.

- MT-Safe: The function is fully prepared for multi-threaded access. 
All global and static data is protected with locks, and some degree 
of concurrency can be achieved within the function.

- MT-Safe with Exceptions: The function is MT-Safe, except under 
certain circumstances.

-- 
Best Regards,
Peng Haitao

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

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

[Michael Kerrisk]

Hi Peng,

On Mon, Nov 15, 2010 at 8:15 AM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> wrote:
> Hi Michael,
>
>> Thanks. That looks promising. Could you elaborate on the meanings of
>> the headings, and also explain how you came up with the lists?
>>
>
> Because we have classified lots of the functions into following
> classifications: Unsafe, Safe, Safe with Exceptions, MT-Safe,
> MT-Safe with Exceptions.

Okay -- I'll rephrase the question... ;-). By what means  did you work
out the classifications?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
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

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

[Peng Haitao]

Hi Michael,

>>> the headings, and also explain how you came up with the lists?
>>>
>>
>> Because we have classified lots of the functions into following
>> classifications: Unsafe, Safe, Safe with Exceptions, MT-Safe,
>> MT-Safe with Exceptions.
> 
> Okay -- I'll rephrase the question... ;-). By what means  did you work
> out the classifications?
> 

The classifications are based on the thread-safety levels defined in  
Solaris operating system, please refer to Sun's attr(5) page:
http://docs.sun.com/app/docs/doc/816-0220/6m6nkoroc?l=en&a=view#MT-Level

Based on the classifications and POSIX standard, I classify functions 
by reading source code.

-- 
Best Regards,
Peng Haitao

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