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
From b30252c8e766779449f5d6ffea57c0fca6ec6d71 Mon Sep 17 00:00:00 2001 From: Peng Haitao <penght@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx> --- 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
From 3573157bcf2a6e7bfd412d6eb8944eb04f194dbf Mon Sep 17 00:00:00 2001 From: Peng Haitao <penght@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx> --- 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@xxxxxxxxxxxxx> .\" -.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
From 5b65eaf185fdd1966b34531fb8f68cfcaa76ef76 Mon Sep 17 00:00:00 2001 From: Peng Haitao <penght@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx> --- 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
