external/bsd/openldap/man/ldap_get_option.3

   1 .TH LDAP_GET_OPTION 3 "2008/07/16" "OpenLDAP 2.4.11"
   2 .\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_get_option.3,v 1.3.2.5 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_get_option, ldap_set_option \- LDAP option handling routines
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .B #include <ldap.h>
  12 .LP
  13 .BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");"
  14 .LP
  15 .BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");"
  16 .SH DESCRIPTION
  17 .LP
  18 These routines provide access to options stored either in a LDAP handle
  19 or as global options, where applicable.
  20 They make use of a neutral interface, where the type of the value
  21 either retrieved by
  22 .BR ldap_get_option (3)
  23 or set by
  24 .BR ldap_set_option (3)
  25 is cast to
  26 .BR "void *" .
  27 The actual type is determined based on the value of the
  28 .B option
  29 argument.
  30 Global options are set/retrieved by passing a NULL LDAP handle.
  31 .TP
  32 .B LDAP_OPT_API_INFO
  33 Fills-in a
  34 .BR "struct ldapapiinfo" ;
  35 .BR outvalue
  36 must be a
  37 .BR "struct ldapapiinfo *" ,
  38 pointing to an already allocated struct.
  39 This is a read-only option.
  40 .TP
  41 .B LDAP_OPT_DESC
  42 Returns the file descriptor associated to the socket buffer
  43 of the LDAP handle passed in as
  44 .BR ld ;
  45 .BR outvalue
  46 must be a
  47 .BR "int *" .
  48 This is a read-only, handler-specific option.
  49 .TP
  50 .B LDAP_OPT_SOCKBUF
  51 Returns a pointer to the socket buffer of the LDAP handle passed in as
  52 .BR ld ;
  53 .BR outvalue
  54 must be a
  55 .BR "Sockbuf **" .
  56 This is a read-only, handler-specific option.
  57 .TP
  58 .B LDAP_OPT_TIMEOUT
  59 Sets/gets a timeout value for the synchronous API calls.
  60 .B outvalue
  61 must be a
  62 .BR "struct timeval **"
  63 (the caller has to free
  64 .BR *outvalue ) ,
  65 and
  66 .B invalue
  67 must be a
  68 .BR "struct timeval *" ,
  69 and they cannot be NULL. Using a struct with seconds set to -1 results
  70 in an infinite timeout, which is the default.
  71 .TP
  72 .B LDAP_OPT_NETWORK_TIMEOUT
  73 Sets/gets the network timeout value after which
  74 .BR poll (2)/ select (2)
  75 following a
  76 .BR connect (2)
  77 returns in case of no activity.
  78 .B outvalue
  79 must be a
  80 .BR "struct timeval **"
  81 (the caller has to free
  82 .BR *outvalue ) ,
  83 and
  84 .B invalue
  85 must be a
  86 .BR "struct timeval *" ,
  87 and they cannot be NULL. Using a struct with seconds set to -1 results
  88 in an infinite timeout, which is the default.
  89 .TP
  90 .B LDAP_OPT_DEREF
  91 Sets/gets the value that defines when alias dereferencing must occur.
  92 .BR outvalue
  93 and
  94 .BR invalue
  95 must be
  96 .BR "int *" ,
  97 and they cannot be NULL.
  98 .TP
  99 .B LDAP_OPT_SIZELIMIT
 100 Sets/gets the value that defines the maximum number of entries
 101 to be returned by a search operation.
 102 .BR outvalue
 103 and
 104 .BR invalue
 105 must be
 106 .BR "int *" ,
 107 and they cannot be NULL.
 108 .TP
 109 .B LDAP_OPT_TIMELIMIT
 110 Sets/gets the value that defines the time limit after which
 111 a search operation should be terminated by the server.
 112 .BR outvalue
 113 and
 114 .BR invalue
 115 must be
 116 .BR "int *" ,
 117 and they cannot be NULL.
 118 .TP
 119 .B LDAP_OPT_REFERRALS
 120 Determines whether the library should implicitly chase referrals or not.
 121 .BR outvalue
 122 and
 123 .BR invalue
 124 must be
 125 .BR "int *" ;
 126 their value should either be
 127 .BR LDAP_OPT_OFF
 128 or
 129 .BR LDAP_OPT_ON .
 130 .TP
 131 .B LDAP_OPT_RESTART
 132 Determines whether the library should implicitly restart connections (FIXME).
 133 .BR outvalue
 134 and
 135 .BR invalue
 136 must be
 137 .BR "int *" ;
 138 their value should either be
 139 .BR LDAP_OPT_OFF
 140 or
 141 .BR LDAP_OPT_ON .
 142 .TP
 143 .B LDAP_OPT_PROTOCOL_VERSION
 144 Sets/gets the protocol version.
 145 .BR outvalue
 146 and
 147 .BR invalue
 148 must be
 149 .BR "int *" .
 150 .TP
 151 .B LDAP_OPT_SERVER_CONTROLS
 152 Sets/gets the server-side controls to be used for all operations.
 153 This is now deprecated as modern LDAP C API provides replacements
 154 for all main operations which accepts server-side controls as
 155 explicit arguments; see for example
 156 .BR ldap_search_ext (3),
 157 .BR ldap_add_ext (3),
 158 .BR ldap_modify_ext (3)
 159 and so on.
 160 .BR outvalue
 161 must be
 162 .BR "LDAPControl ***" ,
 163 and the caller is responsible of freeing the returned controls, if any,
 164 by calling
 165 .BR ldap_controls_free (3),
 166 while
 167 .BR invalue
 168 must be
 169 .BR "LDAPControl **" ;
 170 the library duplicates the controls passed via
 171 .BR invalue .
 172 .TP
 173 .B LDAP_OPT_CLIENT_CONTROLS
 174 Sets/gets the client-side controls to be used for all operations.
 175 This is now deprecated as modern LDAP C API provides replacements
 176 for all main operations which accepts client-side controls as
 177 explicit arguments; see for example
 178 .BR ldap_search_ext (3),
 179 .BR ldap_add_ext (3),
 180 .BR ldap_modify_ext (3)
 181 and so on.
 182 .BR outvalue
 183 must be
 184 .BR "LDAPControl ***" ,
 185 and the caller is responsible of freeing the returned controls, if any,
 186 by calling
 187 .BR ldap_controls_free (3),
 188 while
 189 .BR invalue
 190 must be
 191 .BR "LDAPControl **" ;
 192 the library duplicates the controls passed via
 193 .BR invalue .
 194 .TP
 195 .B LDAP_OPT_HOST_NAME
 196 Sets/gets a space-separated list of hosts to be contacted by the library
 197 when trying to establish a connection.
 198 This is now deprecated in favor of
 199 .BR LDAP_OPT_URI .
 200 .BR outvalue
 201 must be a
 202 .BR "char **" ,
 203 and the caller is responsible of freeing the resulting string by calling
 204 .BR ldap_memfree (3),
 205 while
 206 .BR invalue
 207 must be a
 208 .BR "char *" ;
 209 the library duplicates the corresponding string.
 210 .TP
 211 .B LDAP_OPT_URI
 212 Sets/gets a space-separated list of URIs to be contacted by the library
 213 when trying to establish a connection.
 214 .BR outvalue
 215 must be a
 216 .BR "char **" ,
 217 and the caller is responsible of freeing the resulting string by calling
 218 .BR ldap_memfree (3),
 219 while
 220 .BR invalue
 221 must be a
 222 .BR "char *" ;
 223 the library parses the string into a list of
 224 .BR LDAPURLDesc
 225 structures, so the invocation of
 226 .BR ldap_set_option (3)
 227 may fail if URL parsing fails.
 228 .TP
 229 .B LDAP_OPT_DEFBASE
 230 Sets/gets a string containing the DN to be used as default base
 231 for search operations.
 232 .BR outvalue
 233 must be a
 234 .BR "char **" ,
 235 and the caller is responsible of freeing the returned string by calling
 236 .BR ldap_memfree (3),
 237 while
 238 .BR invalue
 239 must be a
 240 .BR "char *" ;
 241 the library duplicates the corresponding string.
 242 .TP
 243 .B LDAP_OPT_RESULT_CODE
 244 Sets/gets the LDAP result code associated to the handle.
 245 This option was formerly known as
 246 .BR LDAP_OPT_ERROR_NUMBER .
 247 Both
 248 .BR outvalue
 249 and
 250 .BR invalue
 251 must be a
 252 .BR "int *" .
 253 .TP
 254 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
 255 Sets/gets a string containing the error string associated to the LDAP handle.
 256 This option was formerly known as
 257 .BR LDAP_OPT_ERROR_STRING .
 258 .BR outvalue
 259 must be a
 260 .BR "char **" ,
 261 and the caller is responsible of freeing the returned string by calling
 262 .BR ldap_memfree (3),
 263 while
 264 .BR invalue
 265 must be a
 266 .BR "char *" ;
 267 the library duplicates the corresponding string.
 268 .TP
 269 .B LDAP_OPT_MATCHED_DN
 270 Sets/gets a string containing the matched DN associated to the LDAP handle.
 271 .BR outvalue
 272 must be a
 273 .BR "char **" ,
 274 and the caller is responsible of freeing the returned string by calling
 275 .BR ldap_memfree (3),
 276 while
 277 .BR invalue
 278 must be a
 279 .BR "char *" ;
 280 the library duplicates the corresponding string.
 281 .TP
 282 .B LDAP_OPT_REFERRAL_URLS
 283 Sets/gets an array containing the referral URIs associated to the LDAP handle.
 284 .BR outvalue
 285 must be a
 286 .BR "char ***" ,
 287 and the caller is responsible of freeing the returned string by calling
 288 .BR ber_memvfree (3),
 289 while
 290 .BR invalue
 291 must be a NULL-terminated
 292 .BR "char **" ;
 293 the library duplicates the corresponding string.
 294 .TP
 295 .B LDAP_OPT_API_FEATURE_INFO
 296 Fills-in a
 297 .BR "LDAPAPIFeatureInfo" ;
 298 .BR outvalue
 299 must be a
 300 .BR "LDAPAPIFeatureInfo *" ,
 301 pointing to an already allocated struct.
 302 This is a read-only option.
 303 .TP
 304 .B LDAP_OPT_DEBUG_LEVEL
 305 Sets/gets the debug level of the client library.
 306 Both
 307 .BR outvalue
 308 and
 309 .BR invalue
 310 must be a
 311 .BR "int *" .
 312 .SH ERRORS
 313 On success, the functions return
 314 .BR LDAP_OPT_SUCCESS ,
 315 while they may return
 316 .B LDAP_OPT_ERROR
 317 to indicate a generic option handling error.
 318 Occasionally, more specific errors can be returned, like
 319 .B LDAP_NO_MEMORY
 320 to indicate a failure in memory allocation.
 321 .SH NOTES
 322 The LDAP libraries with the
 323 .B LDAP_OPT_REFERRALS
 324 option set to
 325 .B LDAP_OPT_ON
 326 (default value) automatically follow referrals using an anonymous bind.
 327 Application developers are encouraged to either implement consistent
 328 referral chasing features, or explicitly disable referral chasing
 329 by setting that option to
 330 .BR LDAP_OPT_OFF .
 331 .SH SEE ALSO
 332 .BR ldap (3),
 333 .BR ldap_error (3),
 334 .B RFC 4422
 335 (http://www.rfc-editor.org),
 336 .SH ACKNOWLEDGEMENTS
 337 .\" Shared Project Acknowledgement Text
 338 .B "OpenLDAP Software"
 339 is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
 340 .B "OpenLDAP Software"
 341 is derived from University of Michigan LDAP 3.3 Release.