huschi.net

QSORT(3P)                  POSIX Programmer's Manual                 QSORT(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       qsort - sort a table of data
SYNOPSIS
       #include <stdlib.h>
       void qsort(void *base, size_t nel, size_t width,
              int (*compar)(const void *, const void *));

DESCRIPTION
       The qsort() function shall sort an array of nel  objects,  the  initial
       element  of  which  is  pointed to by base. The size of each object, in
       bytes, is specified by the width argument. If the nel argument has  the
       value  zero,  the comparison function pointed to by compar shall not be
       called and no rearrangement shall take place.
       The application shall ensure that the comparison function pointed to by
       compar  does  not  alter the contents of the array.  The implementation
       may reorder elements of the array between calls to the comparison func-
       tion, but shall not alter the contents of any individual element.
       When the same objects (consisting of width bytes, irrespective of their
       current positions in the array) are passed more than once to  the  com-
       parison  function,  the  results  shall be consistent with one another.
       That is, they shall define a total ordering on the array.
       The contents of the array shall be sorted in ascending order  according
       to  a comparison function. The compar argument is a pointer to the com-
       parison function, which is called with two arguments that point to  the
       elements being compared. The application shall ensure that the function
       returns an integer less than, equal to, or greater than 0, if the first
       argument  is  considered  respectively  less than, equal to, or greater
       than the second. If two members compare as equal, their  order  in  the
       sorted array is unspecified.
RETURN VALUE
       The qsort() function shall not return a value.
ERRORS
       No errors are defined.
       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       The  comparison function need not compare every byte, so arbitrary data
       may be contained in the elements in addition to the values  being  com-
       pared.
RATIONALE
       The  requirement that each argument (hereafter referred to as p) to the
       comparison function is a pointer to elements of the array implies  that
       for  every  call,  for  each  argument separately, all of the following
       expressions are nonzero:

              ((char *)p - (char *)base) % width == 0
              (char *)p >= (char *)base
              (char *)p < (char *)base + nel * width
FUTURE DIRECTIONS
       None.
SEE ALSO
       The Base Definitions volume of IEEE Std 1003.1-2001, <stdlib.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                            QSORT(3P)