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@xxxxxxxxxx) .\" 2006-01-15, mtk, Added example program. +.\" Modified 2011-12-29, Ben Bacarisse (software@xxxxxxxxx), 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.
--- 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@xxxxxxxxxx) .\" 2006-01-15, mtk, Added example program. +.\" Modified 2011-12-29, Ben Bacarisse (software@xxxxxxxxx), 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
