qsort() — Sort array

Standards

Standards / Extensions	C or C++	Dependencies
ISO C XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <stdlib.h>

void qsort(void *base, size_t num, size_t width,
           int(*compare)(const void *element1, const void *element2));

General description

The qsort() function sorts an array of num elements, each of width bytes in size, where the first element of the array is pointed to by base.

The compare pointer points to a function, which you supply, that compares two array elements and returns an integer value specifying their relationship. The qsort() function calls the comparison function one or more times during the sort, passing pointers to two array elements on each call. The comparison function must compare the elements and return one of the following values:

Value: Meaning
< 0: element1 less than element2
0: element1 equal to element2
> 0: element1 greater than element2

The sorted array elements are stored in increasing order, as returned by the comparison function. You can sort in reverse order by reversing the "greater than" and "less than" logic in the comparison function. If two elements are equal, their order in the sorted array is unspecified. The qsort() function overwrites the contents of the array with the sorted elements.

Special behavior for C++: C++ and C linkage conventions are incompatible, and therefore the qsort() function cannot receive C++ function pointers. If you attempt to pass a C++ function pointer to the qsort() function, the compiler will flag it as an error. To use the C++ qsort() function, you must ensure that the comparison function has C linkage, by declaring it as extern "C".

Returned value

The qsort() function returns no values.

Example

CELEBQ01

⁄* CELEBQ01                                      

   This example sorts the arguments (argv) in ascending sequence, based on      
   the ASCII value of each character and string, and using the comparison       
   function compare() supplied in the example.                                  

 *⁄                                                                             
#include <stdio.h>                                                              
#include <stdlib.h>                                                             
#include <string.h>                                                             
                                                                                
               ⁄* Declaration of compare() as a function *⁄                     
#ifdef __cplusplus                                                              
extern "C" int compare(const void *, const void *);                             
#else                                                                           
int compare(const void *, const void *);  ⁄* macro is automatically *⁄          
#endif                                    ⁄* defined by the C++⁄MVS compiler  *⁄
                                                                                
                                                                                
int main (int argc, char *argv[ ])                                              
{                                                                               
   int i;                                                                       
   argv++;                                                                      
   argc--;                                                                      
   qsort((char *)argv, argc, sizeof(char *), compare);                          
   for (i = 0; i < argc; ++i)                                                   
      printf("%s\n", argv[i]);                                                  
   return 0;                                                                    
}                                                                               
                                                                                
int compare (const void *arg1, const void *arg2)                                
{                                                                               
               ⁄* Compare all of both strings *⁄                                
   return(strcmp(*(char **)arg1, *(char **)arg2));                              
}

Output

If the program is passed the arguments:

Does, this, really, sort, the, arguments, correctly?

then expect the following output.