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).
