/usr/man2/cat.3/ldap_sort.3.Z(/usr/man2/cat.3/ldap_sort.3.Z)

NAME

       ldap_sort_entries,  ldap_sort_values, ldap_sort_strcasecmp - LDAP sort-
       ing routines

LIBRARY

       OpenLDAP LDAP (libldap, -lldap)

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  values  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  com-
       parison  function to use when comparing values (or individual DN compo-
       nents 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 convention 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
       element  in  the vals array, so if you pass the normal char ** for this
       parameter, cmp should take two char **'s as arguments (i.e., you cannot
       pass  strcasecmp  or  its friends for cmp).  You can, however, pass the
       function ldap_sort_strcasecmp() for this purpose.

       For example:

            LDAP *ld;
            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
       routines.

SEE ALSO

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

ACKNOWLEDGEMENTS

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

OpenLDAP 2.2.30                   2005/11/18                      LDAP_SORT(3)