---

9.3 Array Sort Function

To sort an array using an arbitrary comparison function, use the qsort function. The prototype for this function is in stdlib.h.

Function: void qsort (void *array, size_t count, size_t size, comparison_fn_t compare) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The qsort function sorts the array array. The array contains count elements, each of which is of size size.

The compare function is used to perform the comparison on the array elements. This function is called with two pointer arguments and should return an integer less than, equal to, or greater than zero corresponding to whether its first argument is considered less than, equal to, or greater than its second argument.

Warning: If two objects compare as equal, their order after sorting is unpredictable. That is to say, the sorting is not stable. This can make a difference when the comparison considers only part of the elements. Two elements with the same sort key may differ in other respects.

Although the object addresses passed to the comparison function lie within the array, they need not correspond with the original locations of those objects because the sorting algorithm may swap around objects in the array before making some comparisons. The only way to perform a stable sort with qsort is to first augment the objects with a monotonic counter of some kind.

Here is a simple example of sorting an array of doubles in numerical order, using the comparison function defined above (see Defining the Comparison Function):

{
  double *array;
  int size;
  …
  qsort (array, size, sizeof (double), compare_doubles);
}

The qsort function derives its name from the fact that it was originally implemented using the “quick sort” algorithm.

The implementation of qsort in this library is an in-place sort and uses a constant extra space (allocated on the stack).