(split) LDP: Update original to LDP v3.38.

[linuxjm/LDP_man-pages.git] / original / man3 / qsort.3

diff --git a/original/man3/qsort.3 b/original/man3/qsort.3
index 87ef129..4c266aa 100644 (file)
--- a/original/man3/qsort.3
+++ b/original/man3/qsort.3
@@ -28,19 +28,34 @@
 .\" Modified 1993-03-29, David Metcalfe
 .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
 .\" 2006-01-15, mtk, Added example program.
+.\" Modified 2012-03-08, Mark R. Bannister <cambridge@users.sourceforge.net>
+.\"                  and Ben Bacarisse <software@bsb.me.uk>
+.\"     Document 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-08 "" "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 ()
@@ -56,18 +71,40 @@ arguments that point to the objects being compared.
 The comparison function must return an integer less than, equal to, or
 greater than zero if the first argument is considered to be respectively
 less than, equal to, or greater than the second.
-If two members compare
-as equal, their order in the sorted array is undefined.
+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 reentrant 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 VERSIONS
+.BR qsort_r ()
+was added to glibc in version 2.8.
 .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).