From 1a6aab0540564416fd4dbc9af27de8c3b9bd9822 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Tue, 13 Jun 2006 22:31:34 +0000 Subject: [PATCH] Update ldap_abandon(3) as example as to how to document non-deprecated v. deprecated interfaces. --- doc/man/man3/deprecated | 8 +++++++ doc/man/man3/ldap.3 | 10 ++------- doc/man/man3/ldap_abandon.3 | 43 +++++++++++++++++++++---------------- 3 files changed, 35 insertions(+), 26 deletions(-) create mode 100644 doc/man/man3/deprecated diff --git a/doc/man/man3/deprecated b/doc/man/man3/deprecated new file mode 100644 index 0000000000..c4347abc26 --- /dev/null +++ b/doc/man/man3/deprecated @@ -0,0 +1,8 @@ +While deprecated, +these interfaces generally remain in the library. The macro +LDAP_DEPRECATED can be defined to a non-zero value +(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use +deprecated interaces. It is recommended that developers writing new +programs, or updating old programs, avoid use of deprecated interfaces. +Over time, it is expected that documentation (and, eventually, support) for +deprecated interfaces to be eliminated. diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 index 57a6f8be4e..b2aed2a629 100644 --- a/doc/man/man3/ldap.3 +++ b/doc/man/man3/ldap.3 @@ -114,14 +114,8 @@ routines are used to sort the entries and values returned via the ldap search routines. .SH DEPRECATED INTERFACES A number of interfaces are now considered deprecated. For instance, -ldap_add(3) is deprecated in favor of ldap_add_ext(3). While deprecated, -these interfaces generally remain in the library. The macro -LDAP_DEPRECATED can be defined to a non-zero value -(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use -deprecated interaces. It is recommended that developers writing new -programs, or updating old programs, avoid use of deprecated interfaces. -Over time, it is expected that documentation (and, eventually, support) for -deprecated interfaces to be eliminated. +ldap_add(3) is deprecated in favor of ldap_add_ext(3). +.so deprecated .SH BER LIBRARY Also included in the distribution is a set of lightweight Basic Encoding Rules routines. These routines are used by the LDAP library diff --git a/doc/man/man3/ldap_abandon.3 b/doc/man/man3/ldap_abandon.3 index a2327ea0e0..02bd5df2d6 100644 --- a/doc/man/man3/ldap_abandon.3 +++ b/doc/man/man3/ldap_abandon.3 @@ -3,15 +3,12 @@ .\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME -ldap_abandon, ldap_abandon_ext \- Abandon an LDAP operation in progress +ldap_abandon_ext \- Abandon an LDAP operation in progress .SH LIBRARY OpenLDAP LDAP (libldap, -lldap) .SH SYNOPSIS .nf .B #include -.sp -.BI "int ldap_abandon(LDAP *" ld ", int " msgid ");" -.sp .BI "int ldap_abandon_ext(LDAP *" ld ", int " msgid "," .RS .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]);" @@ -19,15 +16,15 @@ OpenLDAP LDAP (libldap, -lldap) .fi .SH DESCRIPTION The -.B ldap_abandon() +.B ldap_abandon_ext() routine is used to abandon or cancel an LDAP operation in progress. The \fImsgid\fP passed should be the message id of an outstanding LDAP operation, as returned by -.BR ldap_search (3), -.BR ldap_modify (3), +.BR ldap_search_ext (3), +.BR ldap_modify_ext (3), etc. .LP -.BR ldap_abandon () +.BR ldap_abandon_ext () checks to see if the result of the operation has already come in. If it has, it deletes it from the queue of pending messages. If not, it sends an LDAP abandon operation to the the LDAP server. @@ -37,19 +34,12 @@ will not be returned from a future call to .BR ldap_result (3). .LP .B ldap_abandon_ext() -is equivalent to -.B ldap_abandon() -except that it allows server and client controls to be passed -in +allows server and client controls to be passed in via the .I sctrls and -.IR cctrls , -respectively. +.I cctrls +parameters, respectively. .SH ERRORS -.B ldap_abandon() -returns 0 if everything goes ok, -1 otherwise, -setting \fIld_errno\fP with an appropriate LDAP error code. -.LP .B ldap_abandon_ext() directly returns an LDAP error code indicating success or failure of the operation. @@ -57,6 +47,23 @@ operation. See .BR ldap_error (3) for details. +.SH DEPRECATED INTERFACES +The +.B ldap_abandon() +routine is deprecated in favor of the +.B ldap_abandon_ext() +routine. +.LP +.so deprecated +While deprecated, +these interfaces generally remain in the library. The macro +LDAP_DEPRECATED can be defined to a non-zero value +(e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use +deprecated interaces. It is recommended that developers writing new +programs, or updating old programs, avoid use of deprecated interfaces. +Over time, it is expected that documentation (and, eventually, support) for +deprecated interfaces to be eliminated. + .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), -- 2.39.5