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

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

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