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

[Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>]

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