From 3593bc7abfc6f2ae3fe331f6e4c3cf3231314267 Mon Sep 17 00:00:00 2001
From: Kurt Zeilenga <kurt@openldap.org>
Date: Wed, 14 Jun 2006 05:55:34 +0000
Subject: [PATCH] Deprecated.

---
 doc/man/man3/ldap_sort.3 | 115 ++++-----------------------------------
 1 file changed, 10 insertions(+), 105 deletions(-)

diff --git a/doc/man/man3/ldap_sort.3 b/doc/man/man3/ldap_sort.3
index 63ef8dffd1..3d13b377f6 100644
--- a/doc/man/man3/ldap_sort.3
+++ b/doc/man/man3/ldap_sort.3
@@ -3,114 +3,19 @@
 .\" Copyright 1998-2006 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
+LDAP sorting routines (deprecated)
 .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.
+.BR ldap_sort_entries (),
+.BR ldap_sort_values (),
+and
+.BR ldap_sort_strcasecmp ()
+are deprecated.  
+.LP
+.so Deprecated
 .SH SEE ALSO
-.BR ldap (3),
-.BR ldap_search (3),
-.BR ldap_result (3),
-.BR qsort (3)
+.BR ldap (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.  
+.so ../Project
-- 
2.39.5