ldap_sort_entries(3)

LDAP_SORT(3)           C LIBRARY FUNCTIONS           LDAP_SORT(3)

NAME

     ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp  -
     LDAP sorting 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 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  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  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

OpenLDAP LDVERSION  Last change: RELEASEDATE                    1

LDAP_SORT(3)           C LIBRARY FUNCTIONS           LDAP_SORT(3)

     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 func-
     tion 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 pro-
     duce 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  allo-
     cate  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 LDVERSION  Last change: RELEASEDATE                    2