Debian Codegraph @

upstream/debian-unstable/man3/qsort.3

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