external/bsd/openldap/man/ldap_first_reference.3

   1 .TH LDAP_FIRST_REFERENCE 3 "2008/07/16" "OpenLDAP 2.4.11"
   2 .\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_first_reference.3,v 1.11.2.3 2008/02/11 23:26:39 kurt Exp $
   3 .\" Copyright 1998-2008 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <ldap.h>
  13 .LP
  14 .ft B
  15 int ldap_count_references( LDAP *ld, LDAPMessage *result )
  16 .LP
  17 .ft B
  18 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result )
  19 .LP
  20 .ft B
  21 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference )
  22 .SH DESCRIPTION
  23 .LP
  24 These routines are used to step through the continuation references in a
  25 result chain received from
  26 .BR ldap_result (3)
  27 or the synchronous LDAP search operation routines.
  28 .LP
  29 The
  30 .B ldap_first_reference()
  31 routine is used to retrieve the first reference message in a
  32 result chain.  It takes the \fIresult\fP as returned by a call to
  33 .BR ldap_result (3) ,
  34 .BR ldap_search_s (3)
  35 or
  36 .BR ldap_search_st (3)
  37 and returns a pointer to the first reference message in the
  38 result chain.
  39 .LP
  40 This pointer should be supplied on a subsequent call to
  41 .B ldap_next_reference()
  42 to get the next reference message, the result of which should be
  43 supplied to the next call to
  44 .BR ldap_next_reference() ,
  45 etc.
  46 .B ldap_next_reference()
  47 will return NULL when there are no more reference messages.
  48 The reference messages returned from these calls are used by
  49 .BR ldap_parse_reference (3)
  50 to extract referrals and controls.
  51 .LP
  52 A count of the number of reference messages in the search result can be
  53 obtained by calling
  54 .BR ldap_count_references() .
  55 It can also be used to count the number of reference messages remaining
  56 in a result chain.
  57 .SH ERRORS
  58 If an error occurs in
  59 .B ldap_first_reference()
  60 or
  61 .BR ldap_next_reference() ,
  62 NULL is returned.  If an error occurs in
  63 .BR ldap_count_references() ,
  64 -1 is returned.
  65 .SH SEE ALSO
  66 .BR ldap (3),
  67 .BR ldap_result (3),
  68 .BR ldap_search (3),
  69 .BR ldap_parse_reference (3)
  70 .SH ACKNOWLEDGEMENTS
  71 .\" Shared Project Acknowledgement Text
  72 .B "OpenLDAP Software"
  73 is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
  74 .B "OpenLDAP Software"
  75 is derived from University of Michigan LDAP 3.3 Release.