usr/src/man/man3c/qsort.3c

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH QSORT 3C "Dec 6, 2004"
   7 .SH NAME
   8 qsort \- quick sort
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <stdlib.h>
  13
  14 \fBvoid\fR \fBqsort\fR(\fBvoid *\fR\fIbase\fR, \fBsize_t\fR \fInel\fR, \fBsize_t\fR \fIwidth\fR,
  15      \fBint (*\fR\fIcompar\fR)(const void *, const void *));
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBqsort()\fR function is an implementation of the quick-sort algorithm. It
  22 sorts a table of data in place. The contents of the table are sorted in
  23 ascending order according to the  user-supplied comparison function.
  24 .sp
  25 .LP
  26 The \fIbase\fR argument points to the element at the base of the table.  The
  27 \fInel\fR argument is the number of elements in the table.  The \fIwidth\fR
  28 argument specifies the size of each element in bytes.  The \fIcompar\fR
  29 argument is the name of the comparison function, which is called with two
  30 arguments that point to the elements being compared.
  31 .sp
  32 .LP
  33 The function must return an integer less than, equal to, or greater than zero
  34 to indicate if the first argument is to be considered less than, equal to, or
  35 greater than the second argument.
  36 .sp
  37 .LP
  38 The contents of the table are sorted in ascending order according to the user
  39 supplied comparison function.
  40 .SH USAGE
  41 .sp
  42 .LP
  43 The \fBqsort()\fR function safely allows concurrent access by  multiple threads
  44 to disjoint data, such as overlapping subtrees or tables.
  45 .SH EXAMPLES
  46 .LP
  47 \fBExample 1 \fRProgram sorts.
  48 .sp
  49 .LP
  50 The following program sorts a simple array:
  51
  52 .sp
  53 .in +2
  54 .nf
  55 #include <stdlib.h>
  56 #include <stdio.h>
  57
  58 static int
  59 intcompare(const void *p1, const void *p2)
  60 {
  61     int i = *((int *)p1);
  62     int j = *((int *)p2);
  63
  64     if (i > j)
  65         return (1);
  66     if (i < j)
  67         return (-1);
  68     return (0);
  69 }
  70
  71 int
  72 main()
  73 {
  74     int i;
  75     int a[10] = { 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 };
  76     size_t nelems = sizeof (a) / sizeof (int);
  77
  78     qsort((void *)a, nelems, sizeof (int), intcompare);
  79
  80     for (i = 0; i < nelems; i++) {
  81         (void) printf("%d ", a[i]);
  82     }
  83
  84     (void) printf("\en");
  85     return (0);
  86 }
  87 .fi
  88 .in -2
  89
  90 .SH ATTRIBUTES
  91 .sp
  92 .LP
  93 See \fBattributes\fR(5) for descriptions of the following attributes:
  94 .sp
  95
  96 .sp
  97 .TS
  98 box;
  99 c | c
 100 l | l .
 101 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 102 _
 103 Interface Stability     Standard
 104 _
 105 MT-Level        MT-Safe
 106 .TE
 107
 108 .SH SEE ALSO
 109 .sp
 110 .LP
 111 \fBsort\fR(1), \fBbsearch\fR(3C), \fBlsearch\fR(3C), \fBstring\fR(3C),
 112 \fBattributes\fR(5), \fBstandards\fR(5)
 113 .SH NOTES
 114 .sp
 115 .LP
 116 The comparison function need not compare every byte, so arbitrary data may be
 117 contained in the elements in addition to the values being compared.
 118 .sp
 119 .LP
 120 The relative order in the output of two items that compare as equal is
 121 unpredictable.