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

   1 .TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2007 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 and
  62 .B invalue
  63 must be a
  64 .BR "struct timeval *" ,
  65 and they cannot be NULL. Using a struct with seconds set to -1 results
  66 in an infinite timeout, which is the default.
  67 .TP
  68 .B LDAP_OPT_NETWORK_TIMEOUT
  69 Sets/gets the network timeout value after which
  70 .BR poll (2)/ select (2)
  71 following a
  72 .BR connect (2)
  73 returns in case of no activity.
  74 .B outvalue
  75 and
  76 .B invalue
  77 must be a
  78 .BR "struct timeval *" ,
  79 and they cannot be NULL. Using a struct with seconds set to -1 results
  80 in an infinite timeout, which is the default.
  81 .TP
  82 .B LDAP_OPT_DEREF
  83 Sets/gets the value that defines when alias dereferencing must occur.
  84 .BR outvalue
  85 and
  86 .BR invalue
  87 must be
  88 .BR "int *" ,
  89 and they cannot be NULL.
  90 .TP
  91 .B LDAP_OPT_SIZELIMIT
  92 Sets/gets the value that defines the maximum number of entries
  93 to be returned by a search operation.
  94 .BR outvalue
  95 and
  96 .BR invalue
  97 must be
  98 .BR "int *" ,
  99 and they cannot be NULL.
 100 .TP
 101 .B LDAP_OPT_TIMELIMIT
 102 Sets/gets the value that defines the time limit after which
 103 a search operation should be terminated by the server.
 104 .BR outvalue
 105 and
 106 .BR invalue
 107 must be
 108 .BR "int *" ,
 109 and they cannot be NULL.
 110 .TP
 111 .B LDAP_OPT_REFERRALS
 112 Determines whether the library should implicitly chase referrals or not.
 113 .BR outvalue
 114 and
 115 .BR invalue
 116 must be
 117 .BR "int *" ;
 118 their value should either be
 119 .BR LDAP_OPT_OFF
 120 or
 121 .BR LDAP_OPT_ON .
 122 .TP
 123 .B LDAP_OPT_RESTART
 124 Determines whether the library should implicitly restart connections (FIXME).
 125 .BR outvalue
 126 and
 127 .BR invalue
 128 must be
 129 .BR "int *" ;
 130 their value should either be
 131 .BR LDAP_OPT_OFF
 132 or
 133 .BR LDAP_OPT_ON .
 134 .TP
 135 .B LDAP_OPT_PROTOCOL_VERSION
 136 Sets/gets the protocol version.
 137 .BR outvalue
 138 and
 139 .BR invalue
 140 must be
 141 .BR "int *" .
 142 .TP
 143 .B LDAP_OPT_SERVER_CONTROLS
 144 Sets/gets the server-side controls to be used for all operations.
 145 This is now deprecated as modern LDAP C API provides replacements
 146 for all main operations which accepts server-side controls as
 147 explicit arguments; see for example
 148 .BR ldap_search_ext (3),
 149 .BR ldap_add_ext (3),
 150 .BR ldap_modify_ext (3)
 151 and so on.
 152 .BR outvalue
 153 must be
 154 .BR "LDAPControl ***" ,
 155 and the caller is responsible of freeing the returned controls, if any,
 156 by calling
 157 .BR ldap_controls_free (3),
 158 while
 159 .BR invalue
 160 must be
 161 .BR "LDAPControl **" ;
 162 the library duplicates the controls passed via
 163 .BR invalue .
 164 .TP
 165 .B LDAP_OPT_CLIENT_CONTROLS
 166 Sets/gets the client-side controls to be used for all operations.
 167 This is now deprecated as modern LDAP C API provides replacements
 168 for all main operations which accepts client-side controls as
 169 explicit arguments; see for example
 170 .BR ldap_search_ext (3),
 171 .BR ldap_add_ext (3),
 172 .BR ldap_modify_ext (3)
 173 and so on.
 174 .BR outvalue
 175 must be
 176 .BR "LDAPControl ***" ,
 177 and the caller is responsible of freeing the returned controls, if any,
 178 by calling
 179 .BR ldap_controls_free (3),
 180 while
 181 .BR invalue
 182 must be
 183 .BR "LDAPControl **" ;
 184 the library duplicates the controls passed via
 185 .BR invalue .
 186 .TP
 187 .B LDAP_OPT_HOST_NAME
 188 Sets/gets a space-separated list of hosts to be contacted by the library
 189 when trying to establish a connection.
 190 This is now deprecated in favor of
 191 .BR LDAP_OPT_URI .
 192 .BR outvalue
 193 must be a
 194 .BR "char **" ,
 195 and the caller is responsible of freeing the resulting string by calling
 196 .BR ldap_memfree (3),
 197 while
 198 .BR invalue
 199 must be a
 200 .BR "char *" ;
 201 the library duplicates the corresponding string.
 202 .TP
 203 .B LDAP_OPT_URI
 204 Sets/gets a space-separated list of URIs to be contacted by the library
 205 when trying to establish a connection.
 206 .BR outvalue
 207 must be a
 208 .BR "char **" ,
 209 and the caller is responsible of freeing the resulting string by calling
 210 .BR ldap_memfree (3),
 211 while
 212 .BR invalue
 213 must be a
 214 .BR "char *" ;
 215 the library parses the string into a list of
 216 .BR LDAPURLDesc
 217 structures, so the invocation of
 218 .BR ldap_set_option (3)
 219 may fail if URL parsing fails.
 220 .TP
 221 .B LDAP_OPT_DEFBASE
 222 Sets/gets a string containing the DN to be used as default base
 223 for search operations.
 224 .BR outvalue
 225 must be a
 226 .BR "char **" ,
 227 and the caller is responsible of freeing the returned string by calling
 228 .BR ldap_memfree (3),
 229 while
 230 .BR invalue
 231 must be a
 232 .BR "char *" ;
 233 the library duplicates the corresponding string.
 234 .TP
 235 .B LDAP_OPT_RESULT_CODE
 236 Sets/gets the LDAP result code associated to the handle.
 237 This option was formerly known as
 238 .BR LDAP_OPT_ERROR_NUMBER .
 239 Both
 240 .BR outvalue
 241 and
 242 .BR invalue
 243 must be a
 244 .BR "int *" .
 245 .TP
 246 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
 247 Sets/gets a string containing the error string associated to the LDAP handle.
 248 This option was formerly known as
 249 .BR LDAP_OPT_ERROR_STRING .
 250 .BR outvalue
 251 must be a
 252 .BR "char **" ,
 253 and the caller is responsible of freeing the returned string by calling
 254 .BR ldap_memfree (3),
 255 while
 256 .BR invalue
 257 must be a
 258 .BR "char *" ;
 259 the library duplicates the corresponding string.
 260 .TP
 261 .B LDAP_OPT_MATCHED_DN
 262 Sets/gets a string containing the matched DN associated to the LDAP handle.
 263 .BR outvalue
 264 must be a
 265 .BR "char **" ,
 266 and the caller is responsible of freeing the returned string by calling
 267 .BR ldap_memfree (3),
 268 while
 269 .BR invalue
 270 must be a
 271 .BR "char *" ;
 272 the library duplicates the corresponding string.
 273 .TP
 274 .B LDAP_OPT_REFERRAL_URLS
 275 Sets/gets an array containing the referral URIs associated to the LDAP handle.
 276 .BR outvalue
 277 must be a
 278 .BR "char ***" ,
 279 and the caller is responsible of freeing the returned string by calling
 280 .BR ber_memvfree (3),
 281 while
 282 .BR invalue
 283 must be a NULL-terminated
 284 .BR "char **" ;
 285 the library duplicates the corresponding string.
 286 .TP
 287 .B LDAP_OPT_API_FEATURE_INFO
 288 Fills-in a
 289 .BR "LDAPAPIFeatureInfo" ;
 290 .BR outvalue
 291 must be a
 292 .BR "LDAPAPIFeatureInfo *" ,
 293 pointing to an already allocated struct.
 294 This is a read-only option.
 295 .TP
 296 .B LDAP_OPT_DEBUG_LEVEL
 297 Sets/gets the debug level of the client library.
 298 Both
 299 .BR outvalue
 300 and
 301 .BR invalue
 302 must be a
 303 .BR "int *" .
 304 .SH ERRORS
 305 On success, the functions return
 306 .BR LDAP_OPT_SUCCESS ,
 307 while they may return
 308 .B LDAP_OPT_ERROR
 309 to indicate a generic option handling error.
 310 Occasionally, more specific errors can be returned, like
 311 .B LDAP_NO_MEMORY
 312 to indicate a failure in memory allocation.
 313 .SH NOTES
 314 The LDAP libraries with the
 315 .B LDAP_OPT_REFERRALS
 316 option set to
 317 .B LDAP_OPT_ON
 318 (default value) automatically follow referrals using an anonymous bind.
 319 Application developers are encouraged to either implement consistent
 320 referral chasing features, or explicitly disable referral chasing
 321 by setting that option to
 322 .BR LDAP_OPT_OFF .
 323 .SH SEE ALSO
 324 .BR ldap (3),
 325 .BR ldap_error (3),
 326 .B RFC 4422
 327 (http://www.rfc-editor.org),
 328 .SH ACKNOWLEDGEMENTS
 329 .so ../Project