mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
113 lines
3.4 KiB
Groff
113 lines
3.4 KiB
Groff
.TH LDAP_SORT 3 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines
|
|
.SH LIBRARY
|
|
OpenLDAP LDAP (libldap, -lldap)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <ldap.h>
|
|
.LP
|
|
.ft B
|
|
ldap_sort_entries(ld, chain, attr, cmp)
|
|
.ft
|
|
LDAP *ld;
|
|
LDAPMessage **chain;
|
|
char *attr;
|
|
int (*cmp)();
|
|
.LP
|
|
.ft B
|
|
ldap_sort_values(ld, vals, cmp)
|
|
.ft
|
|
LDAP *ld;
|
|
char **vals;
|
|
int (*cmp)();
|
|
.LP
|
|
.ft B
|
|
ldap_sort_strcasecmp(a, b)
|
|
.ft
|
|
char *a;
|
|
char *b;
|
|
.SH DESCRIPTION
|
|
These routines are used to sort lists of entries and values retrieved
|
|
from an LDAP server.
|
|
.B 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 \fIld\fP, the LDAP
|
|
structure, which is only used for error reporting, \fIchain\fP, the
|
|
list of entries as returned by
|
|
.BR ldap_search_s (3)
|
|
or
|
|
.BR ldap_result (3).
|
|
\fIattr\fP is the attribute to use as a key in the sort
|
|
or NULL to sort by DN, and \fIcmp\fP is the comparison function to use
|
|
when comparing values (or individual DN components if sorting by DN).
|
|
In this case, \fIcmp\fP should be a function taking two single values
|
|
of the \fIattr\fP 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
|
|
.BR qsort (3),
|
|
which is called to do the actual sorting.
|
|
.LP
|
|
.B ldap_sort_values()
|
|
is used to sort an array of values from an entry,
|
|
as returned by
|
|
.BR ldap_get_values (3).
|
|
It takes the LDAP connection
|
|
structure \fIld\fP, the array of values
|
|
to sort \fIvals\fP, and \fIcmp\fP, the comparison
|
|
function to use during the sort.
|
|
Note that \fIcmp\fP will be passed a pointer to each element in the
|
|
\fIvals\fP array, so if you pass the normal char ** for this parameter,
|
|
\fIcmp\fP should take two char **'s as arguments (i.e., you cannot
|
|
pass \fIstrcasecmp\fP or its friends for \fIcmp\fP). You can, however,
|
|
pass the function
|
|
.B ldap_sort_strcasecmp()
|
|
for this purpose.
|
|
.LP
|
|
For example:
|
|
.LP
|
|
.nf
|
|
.ft tt
|
|
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" );
|
|
.ft
|
|
.fi
|
|
.SH NOTES
|
|
.LP
|
|
The
|
|
.B ldap_sort_entries()
|
|
routine applies the comparison function to
|
|
each value of the attribute in the array as returned by a call to
|
|
.BR 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.
|
|
.SH SEE ALSO
|
|
.BR ldap (3),
|
|
.BR ldap_search (3),
|
|
.BR ldap_result (3),
|
|
.BR qsort (3)
|
|
.SH ACKNOWLEDGEMENTS
|
|
.B OpenLDAP
|
|
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
|
|
.B OpenLDAP
|
|
is derived from University of Michigan LDAP 3.3 Release.
|