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