[patch] qsort.3: document qsort_r

[Ben <software-QW8DL1zPdzBaa/9Udqfwiw@public.gmane.org>]

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

Following a discussion on comp.lang.c, I noticed that glibc's qsort_r is
not documented in the man pages.  Following the model of strtok_r (and
the FIXME in qsort.3) I include a patch that adds qsort_r to the man
page for qsort (inline and as an attachment):

--- qsort.3.orig	2011-12-29 16:12:51.000000000 +0000
+++ qsort.3	2011-12-29 15:30:33.000000000 +0000
@@ -28,19 +28,32 @@
 .\" Modified 1993-03-29, David Metcalfe
 .\" Modified 1993-07-24, Rik Faith (faith-+5Oa3zvhR2o3uPMLIKxrzw@public.gmane.org)
 .\" 2006-01-15, mtk, Added example program.
+.\" Modified 2011-12-29, Ben Bacarisse (software-QW8DL1zPdzBaa/9Udqfwiw@public.gmane.org), 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 2011-12-29 "" "Linux Programmer's Manual"
 .SH NAME
-qsort \- sorts an array
+qsort, qsort_r \- sorts 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 *" data ");"
 .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,12 +71,29 @@
 less than, equal to, or greater than the second.
 If two members compare
 as equal, their order in the sorted array is undefined.
+
+.BR qsort_r ()
+permits a pointer to an arbitrary piece of data to be passed to the
+comparisson function.
+The \fIdata\fP argument to
+.BR qsort_r ()
+is passed as the third argument in every call to \fIcompar\fP.
 .SH "RETURN VALUE"
 The
 .BR qsort ()
-function returns no value.
+and
+.BR qsort_r ()
+functions return no value.
 .SH "CONFORMING TO"
+.TP
+.BR qsort ()
 SVr4, 4.3BSD, C89, C99.
+.TP
+.BR qsort_r ()
+is a GNU extension.  Note that the argument order and the type of the
+comparison function are different to that used by BSD's
+.BR qsort_r ()
+function.
 .SH NOTES
 Library routines suitable for use as the
 .I compar

-- 
Ben.


[-- Attachment #2: qsort_r.patch --]
[-- Type: text/x-patch, Size: 2070 bytes --]

--- qsort.3.orig	2011-12-29 16:12:51.000000000 +0000
+++ qsort.3	2011-12-29 15:30:33.000000000 +0000
@@ -28,19 +28,32 @@
 .\" Modified 1993-03-29, David Metcalfe
 .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
 .\" 2006-01-15, mtk, Added example program.
+.\" Modified 2011-12-29, Ben Bacarisse (software@bsb.me.uk), 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 2011-12-29 "" "Linux Programmer's Manual"
 .SH NAME
-qsort \- sorts an array
+qsort, qsort_r \- sorts 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 *" data ");"
 .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,12 +71,29 @@
 less than, equal to, or greater than the second.
 If two members compare
 as equal, their order in the sorted array is undefined.
+
+.BR qsort_r ()
+permits a pointer to an arbitrary piece of data to be passed to the
+comparisson function.
+The \fIdata\fP argument to
+.BR qsort_r ()
+is passed as the third argument in every call to \fIcompar\fP.
 .SH "RETURN VALUE"
 The
 .BR qsort ()
-function returns no value.
+and
+.BR qsort_r ()
+functions return no value.
 .SH "CONFORMING TO"
+.TP
+.BR qsort ()
 SVr4, 4.3BSD, C89, C99.
+.TP
+.BR qsort_r ()
+is a GNU extension.  Note that the argument order and the type of the
+comparison function are different to that used by BSD's
+.BR qsort_r ()
+function.
 .SH NOTES
 Library routines suitable for use as the
 .I compar