xref: /illumos-gate/usr/src/man/man3c/qsort.3c (revision 1f606c5b8e527ed924f5cbdbbce612887c7dbe32)
1.\"
2.\" The contents of this file are subject to the terms of the
3.\" Common Development and Distribution License (the "License").
4.\" You may not use this file except in compliance with the License.
5.\"
6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7.\" or http://www.opensolaris.org/os/licensing.
8.\" See the License for the specific language governing permissions
9.\" and limitations under the License.
10.\"
11.\" When distributing Covered Code, include this CDDL HEADER in each
12.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13.\" If applicable, add the following below this CDDL HEADER, with the
14.\" fields enclosed by brackets "[]" replaced with your own identifying
15.\" information: Portions Copyright [yyyy] [name of copyright owner]
16.\"
17.\"
18.\" Copyright 1989 AT&T
19.\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
20.\" Copyright 2020 Oxide Computer Company
21.\"
22.Dd November 15, 2023
23.Dt QSORT 3C
24.Os
25.Sh NAME
26.Nm qsort ,
27.Nm qsort_r
28.Nd quick sort
29.Sh SYNOPSIS
30.In stdlib.h
31.Ft void
32.Fo qsort
33.Fa "void *base"
34.Fa "size_t nel"
35.Fa "size_t width"
36.Fa "int (*compar)(const void *, const void *)"
37.Fc
38.Ft void
39.Fo qsort_r
40.Fa "void *base"
41.Fa "size_t nel"
42.Fa "size_t width"
43.Fa "int (*compar_arg)(const void *, const void *, void *)"
44.Fa "void *arg"
45.Fc
46.Sh DESCRIPTION
47The
48.Fn qsort
49function is an implementation of the quick-sort algorithm.
50It sorts a table of data in place.
51The contents of the table are sorted in ascending order according to the
52user-supplied comparison function.
53.Pp
54The
55.Fa base
56argument points to the element at the base of the table.
57The
58.Fa nel
59argument is the number of elements in the table.
60The
61.Fa width
62argument specifies the size of each element in bytes.
63The
64.Fa compar
65argument is the name of the comparison function, which is called with two
66arguments that point to the elements being compared.
67The comparison function need not compare every byte, so arbitrary data may be
68contained in the elements in addition to the values being compared.
69.Pp
70The function must return an integer less than, equal to, or greater than zero
71to indicate if the first argument is to be considered less than, equal to, or
72greater than the second argument.
73.Pp
74The contents of the table are sorted in ascending order according to the user
75supplied comparison function.
76The relative order in the output of two items that compare as equal is
77unpredictable.
78.Pp
79The
80.Fn qsort_r
81function behaves similarly to the
82.Fn qsort
83function, except that its comparison function,
84.Fn compar_arg ,
85takes an extra argument which is the
86.Fn qsort_r
87argument
88.Fa arg .
89This allows one to avoid global data in the comparison function, unlike
90with the
91.Fn qsort
92function.
93.Pp
94The
95.Fn qsort
96and
97.Fn qsort_r
98functions safely allow concurrent access by multiple threads
99to disjoint data, such as overlapping subtrees or tables.
100.Sh EXAMPLES
101.Sy Example 1
102Program sorts.
103.Pp
104The following program sorts a simple array:
105.Bd -literal
106#include <stdlib.h>
107#include <stdio.h>
108
109static int
110intcompare(const void *p1, const void *p2)
111{
112    int i = *((int *)p1);
113    int j = *((int *)p2);
114
115    if (i > j)
116        return (1);
117    if (i < j)
118        return (-1);
119    return (0);
120}
121
122int
123main()
124{
125    int i;
126    int a[10] = { 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 };
127    size_t nelems = sizeof (a) / sizeof (int);
128
129    qsort((void *)a, nelems, sizeof (int), intcompare);
130
131    for (i = 0; i < nelems; i++) {
132        (void) printf("%d ", a[i]);
133    }
134
135    (void) printf("\en");
136    return (0);
137}
138.Ed
139.Sh INTERFACE STABILITY
140.Sy Standard
141.Sh MT-LEVEL
142.Sy MT-Safe
143.Sh SEE ALSO
144.Xr sort 1 ,
145.Xr bsearch 3C ,
146.Xr lsearch 3C ,
147.Xr string 3C ,
148.Xr attributes 7 ,
149.Xr standards 7
150