Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

qsort(3C)

Name

qsort - quick sort

qsort_s - quick sort with additional safety checks

Synopsis

#include <stdlib.h>

void qsort(void *base, size_t nel, size_t width,
    int (*compar)(const void *, const void *));
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
   
errno_t qsort_s(void *base, rsize_t nel, rsize_t width,
    int (*compar)(const void *x, const void *y, void *context),
    void *context);

Description

The qsort() function is an implementation of the quick-sort algorithm. It sorts a table of data in place. The contents of the table are sorted in ascending order according to the user-supplied comparison function.

The base argument points to the element at the base of the table. The nel argument is the number of elements in the table. The width argument specifies the size of each element in bytes. The compar argument is the name of the comparison function, which is called with two arguments that point to the elements being compared.

The function must return an integer less than, equal to, or greater than zero to indicate if the first argument is to be considered less than, equal to, or greater than the second argument.

The contents of the table are sorted in ascending order according to the user supplied comparison function.

The qsort_s() function is part of the C11 bounds checking interfaces specified in the C11 standard, Annex K. It is similar to the qsort() function, but with differing parameters and return type and explicit runtime-constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.

Return Values

If no runtime-constraint violation is detected, qsort_s() returns zero, otherwise, it returns a non-zero value.

Errors

The qsort() and qsort_s() functions will fail if:

EINVAL

Null pointer is passed.

ERANGE

size argument is not a valid value.

Usage

The qsort() function safely allows concurrent access by multiple threads to disjoint data, such as overlapping subtrees or tables.

Examples

Example 1 Program Sorts

The following program sorts a simple array:

#include <stdlib.h>
#include <stdio.h>

static int
intcompare(const void *p1, const void *p2)
{
    int i = *((int *)p1);
    int j = *((int *)p2);

    if (i > j)
        return (1);
    if (i < j)
        return (-1);
    return (0);
}

int
main()
{
    int i;
    int a[10] = { 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 };
    size_t nelems = sizeof (a) / sizeof (int);

    qsort((void *)a, nelems, sizeof (int), intcompare);

    for (i = 0; i < nelems; i++) {
        (void) printf("%d ", a[i]);
    }

    (void) printf("\n");
    return (0);
}

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
See below
Standard

The qsort() function can be used safely in multithreaded applications.

The qsort_s() function cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.

See Also

sort(1), bsearch(3C), bsearch_s(3C), lsearch(3C), string(3C), attributes(7), standards(7), runtime_constraint_handler(3C)

Notes

The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared.

The relative order in the output of two items that compare as equal is unpredictable.