Re: [patch] qsort.3: document qsort_r

[Ben <software@xxxxxxxxx>]

On Tue, 2012-03-06 at 08:00 +1300, Michael Kerrisk (man-pages) wrote: 
> Mark, Ben,
> 
> Mark submitted an initial patch that I have been slow to respond to.
> Mark, is there anything in Ben's patch that could be included in your
> patch?

I included a reference to the feature test macros used to enable
qsort_r.  That's pretty much the only significant difference.  The other
changes were to alter the spacing in the SYNOPSIS section to reflect the
more usual style for function pointers.

I've attached a new patch that (a) has all of Mark's patch, (b) a
reference to the feature test macros, (c) the two spacing changes in the
type of the function pointers, and (d) replacing "sorts an array" with
"sort and array" which, I think, is better when two functions are being
described.  I hope that helps.  If it doesn't please feel free to ignore
it.

-- 
Ben.

--- qsort.3.orig	2012-03-05 21:38:09.000000000 +0000
+++ qsort.3	2012-03-05 21:48:40.000000000 +0000
@@ -28,19 +28,35 @@
 .\" Modified 1993-03-29, David Metcalfe
 .\" Modified 1993-07-24, Rik Faith (faith@xxxxxxxxxx)
 .\" 2006-01-15, mtk, Added example program.
+.\" Modified 2011-10-24, Mark R. Bannister (cambridge@xxxxxxxxxxxxxxxxxxxxx)
+.\"				to add qsort_r()
+.\" Modified 2012-03-05, Ben Bacarisse (software@xxxxxxxxx) added
+.\"                      reference to feature test macro for qsort_r.
 .\"
-.\" FIXME glibc 2.8 added qsort_r(), which needs to be documented.
-.\"
-.TH QSORT 3 2009-09-15 "" "Linux Programmer's Manual"
+.TH QSORT 3 2012-03-05 "" "Linux Programmer's Manual"
 .SH NAME
-qsort \- sorts an array
+qsort, qsort_r \- sort an array
 .SH SYNOPSIS
 .nf
 .B #include <stdlib.h>
 .sp
 .BI "void qsort(void *" base ", size_t " nmemb ", size_t " size ,
-.BI "           int(*" compar ")(const void *, const void *));"
+.BI "           int (*" compar ")(const void *, const void *));"
+.sp
+.BI "void qsort_r(void *" base ", size_t " nmemb ", size_t " size ,
+.BI "           int (*" compar ")(const void *, const void *, void *),"
+.BI "           void *" arg ");"
 .fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.ad l
+.BR qsort_r ():
+_GNU_SOURCE
+.ad b
 .SH DESCRIPTION
 The
 .BR qsort ()
@@ -58,16 +74,34 @@
 less than, equal to, or greater than the second.
 If two members compare
 as equal, their order in the sorted array is undefined.
+.PP
+The
+.BR qsort_r ()
+function is identical to
+.BR qsort ()
+except that the comparison function
+.I compar
+takes a third argument.  A pointer is passed to the comparison function via
+.IR arg .
+In this way, the comparison function does not need to use global variables to
+pass through arbitrary arguments, and is therefore re-entrant and safe to
+use in threads.
 .SH "RETURN VALUE"
 The
 .BR qsort ()
-function returns no value.
+and
+.BR qsort_r ()
+functions return no value.
 .SH "CONFORMING TO"
-SVr4, 4.3BSD, C89, C99.
+The
+.BR qsort ()
+function conforms to SVr4, 4.3BSD, C89, C99.
 .SH NOTES
 Library routines suitable for use as the
 .I compar
-argument include
+argument to
+.BR qsort ()
+include
 .BR alphasort (3)
 and
 .BR versionsort (3).