git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_first_reference.3

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