ldap_sort_values

LDAP_SORT(3)							 LDAP_SORT(3)



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	 tak-
       ing  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 compari-
       son 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  dealloca-
       tion 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.13			  2004/06/10			 LDAP_SORT(3)