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