ldap_sort_entries,  ldap_sort_values, ldap_sort_strcasecmp
       - LDAP sorting routines


SYNOPSIS

       #include <ldap.h>

       ldap_sort_entries(ld, chain, attr, cmp)
       LDAP *ld;
       LDAPMessage **chain;
       char *attr;
       int (*cmp)();

       ldap_sort_values(ld, vals, cmp)
       LDAP *ld;
       char **vals;
       int (*cmp)();

       ldap_sort_strcasecmp(a, b)
       char *a;
       char *b;


DESCRIPTION

       These routines are used to sort lists of entries and  val­
       ues retrieved from an LDAP server.  ldap_sort_entries() is
       used to sort a chain of entries  retrieved  from  an  LDAP
       search call either by DN or by some arbitrary attribute in
       the entries.  It takes ld, the LDAP  structure,  which  is
       only  used for error reporting, chain, the list of entries
       as returned by ldap_search_s(3) or  ldap_result(3).   attr
       is  the  attribute  to use as a key in the sort or NULL to
       sort by DN, and cmp is the comparison function to use when
       comparing  values  (or individual DN components if sorting
       by DN).  In this case, cmp should be a function taking two
       single  values  of  the  attr  to sort by, and returning a
       value less than zero, equal to zero, or greater than zero,
       depending  on  whether  the  first  argument is less than,
       equal to, or greater than the second argument.   The  con­
       vention  is  the same as used by qsort(3), which is called
       to do the actual sorting.

       ldap_sort_values() is used to sort an array of values from
       an entry, as returned by ldap_get_values(3).  It takes the
       LDAP connection structure ld, the array of values to  sort
       vals,  and  cmp, the comparison function to use during the
       sort.  Note that cmp will be passed a pointer to each ele­
       ment  in the vals array, so if you pass the normal char **
       for this parameter, cmp should take two char **'s as argu­
       ments (i.e., you cannot pass strcasecmp or its friends for
       cmp).  You can, however, pass the function  ldap_sort_str­
       casecmp() for this purpose.

       For example:

            LDAPMessage *res;

            /* ... call to ldap_search_s(), fill in res, retrieve sn attr ... */

            /* now sort the entries on surname attribute */
            if ( ldap_sort_entries( ld, &res, "sn", ldap_sort_strcasecmp ) != 0 )
                 ldap_perror( ld, "ldap_sort_entries" );


NOTES

       The  ldap_sort_entries()  routine  applies  the comparison
       function to each value of the attribute in  the  array  as
       returned by a call to ldap_get_values(3), until a mismatch
       is found.  This works fine for  single-valued  attributes,
       but   may  produce  unexpected  results  for  multi-valued
       attributes.  When sorting by DN, the  comparison  function
       is  applied  to  an  exploded  version  of the DN, without
       types.  The return values for all of these  functions  are
       declared  in  the <ldap.h> header file.  Some routines may
       dynamically allocate memory.  Callers are responsible  for
       freeing  such  memory using the supplied deallocation rou­
       tines.


SEE ALSO

       ldap(3), ldap_search(3), ldap_result(3), qsort(3)


ACKNOWLEDGEMENTS

       OpenLDAP is developed and maintained by The OpenLDAP  Pro­
       ject (http://www.openldap.org/).  OpenLDAP is derived from
       University of Michigan LDAP 3.3 Release.


Man(1) output converted with man2html