man3/qsort.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\"
  11 .\" Modified 1993-03-29, David Metcalfe
  12 .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu)
  13 .\" 2006-01-15, mtk, Added example program.
  14 .\" Modified 2012-03-08, Mark R. Bannister <cambridge@users.sourceforge.net>
  15 .\"                  and Ben Bacarisse <software@bsb.me.uk>
  16 .\"     Document qsort_r()
  17 .\"
  18 .TH qsort 3 (date) "Linux man-pages (unreleased)"
  19 .SH NAME
  20 qsort, qsort_r \- sort an array
  21 .SH LIBRARY
  22 Standard C library
  23 .RI ( libc ", " \-lc )
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <stdlib.h>
  27 .P
  28 .BI "void qsort(void " base [. size " * ." nmemb "], size_t " nmemb ", \
  29 size_t " size ,
  30 .BI "           int (*" compar ")(const void [." size "], \
  31 const void [." size ]));
  32 .BI "void qsort_r(void " base [. size " * ." nmemb "], size_t " nmemb ", \
  33 size_t " size ,
  34 .BI "           int (*" compar ")(const void [." size "], \
  35 const void [." size "], void *),"
  36 .BI "           void *" arg ");"
  37 .fi
  38 .P
  39 .RS -4
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .RE
  43 .P
  44 .BR qsort_r ():
  45 .nf
  46     _GNU_SOURCE
  47 .fi
  48 .SH DESCRIPTION
  49 The
  50 .BR qsort ()
  51 function sorts an array with \fInmemb\fP elements of
  52 size \fIsize\fP.
  53 The \fIbase\fP argument points to the start of the
  54 array.
  55 .P
  56 The contents of the array are sorted in ascending order according to a
  57 comparison function pointed to by \fIcompar\fP, which is called with two
  58 arguments that point to the objects being compared.
  59 .P
  60 The comparison function must return an integer less than, equal to, or
  61 greater than zero if the first argument is considered to be respectively
  62 less than, equal to, or greater than the second.
  63 If two members compare as equal,
  64 their order in the sorted array is undefined.
  65 .P
  66 The
  67 .BR qsort_r ()
  68 function is identical to
  69 .BR qsort ()
  70 except that the comparison function
  71 .I compar
  72 takes a third argument.
  73 A pointer is passed to the comparison function via
  74 .IR arg .
  75 In this way, the comparison function does not need to use global variables to
  76 pass through arbitrary arguments, and is therefore reentrant and safe to
  77 use in threads.
  78 .SH RETURN VALUE
  79 The
  80 .BR qsort ()
  81 and
  82 .BR qsort_r ()
  83 functions return no value.
  84 .SH ATTRIBUTES
  85 For an explanation of the terms used in this section, see
  86 .BR attributes (7).
  87 .TS
  88 allbox;
  89 lbx lb lb
  90 l l l.
  91 Interface       Attribute       Value
  92 T{
  93 .na
  94 .nh
  95 .BR qsort (),
  96 .BR qsort_r ()
  97 T}      Thread safety   MT-Safe
  98 .TE
  99 .SH STANDARDS
 100 .TP
 101 .BR qsort ()
 102 C11, POSIX.1-2008.
 103 .SH HISTORY
 104 .TP
 105 .BR qsort ()
 106 POSIX.1-2001, C89, SVr4, 4.3BSD.
 107 .TP
 108 .BR qsort_r ()
 109 glibc 2.8.
 110 .SH NOTES
 111 To compare C strings, the comparison function can call
 112 .BR strcmp (3),
 113 as shown in the example below.
 114 .SH EXAMPLES
 115 For one example of use, see the example under
 116 .BR bsearch (3).
 117 .P
 118 Another example is the following program,
 119 which sorts the strings given in its command-line arguments:
 120 .P
 121 .\" SRC BEGIN (qsort.c)
 122 .EX
 123 #include <stdio.h>
 124 #include <stdlib.h>
 125 #include <string.h>
 126 \&
 127 static int
 128 cmpstringp(const void *p1, const void *p2)
 129 {
 130     /* The actual arguments to this function are "pointers to
 131        pointers to char", but strcmp(3) arguments are "pointers
 132        to char", hence the following cast plus dereference. */
 133 \&
 134     return strcmp(*(const char **) p1, *(const char **) p2);
 135 }
 136 \&
 137 int
 138 main(int argc, char *argv[])
 139 {
 140     if (argc < 2) {
 141         fprintf(stderr, "Usage: %s <string>...\en", argv[0]);
 142         exit(EXIT_FAILURE);
 143     }
 144 \&
 145     qsort(&argv[1], argc \- 1, sizeof(char *), cmpstringp);
 146 \&
 147     for (size_t j = 1; j < argc; j++)
 148         puts(argv[j]);
 149     exit(EXIT_SUCCESS);
 150 }
 151 .EE
 152 .\" SRC END
 153 .SH SEE ALSO
 154 .BR sort (1),
 155 .BR alphasort (3),
 156 .BR strcmp (3),
 157 .BR versionsort (3)