Section 3 man page for ldap_parse_reference()

diff --git a/doc/man/man3/ldap_parse_reference.3 b/doc/man/man3/ldap_parse_reference.3
new file mode 100644 (file)
index 0000000..b5cd824
--- /dev/null
+++ b/doc/man/man3/ldap_parse_reference.3
@@ -0,0 +1,61 @@
+.TH LDAP_PARSE_REFERENCE 3 "26 September 2001" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2001 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.SH NAME
+ldap_parse \- Extract referrals and controls from a reference message
+.SH SYNOPSIS
+.nf
+.ft B
+#include <ldap.h>
+.LP
+.ft B
+int ldap_parse_reference( LDAP *ld, LDAPMessage *reference,
+       char ***referralsp, LDAPControl ***serverctrlsp, int freeit )
+.SH DESCRIPTION
+.LP
+The
+.B ldap_parse_reference()
+routine is used to extract referrals and controls from a reference message.
+The \fIreference\fP parameter is a reference message as returned by a
+call to
+.BR ldap_first_reference (3) ,
+.BR ldap_next_reference (3) ,
+.BR ldap_first_message (3) ,
+.BR ldap_next_message (3)
+or
+.BR ldap_result (3) .
+.LP
+The \fIreferralsp\fP parameter will be filled in with an allocated array of
+character strings. The strings are copies of the referrals contained in
+the parsed message. The array should be freed by calling
+.BR ldap_value_free (3) .
+If \fIreferralsp\fP is NULL, no referrals are returned.
+If no referrals were returned, \fI*referralsp\fP is set to NULL.
+.LP
+The \fIserverctrlsp\fP parameter will be filled in with an allocated array of
+controls copied from the parsed message. The array should be freed by calling
+.BR ldap_controls_free (3) .
+If \fIserverctrlsp\fP is NULL, no controls are returned.
+If no controls were returned, \fI*serverctrlsp\fP is set to NULL.
+.LP
+The \fIfreeit\fP parameter determines whether the parsed message is
+freed or not after the extraction. Any non-zero value will make it
+free the message. The
+.BR ldap_msgfree (3)
+routine can also be used to free the message later.
+.SH ERRORS
+Upon success LDAP_SUCCESS is returned. Otherwise the values of the
+\fIreferralsp\fP and \fIserverctrlsp\fP parameters are undefined.
+.SH SEE ALSO
+.BR ldap(3),
+.BR ldap_first_reference(3),
+.BR ldap_first_message(3),
+.BR ldap_result(3),
+.BR ldap_get_values(3),
+.BR ldap_controls_free(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.