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