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-2009 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_FEATURE_INFO
  33 Fills-in a
  34 .BR "LDAPAPIFeatureInfo" ;
  35 .BR outvalue
  36 must be a
  37 .BR "LDAPAPIFeatureInfo *" ,
  38 pointing to an already allocated struct.
  39 This is a read-only option.
  40 .TP
  41 .B LDAP_OPT_API_INFO
  42 Fills-in a
  43 .BR "struct ldapapiinfo" ;
  44 .BR outvalue
  45 must be a
  46 .BR "struct ldapapiinfo *" ,
  47 pointing to an already allocated struct.
  48 This is a read-only option.
  49 .TP
  50 .B LDAP_OPT_CLIENT_CONTROLS
  51 Sets/gets the client-side controls to be used for all operations.
  52 This is now deprecated as modern LDAP C API provides replacements
  53 for all main operations which accepts client-side controls as
  54 explicit arguments; see for example
  55 .BR ldap_search_ext (3),
  56 .BR ldap_add_ext (3),
  57 .BR ldap_modify_ext (3)
  58 and so on.
  59 .BR outvalue
  60 must be
  61 .BR "LDAPControl ***" ,
  62 and the caller is responsible of freeing the returned controls, if any,
  63 by calling
  64 .BR ldap_controls_free (3),
  65 while
  66 .BR invalue
  67 must be
  68 .BR "LDAPControl **" ;
  69 the library duplicates the controls passed via
  70 .BR invalue .
  71 .TP
  72 .B LDAP_OPT_CONNECT_ASYNC
  73 Sets/gets the status of the asynchronous connect flag.
  74 The value should either be
  75 .BR LDAP_OPT_OFF
  76 or
  77 .BR LDAP_OPT_ON .
  78 When set, the library will call
  79 .BR connect (2)
  80 and return, without waiting for response.
  81 This leaves the handler in a connecting state.
  82 Subsequent calls to library routines will poll for completion
  83 of the connect before performing further operations.
  84 As a consequence, library calls that need to establish a connection
  85 with a DSA do not block even for the network timeout
  86 (option
  87 .BR LDAP_OPT_NETWORK_TIMEOUT ).
  88 This option is OpenLDAP specific.
  89 .TP
  90 .B LDAP_OPT_CONNECT_CB
  91 This option allows to set a connect callback.
  92 The
  93 .B invalue
  94 must be a pointer to a
  95 .IR "struct ldap_conncb" .
  96 Callbacks are executed in last in-first served order.
  97 Hanlder-specific callbacks are executed first, followed by global ones.
  98 Right before freeing the callback structure, the
  99 .I lc_del
 100 callback handler is passed a
 101 .B NULL
 102 .IR Sockbuf .
 103 Calling
 104 .BR ldap_get_option (3)
 105 for this option removes the callback whose pointer matches
 106 .BR outvalue .
 107 This option is OpenLDAP specific.
 108 .TP
 109 .B LDAP_OPT_DEBUG_LEVEL
 110 Sets/gets the debug level of the client library.
 111 Both
 112 .BR outvalue
 113 and
 114 .BR invalue
 115 must be a
 116 .BR "int *" .
 117 This option is OpenLDAP specific.
 118 .TP
 119 .B LDAP_OPT_DEFBASE
 120 Sets/gets a string containing the DN to be used as default base
 121 for search operations.
 122 .BR outvalue
 123 must be a
 124 .BR "char **" ,
 125 and the caller is responsible of freeing the returned string by calling
 126 .BR ldap_memfree (3),
 127 while
 128 .BR invalue
 129 must be a
 130 .BR "char *" ;
 131 the library duplicates the corresponding string.
 132 This option is OpenLDAP specific.
 133 .TP
 134 .B LDAP_OPT_DEREF
 135 Sets/gets the value that defines when alias dereferencing must occur.
 136 .BR outvalue
 137 and
 138 .BR invalue
 139 must be
 140 .BR "int *" ,
 141 and they cannot be NULL.
 142 The value of
 143 .BR *invalue
 144 should be one of
 145 .BR LDAP_DEREF_NEVER
 146 (the default),
 147 .BR LDAP_DEREF_SEARCHING ,
 148 .BR LDAP_DEREF_FINDING ,
 149 or
 150 .BR LDAP_DEREF_ALWAYS .
 151 Note that this has ever been the only means to determine alias dereferencing
 152 within search operations.
 153 .TP
 154 .B LDAP_OPT_DESC
 155 Returns the file descriptor associated to the socket buffer
 156 of the LDAP handle passed in as
 157 .BR ld ;
 158 .BR outvalue
 159 must be a
 160 .BR "int *" .
 161 This is a read-only, handler-specific option.
 162 .TP
 163 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
 164 Sets/gets a string containing the error string associated to the LDAP handle.
 165 This option was formerly known as
 166 .BR LDAP_OPT_ERROR_STRING .
 167 .BR outvalue
 168 must be a
 169 .BR "char **" ,
 170 and the caller is responsible of freeing the returned string by calling
 171 .BR ldap_memfree (3),
 172 while
 173 .BR invalue
 174 must be a
 175 .BR "char *" ;
 176 the library duplicates the corresponding string.
 177 .TP
 178 .B LDAP_OPT_HOST_NAME
 179 Sets/gets a space-separated list of hosts to be contacted by the library
 180 when trying to establish a connection.
 181 This is now deprecated in favor of
 182 .BR LDAP_OPT_URI .
 183 .BR outvalue
 184 must be a
 185 .BR "char **" ,
 186 and the caller is responsible of freeing the resulting string by calling
 187 .BR ldap_memfree (3),
 188 while
 189 .BR invalue
 190 must be a
 191 .BR "char *" ;
 192 the library duplicates the corresponding string.
 193 .TP
 194 .B LDAP_OPT_MATCHED_DN
 195 Sets/gets a string containing the matched DN associated to the LDAP handle.
 196 .BR outvalue
 197 must be a
 198 .BR "char **" ,
 199 and the caller is responsible of freeing the returned string by calling
 200 .BR ldap_memfree (3),
 201 while
 202 .BR invalue
 203 must be a
 204 .BR "char *" ;
 205 the library duplicates the corresponding string.
 206 .TP
 207 .B LDAP_OPT_NETWORK_TIMEOUT
 208 Sets/gets the network timeout value after which
 209 .BR poll (2)/ select (2)
 210 following a
 211 .BR connect (2)
 212 returns in case of no activity.
 213 .B outvalue
 214 must be a
 215 .BR "struct timeval **"
 216 (the caller has to free
 217 .BR *outvalue ) ,
 218 and
 219 .B invalue
 220 must be a
 221 .BR "struct timeval *" ,
 222 and they cannot be NULL. Using a struct with seconds set to \-1 results
 223 in an infinite timeout, which is the default.
 224 This option is OpenLDAP specific.
 225 .TP
 226 .B LDAP_OPT_PROTOCOL_VERSION
 227 Sets/gets the protocol version.
 228 .BR outvalue
 229 and
 230 .BR invalue
 231 must be
 232 .BR "int *" .
 233 .TP
 234 .B LDAP_OPT_REFERRAL_URLS
 235 Sets/gets an array containing the referral URIs associated to the LDAP handle.
 236 .BR outvalue
 237 must be a
 238 .BR "char ***" ,
 239 and the caller is responsible of freeing the returned string by calling
 240 .BR ber_memvfree (3),
 241 while
 242 .BR invalue
 243 must be a NULL-terminated
 244 .BR "char **" ;
 245 the library duplicates the corresponding string.
 246 This option is OpenLDAP specific.
 247 .TP
 248 .B LDAP_OPT_REFERRALS
 249 Determines whether the library should implicitly chase referrals or not.
 250 .BR outvalue
 251 and
 252 .BR invalue
 253 must be
 254 .BR "int *" ;
 255 their value should either be
 256 .BR LDAP_OPT_OFF
 257 or
 258 .BR LDAP_OPT_ON .
 259 .TP
 260 .B LDAP_OPT_REFHOPLIMIT
 261 This option is OpenLDAP specific.
 262 It is not currently implemented.
 263 .TP
 264 .B LDAP_OPT_RESTART
 265 Determines whether the library should implicitly restart connections (FIXME).
 266 .BR outvalue
 267 and
 268 .BR invalue
 269 must be
 270 .BR "int *" ;
 271 their value should either be
 272 .BR LDAP_OPT_OFF
 273 or
 274 .BR LDAP_OPT_ON .
 275 .TP
 276 .B LDAP_OPT_RESULT_CODE
 277 Sets/gets the LDAP result code associated to the handle.
 278 This option was formerly known as
 279 .BR LDAP_OPT_ERROR_NUMBER .
 280 Both
 281 .BR outvalue
 282 and
 283 .BR invalue
 284 must be a
 285 .BR "int *" .
 286 .TP
 287 .B LDAP_OPT_SERVER_CONTROLS
 288 Sets/gets the server-side controls to be used for all operations.
 289 This is now deprecated as modern LDAP C API provides replacements
 290 for all main operations which accepts server-side controls as
 291 explicit arguments; see for example
 292 .BR ldap_search_ext (3),
 293 .BR ldap_add_ext (3),
 294 .BR ldap_modify_ext (3)
 295 and so on.
 296 .BR outvalue
 297 must be
 298 .BR "LDAPControl ***" ,
 299 and the caller is responsible of freeing the returned controls, if any,
 300 by calling
 301 .BR ldap_controls_free (3),
 302 while
 303 .BR invalue
 304 must be
 305 .BR "LDAPControl **" ;
 306 the library duplicates the controls passed via
 307 .BR invalue .
 308 .TP
 309 .B LDAP_OPT_SIZELIMIT
 310 Sets/gets the value that defines the maximum number of entries
 311 to be returned by a search operation.
 312 .BR outvalue
 313 and
 314 .BR invalue
 315 must be
 316 .BR "int *" ,
 317 and they cannot be NULL.
 318 .TP
 319 .B LDAP_OPT_SOCKBUF
 320 Returns a pointer to the socket buffer of the LDAP handle passed in as
 321 .BR ld ;
 322 .BR outvalue
 323 must be a
 324 .BR "Sockbuf **" .
 325 This is a read-only, handler-specific option.
 326 This option is OpenLDAP specific.
 327 .TP
 328 .B LDAP_OPT_TIMELIMIT
 329 Sets/gets the value that defines the time limit after which
 330 a search operation should be terminated by the server.
 331 .BR outvalue
 332 and
 333 .BR invalue
 334 must be
 335 .BR "int *" ,
 336 and they cannot be NULL.
 337 .TP
 338 .B LDAP_OPT_TIMEOUT
 339 Sets/gets a timeout value for the synchronous API calls.
 340 .B outvalue
 341 must be a
 342 .BR "struct timeval **"
 343 (the caller has to free
 344 .BR *outvalue ) ,
 345 and
 346 .B invalue
 347 must be a
 348 .BR "struct timeval *" ,
 349 and they cannot be NULL. Using a struct with seconds set to \-1 results
 350 in an infinite timeout, which is the default.
 351 This option is OpenLDAP specific.
 352 .TP
 353 .B LDAP_OPT_URI
 354 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
 355 when trying to establish a connection.
 356 .BR outvalue
 357 must be a
 358 .BR "char **" ,
 359 and the caller is responsible of freeing the resulting string by calling
 360 .BR ldap_memfree (3),
 361 while
 362 .BR invalue
 363 must be a
 364 .BR "char *" ;
 365 the library parses the string into a list of
 366 .BR LDAPURLDesc
 367 structures, so the invocation of
 368 .BR ldap_set_option (3)
 369 may fail if URL parsing fails.
 370 URIs may only contain the
 371 .BR schema ,
 372 the
 373 .BR host ,
 374 and the
 375 .BR port
 376 fields.
 377 This option is OpenLDAP specific.
 378 .SH SASL OPTIONS
 379 The SASL options are OpenLDAP specific.
 380 .TP
 381 .B LDAP_OPT_X_SASL_MECH
 382 Gets the SASL mechanism;
 383 .BR outvalue
 384 must be a
 385 .BR "char **" ,
 386 its content needs to be freed by the caller.
 387 .TP
 388 .B LDAP_OPT_X_SASL_REALM
 389 Gets the SASL realm;
 390 .BR outvalue
 391 must be a
 392 .BR "char **" ,
 393 its content needs to be freed by the caller.
 394 .TP
 395 .B LDAP_OPT_X_SASL_AUTHCID
 396 Gets the SASL authentication identity;
 397 .BR outvalue
 398 must be a
 399 .BR "char **" ,
 400 its content needs to be freed by the caller.
 401 .TP
 402 .B LDAP_OPT_X_SASL_AUTHZID
 403 Gets the SASL authorization identity;
 404 .BR outvalue
 405 must be a
 406 .BR "char **" ,
 407 its content needs to be freed by the caller.
 408 .TP
 409 .B LDAP_OPT_X_SASL_SSF
 410 Gets the SASL SSF;
 411 .BR outvalue
 412 must be a
 413 .BR "int *" .
 414 .TP
 415 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
 416 Sets the SASL SSF value related to an authentication
 417 performed using an EXTERNAL mechanism;
 418 .BR invalue
 419 must be a
 420 .BR "ber_len_t *" .
 421 .TP
 422 .B LDAP_OPT_X_SASL_SECPROPS
 423 Set the SASL secprops;
 424 .BR invalue
 425 must be a
 426 .BR "char *" ,
 427 containing a comma-separated list of properties.
 428 Legal values are:
 429 .BR none ,
 430 .BR nodict ,
 431 .BR noplain ,
 432 .BR noactive ,
 433 .BR passcred ,
 434 .BR forwardsec ,
 435 .BR noanonymous ,
 436 .BR minssf=<minssf> ,
 437 .BR maxssf=<maxssf> ,
 438 .BR maxbufsize=<maxbufsize> ,
 439 with
 440 .BR "minssf >= 0" ,
 441 .BR "maxssf <= 2**31 - 1" ,
 442 .BR "maxbufsize <= 65536" .
 443 .TP
 444 .B LDAP_OPT_X_SASL_SSF_MIN
 445 Gets/sets SASL minimum SSF;
 446 .BR invalue
 447 must be
 448 .BR "const ber_len_t *" ,
 449 while
 450 .BR outvalue
 451 must be
 452 .BR "ber_len_t *" .
 453 See also
 454 .BR LDAP_OPT_X_SASL_SECPROPS .
 455 .TP
 456 .B LDAP_OPT_X_SASL_SSF_MAX
 457 Gets/sets SASL maximum SSF;
 458 .BR invalue
 459 must be
 460 .BR "const ber_len_t *" ,
 461 while
 462 .BR outvalue
 463 must be
 464 .BR "ber_len_t *" .
 465 See also
 466 .BR LDAP_OPT_X_SASL_SECPROPS .
 467 .TP
 468 .B LDAP_OPT_X_SASL_MAXBUFSIZE
 469 Gets/sets SASL maximum buffer size;
 470 .BR invalue
 471 must be
 472 .BR "const ber_len_t *" ,
 473 while
 474 .BR outvalue
 475 must be
 476 .BR "ber_len_t *" .
 477 See also
 478 .BR LDAP_OPT_X_SASL_SECPROPS .
 479 .TP
 480 .B LDAP_OPT_X_SASL_MECHLIST
 481 Gets the list of the available mechanisms,
 482 in form of a NULL-terminated array of strings;
 483 .BR outvalue
 484 must be
 485 .BR "char ***" .
 486 .TP
 487 .B LDAP_OPT_X_SASL_NOCANON
 488 Sets/gets the NOCANON flag.
 489 When unset, the hostname is canonicalized.
 490 The value should either be
 491 .BR LDAP_OPT_OFF
 492 or
 493 .BR LDAP_OPT_ON .
 494 .TP
 495 .B LDAP_OPT_X_SASL_USERNAME
 496 Gets the SASL username;
 497 .BR outvalue
 498 must be a
 499 .BR "char **" .
 500 It points to memory that belongs to the handle;
 501 the caller must not muck with it.
 502 .SH TLS OPTIONS
 503 The TLS options are OpenLDAP specific.
 504 .TP
 505 .B LDAP_OPT_X_TLS
 506 Sets/gets the TLS mode, one of
 507 .BR LDAP_OPT_X_TLS_NEVER ,
 508 .BR LDAP_OPT_X_TLS_HARD ,
 509 .BR LDAP_OPT_X_TLS_DEMAND ,
 510 .BR LDAP_OPT_X_TLS_ALLOW ,
 511 .BR LDAP_OPT_X_TLS_TRY .
 512 .TP
 513 .B LDAP_OPT_X_TLS_CTX
 514 Sets/gets the OpenSSL CTX.
 515 .TP
 516 .B LDAP_OPT_X_TLS_CACERTFILE
 517 Sets/gets the full-path CA certificate file.
 518 .TP
 519 .B LDAP_OPT_X_TLS_CACERTDIR
 520 Sets/gets the path of the directory containing CA certificates.
 521 .TP
 522 .B LDAP_OPT_X_TLS_CERTFILE
 523 Sets/gets the full-path certificate file.
 524 .TP
 525 .B LDAP_OPT_X_TLS_KEYFILE
 526 Sets/gets the full-path certificate key file.
 527 .TP
 528 .B LDAP_OPT_X_TLS_REQUIRE_CERT
 529 Sets/gets the peer certificate checking strategy,
 530 one of
 531 .BR LDAP_OPT_X_TLS_NEVER ,
 532 .BR LDAP_OPT_X_TLS_HARD ,
 533 .BR LDAP_OPT_X_TLS_DEMAND ,
 534 .BR LDAP_OPT_X_TLS_ALLOW ,
 535 .BR LDAP_OPT_X_TLS_TRY .
 536 .TP
 537 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
 538 Sets/gets the minimum protocol version.
 539 .TP
 540 .B LDAP_OPT_X_TLS_CIPHER_SUITE
 541 Sets/gets the allowed cipher suite.
 542 .TP
 543 .B LDAP_OPT_X_TLS_RANDOM_FILE
 544 Sets/gets the random file when
 545 .I /dev/random
 546 and
 547 .I /dev/urandom
 548 are not available.
 549 Ignored by GNUtls.
 550 .TP
 551 .B LDAP_OPT_X_TLS_SSL_CTX
 552 Sets/gets the OpenSSL SSL CTX.
 553 .TP
 554 .B LDAP_OPT_X_TLS_CRLCHECK
 555 Sets/gets the CRL evaluation strategy, one of
 556 .BR LDAP_OPT_X_TLS_CRL_NONE ,
 557 .BR LDAP_OPT_X_TLS_CRL_PEER ,
 558 or
 559 .BR LDAP_OPT_X_TLS_CRL_ALL .
 560 Requires OpenSSL.
 561 .TP
 562 .B LDAP_OPT_X_TLS_CONNECT_CB
 563 Sets/gets the connection callback.
 564 Currently not implemented.
 565 .TP
 566 .B LDAP_OPT_X_TLS_CONNECT_ARG
 567 Sets/gets the connection callback argument.
 568 Currently not implemented.
 569 .TP
 570 .B LDAP_OPT_X_TLS_DHFILE
 571 Gets/sets the full-path of the file containing the parameters
 572 for Diffie-Hellman ephemeral key exchange.
 573 Ignored by GNUtls.
 574 .TP
 575 .B LDAP_OPT_X_TLS_NEWCTX
 576 Instructs the library to create a new TLS CTX.
 577 A non-zero
 578 .BR invalue
 579 tells the library to create a CTX for a server.
 580 .TP
 581 .B LDAP_OPT_X_TLS_CRLFILE
 582 Sets/gets the full-path of the CRL file.
 583 This option is only valid for GNUtls.
 584 .SH ERRORS
 585 On success, the functions return
 586 .BR LDAP_OPT_SUCCESS ,
 587 while they may return
 588 .B LDAP_OPT_ERROR
 589 to indicate a generic option handling error.
 590 Occasionally, more specific errors can be returned, like
 591 .B LDAP_NO_MEMORY
 592 to indicate a failure in memory allocation.
 593 .SH NOTES
 594 The LDAP libraries with the
 595 .B LDAP_OPT_REFERRALS
 596 option set to
 597 .B LDAP_OPT_ON
 598 (default value) automatically follow referrals using an anonymous bind.
 599 Application developers are encouraged to either implement consistent
 600 referral chasing features, or explicitly disable referral chasing
 601 by setting that option to
 602 .BR LDAP_OPT_OFF .
 603 .P
 604 The protocol version used by the library defaults to LDAPv2 (now historic),
 605 which corresponds to the
 606 .B LDAP_VERSION2
 607 macro.
 608 Application developers are encouraged to explicitly set
 609 .B LDAP_OPT_PROTOCOL_VERSION
 610 to LDAPv3, using the
 611 .B LDAP_VERSION3
 612 macro, or to allow users to select the protocol version.
 613 .SH SEE ALSO
 614 .BR ldap (3),
 615 .BR ldap_error (3),
 616 .B RFC 4422
 617 (http://www.rfc-editor.org),
 618 .SH ACKNOWLEDGEMENTS
 619 .so ../Project