[patch] qsort.3: document qsort_r

[patch] qsort.3: document qsort_r

[Ben]

[-- 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

Re: [patch] qsort.3: document qsort_r

[Mark R Bannister]

Ben <software-QW8DL1zPdzBaa/9Udqfwiw@public.gmane.org> wrote on 2011-12-29 20:50:25 GMT:
> Following a discussion on comp.lang.c, I noticed that glibc's qsort_r is
> not documented in the man pages.

Hi Ben,

I addressed this omission in a patch dated 24th October:
http://article.gmane.org/gmane.linux.man/2397

Best regards,
Mark.



--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] qsort.3: document qsort_r

[Michael Kerrisk (man-pages)]

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?

Thanks,

Michael

On Wed, Jan 4, 2012 at 1:11 AM, Mark R Bannister
<mark-/K+B3afwL8Jt0JrxVvvTASp2UmYkHbXO@public.gmane.org> wrote:
> Ben <software-QW8DL1zPdzBaa/9Udqfwiw@public.gmane.org> wrote on 2011-12-29 20:50:25 GMT:
>> Following a discussion on comp.lang.c, I noticed that glibc's qsort_r is
>> not documented in the man pages.
>
> Hi Ben,
>
> I addressed this omission in a patch dated 24th October:
> http://article.gmane.org/gmane.linux.man/2397
>
> Best regards,
> Mark.
>
>
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] qsort.3: document qsort_r

[Ben]

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

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.


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

--- 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@cs.unc.edu)
 .\" 2006-01-15, mtk, Added example program.
+.\" Modified 2011-10-24, Mark R. Bannister (cambridge@users.sourceforge.net)
+.\"				to add qsort_r()
+.\" Modified 2012-03-05, Ben Bacarisse (software@bsb.me.uk) 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).

Re: [patch] qsort.3: document qsort_r

[Michael Kerrisk (man-pages)]

Hi Ben,

On Tue, Mar 6, 2012 at 10:55 AM, Ben <software-QW8DL1zPdzBaa/9Udqfwiw@public.gmane.org> wrote:
> 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, thanks for that. I've applied all of the above.

Mark, thanks for the initial patch!

Cheers,

Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html