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-2011 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 "LDAPAPIInfo" ;
  44 .BR outvalue
  45 must be a
  46 .BR "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 *const *" ;
  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 .BR invalue
  75 should either be
  76 .BR LDAP_OPT_OFF
  77 or
  78 .BR LDAP_OPT_ON ;
  79 .BR outvalue
  80 must be
  81 .BR "int *" .
  82 When set, the library will call
  83 .BR connect (2)
  84 and return, without waiting for response.
  85 This leaves the handle in a connecting state.
  86 Subsequent calls to library routines will poll for completion
  87 of the connect before performing further operations.
  88 As a consequence, library calls that need to establish a connection
  89 with a DSA do not block even for the network timeout
  90 (option
  91 .BR LDAP_OPT_NETWORK_TIMEOUT ).
  92 This option is OpenLDAP specific.
  93 .TP
  94 .B LDAP_OPT_CONNECT_CB
  95 This option allows to set a connect callback.
  96 .B invalue
  97 must be a
  98 .BR "const struct ldap_conncb *" .
  99 Callbacks are executed in last in-first served order.
 100 Handle-specific callbacks are executed first, followed by global ones.
 101 Right before freeing the callback structure, the
 102 .B lc_del
 103 callback handler is passed a
 104 .B NULL
 105 .BR Sockbuf .
 106 Calling
 107 .BR ldap_get_option (3)
 108 for this option removes the callback whose pointer matches
 109 .BR outvalue .
 110 This option is OpenLDAP specific.
 111 .TP
 112 .B LDAP_OPT_DEBUG_LEVEL
 113 Sets/gets the debug level of the client library.
 114 .BR invalue
 115 must be a
 116 .BR "const int *" ;
 117 .BR outvalue
 118 must be a
 119 .BR "int *" .
 120 Valid debug levels are
 121 .BR LDAP_DEBUG_ANY ,
 122 .BR LDAP_DEBUG_ARGS ,
 123 .BR LDAP_DEBUG_BER ,
 124 .BR LDAP_DEBUG_CONNS ,
 125 .BR LDAP_DEBUG_NONE ,
 126 .BR LDAP_DEBUG_PACKETS ,
 127 .BR LDAP_DEBUG_PARSE ,
 128 and
 129 .BR LDAP_DEBUG_TRACE .
 130 This option is OpenLDAP specific.
 131 .TP
 132 .B LDAP_OPT_DEFBASE
 133 Sets/gets a string containing the DN to be used as default base
 134 for search operations.
 135 .BR outvalue
 136 must be a
 137 .BR "char **" ,
 138 and the caller is responsible of freeing the returned string by calling
 139 .BR ldap_memfree (3),
 140 while
 141 .BR invalue
 142 must be a
 143 .BR "const char *" ;
 144 the library duplicates the corresponding string.
 145 This option is OpenLDAP specific.
 146 .TP
 147 .B LDAP_OPT_DEREF
 148 Sets/gets the value that defines when alias dereferencing must occur.
 149 .BR invalue
 150 must be
 151 .BR "const int *" ;
 152 .BR outvalue
 153 must be
 154 .BR "int *" .
 155 They cannot be NULL.
 156 The value of
 157 .BR *invalue
 158 should be one of
 159 .BR LDAP_DEREF_NEVER
 160 (the default),
 161 .BR LDAP_DEREF_SEARCHING ,
 162 .BR LDAP_DEREF_FINDING ,
 163 or
 164 .BR LDAP_DEREF_ALWAYS .
 165 Note that this has ever been the only means to determine alias dereferencing
 166 within search operations.
 167 .TP
 168 .B LDAP_OPT_DESC
 169 Returns the file descriptor associated to the socket buffer
 170 of the LDAP handle passed in as
 171 .BR ld ;
 172 .BR outvalue
 173 must be a
 174 .BR "int *" .
 175 This is a read-only, handle-specific option.
 176 .TP
 177 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
 178 Sets/gets a string containing the error string associated to the LDAP handle.
 179 This option was formerly known as
 180 .BR LDAP_OPT_ERROR_STRING .
 181 .BR outvalue
 182 must be a
 183 .BR "char **" ,
 184 and the caller is responsible of freeing the returned string by calling
 185 .BR ldap_memfree (3),
 186 while
 187 .BR invalue
 188 must be a
 189 .BR "char *" ;
 190 the library duplicates the corresponding string.
 191 .TP
 192 .B LDAP_OPT_HOST_NAME
 193 Sets/gets a space-separated list of hosts to be contacted by the library
 194 when trying to establish a connection.
 195 This is now deprecated in favor of
 196 .BR LDAP_OPT_URI .
 197 .BR outvalue
 198 must be a
 199 .BR "char **" ,
 200 and the caller is responsible of freeing the resulting string by calling
 201 .BR ldap_memfree (3),
 202 while
 203 .BR invalue
 204 must be a
 205 .BR "const char *" ;
 206 the library duplicates the corresponding string.
 207 .TP
 208 .B LDAP_OPT_MATCHED_DN
 209 Sets/gets a string containing the matched DN associated to the LDAP handle.
 210 .BR outvalue
 211 must be a
 212 .BR "char **" ,
 213 and the caller is responsible of freeing the returned string by calling
 214 .BR ldap_memfree (3),
 215 while
 216 .BR invalue
 217 must be a
 218 .BR "const char *" ;
 219 the library duplicates the corresponding string.
 220 .TP
 221 .B LDAP_OPT_NETWORK_TIMEOUT
 222 Sets/gets the network timeout value after which
 223 .BR poll (2)/ select (2)
 224 following a
 225 .BR connect (2)
 226 returns in case of no activity.
 227 .B outvalue
 228 must be a
 229 .BR "struct timeval **"
 230 (the caller has to free
 231 .BR *outvalue ) ,
 232 and
 233 .B invalue
 234 must be a
 235 .BR "const struct timeval *" .
 236 They cannot be NULL. Using a struct with seconds set to \-1 results
 237 in an infinite timeout, which is the default.
 238 This option is OpenLDAP specific.
 239 .TP
 240 .B LDAP_OPT_PROTOCOL_VERSION
 241 Sets/gets the protocol version.
 242 .BR outvalue
 243 and
 244 .BR invalue
 245 must be
 246 .BR "int *" .
 247 .TP
 248 .B LDAP_OPT_REFERRAL_URLS
 249 Sets/gets an array containing the referral URIs associated to the LDAP handle.
 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_memvfree (3),
 255 while
 256 .BR invalue
 257 must be a NULL-terminated
 258 .BR "char *const *" ;
 259 the library duplicates the corresponding string.
 260 This option is OpenLDAP specific.
 261 .TP
 262 .B LDAP_OPT_REFERRALS
 263 Determines whether the library should implicitly chase referrals or not.
 264 .BR invalue
 265 must be
 266 .BR "const int *" ;
 267 its value should either be
 268 .BR LDAP_OPT_OFF
 269 or
 270 .BR LDAP_OPT_ON .
 271 .BR outvalue
 272 must be
 273 .BR "int *" .
 274 .\".TP
 275 .\".B LDAP_OPT_REFHOPLIMIT
 276 .\"This option is OpenLDAP specific.
 277 .\"It is not currently implemented.
 278 .TP
 279 .B LDAP_OPT_RESTART
 280 Determines whether the library should implicitly restart connections (FIXME).
 281 .BR invalue
 282 must be
 283 .BR "const int *" ;
 284 its value should either be
 285 .BR LDAP_OPT_OFF
 286 or
 287 .BR LDAP_OPT_ON .
 288 .BR outvalue
 289 must be
 290 .BR "int *" .
 291 .TP
 292 .B LDAP_OPT_RESULT_CODE
 293 Sets/gets the LDAP result code associated to the handle.
 294 This option was formerly known as
 295 .BR LDAP_OPT_ERROR_NUMBER .
 296 .BR invalue
 297 must be a
 298 .BR "const int *" .
 299 .BR outvalue
 300 must be a
 301 .BR "int *" .
 302 .TP
 303 .B LDAP_OPT_SERVER_CONTROLS
 304 Sets/gets the server-side controls to be used for all operations.
 305 This is now deprecated as modern LDAP C API provides replacements
 306 for all main operations which accepts server-side controls as
 307 explicit arguments; see for example
 308 .BR ldap_search_ext (3),
 309 .BR ldap_add_ext (3),
 310 .BR ldap_modify_ext (3)
 311 and so on.
 312 .BR outvalue
 313 must be
 314 .BR "LDAPControl ***" ,
 315 and the caller is responsible of freeing the returned controls, if any,
 316 by calling
 317 .BR ldap_controls_free (3),
 318 while
 319 .BR invalue
 320 must be
 321 .BR "LDAPControl *const *" ;
 322 the library duplicates the controls passed via
 323 .BR invalue .
 324 .TP
 325 .B LDAP_OPT_SIZELIMIT
 326 Sets/gets the value that defines the maximum number of entries
 327 to be returned by a search operation.
 328 .BR invalue
 329 must be
 330 .BR "const int *" ,
 331 while
 332 .BR outvalue
 333 must be
 334 .BR "int *" ;
 335 They cannot be NULL.
 336 .TP
 337 .B LDAP_OPT_SOCKBUF
 338 Returns a pointer to the socket buffer of the LDAP handle passed in as
 339 .BR ld ;
 340 .BR outvalue
 341 must be a
 342 .BR "Sockbuf **" .
 343 This is a read-only, handle-specific option.
 344 This option is OpenLDAP specific.
 345 .TP
 346 .B LDAP_OPT_TIMELIMIT
 347 Sets/gets the value that defines the time limit after which
 348 a search operation should be terminated by the server.
 349 .BR invalue
 350 must be
 351 .BR "const int *" ,
 352 while
 353 .BR outvalue
 354 must be
 355 .BR "int *" ,
 356 and they cannot be NULL.
 357 .TP
 358 .B LDAP_OPT_TIMEOUT
 359 Sets/gets a timeout value for the synchronous API calls.
 360 .B outvalue
 361 must be a
 362 .BR "struct timeval **"
 363 (the caller has to free
 364 .BR *outvalue ) ,
 365 and
 366 .B invalue
 367 must be a
 368 .BR "struct timeval *" ,
 369 and they cannot be NULL. Using a struct with seconds set to \-1 results
 370 in an infinite timeout, which is the default.
 371 This option is OpenLDAP specific.
 372 .TP
 373 .B LDAP_OPT_URI
 374 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
 375 when trying to establish a connection.
 376 .BR outvalue
 377 must be a
 378 .BR "char **" ,
 379 and the caller is responsible of freeing the resulting string by calling
 380 .BR ldap_memfree (3),
 381 while
 382 .BR invalue
 383 must be a
 384 .BR "const char *" ;
 385 the library parses the string into a list of
 386 .BR LDAPURLDesc
 387 structures, so the invocation of
 388 .BR ldap_set_option (3)
 389 may fail if URL parsing fails.
 390 URIs may only contain the
 391 .BR schema ,
 392 the
 393 .BR host ,
 394 and the
 395 .BR port
 396 fields.
 397 This option is OpenLDAP specific.
 398 .SH SASL OPTIONS
 399 The SASL options are OpenLDAP specific.
 400 .TP
 401 .B LDAP_OPT_X_SASL_AUTHCID
 402 Gets the SASL authentication identity;
 403 .BR outvalue
 404 must be a
 405 .BR "char **" ,
 406 its content needs to be freed by the caller using
 407 .BR ldap_memfree (3).
 408 .TP
 409 .B LDAP_OPT_X_SASL_AUTHZID
 410 Gets the SASL authorization identity;
 411 .BR outvalue
 412 must be a
 413 .BR "char **" ,
 414 its content needs to be freed by the caller using
 415 .BR ldap_memfree (3).
 416 .TP
 417 .B LDAP_OPT_X_SASL_MAXBUFSIZE
 418 Gets/sets SASL maximum buffer size;
 419 .BR invalue
 420 must be
 421 .BR "const ber_len_t *" ,
 422 while
 423 .BR outvalue
 424 must be
 425 .BR "ber_len_t *" .
 426 See also
 427 .BR LDAP_OPT_X_SASL_SECPROPS .
 428 .TP
 429 .B LDAP_OPT_X_SASL_MECH
 430 Gets the SASL mechanism;
 431 .BR outvalue
 432 must be a
 433 .BR "char **" ,
 434 its content needs to be freed by the caller using
 435 .BR ldap_memfree (3).
 436 .TP
 437 .B LDAP_OPT_X_SASL_MECHLIST
 438 Gets the list of the available mechanisms,
 439 in form of a NULL-terminated array of strings;
 440 .BR outvalue
 441 must be
 442 .BR "char ***" .
 443 The caller must not free or otherwise muck with it.
 444 .TP
 445 .B LDAP_OPT_X_SASL_NOCANON
 446 Sets/gets the NOCANON flag.
 447 When unset, the hostname is canonicalized.
 448 .BR invalue
 449 must be
 450 .BR "const int *" ;
 451 its value should either be
 452 .BR LDAP_OPT_OFF
 453 or
 454 .BR LDAP_OPT_ON .
 455 .BR outvalue
 456 must be
 457 .BR "int *" .
 458 .TP
 459 .B LDAP_OPT_X_SASL_REALM
 460 Gets the SASL realm;
 461 .BR outvalue
 462 must be a
 463 .BR "char **" ,
 464 its content needs to be freed by the caller using
 465 .BR ldap_memfree (3).
 466 .TP
 467 .B LDAP_OPT_X_SASL_SECPROPS
 468 Sets the SASL secprops;
 469 .BR invalue
 470 must be a
 471 .BR "char *" ,
 472 containing a comma-separated list of properties.
 473 Legal values are:
 474 .BR none ,
 475 .BR nodict ,
 476 .BR noplain ,
 477 .BR noactive ,
 478 .BR passcred ,
 479 .BR forwardsec ,
 480 .BR noanonymous ,
 481 .BR minssf=<minssf> ,
 482 .BR maxssf=<maxssf> ,
 483 .BR maxbufsize=<maxbufsize> .
 484 .TP
 485 .B LDAP_OPT_X_SASL_SSF
 486 Gets the SASL SSF;
 487 .BR outvalue
 488 must be a
 489 .BR "ber_len_t *" .
 490 .TP
 491 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
 492 Sets the SASL SSF value related to an authentication
 493 performed using an EXTERNAL mechanism;
 494 .BR invalue
 495 must be a
 496 .BR "const ber_len_t *" .
 497 .TP
 498 .B LDAP_OPT_X_SASL_SSF_MAX
 499 Gets/sets SASL maximum SSF;
 500 .BR invalue
 501 must be
 502 .BR "const ber_len_t *" ,
 503 while
 504 .BR outvalue
 505 must be
 506 .BR "ber_len_t *" .
 507 See also
 508 .BR LDAP_OPT_X_SASL_SECPROPS .
 509 .TP
 510 .B LDAP_OPT_X_SASL_SSF_MIN
 511 Gets/sets SASL minimum SSF;
 512 .BR invalue
 513 must be
 514 .BR "const ber_len_t *" ,
 515 while
 516 .BR outvalue
 517 must be
 518 .BR "ber_len_t *" .
 519 See also
 520 .BR LDAP_OPT_X_SASL_SECPROPS .
 521 .TP
 522 .B LDAP_OPT_X_SASL_USERNAME
 523 Gets the SASL username;
 524 .BR outvalue
 525 must be a
 526 .BR "char **" .
 527 Its content needs to be freed by the caller using
 528 .BR ldap_memfree (3).
 529 .SH TCP OPTIONS
 530 The TCP options are OpenLDAP specific.
 531 Mainly intended for use with Linux, they may not be portable.
 532 .TP
 533 .B LDAP_OPT_X_KEEPALIVE_IDLE
 534 Sets/gets the number of seconds a connection needs to remain idle
 535 before TCP starts sending keepalive probes.
 536 .BR invalue
 537 must be
 538 .BR "const int *" ;
 539 .BR outvalue
 540 must be
 541 .BR "int *" .
 542 .TP
 543 .B LDAP_OPT_X_KEEPALIVE_PROBES
 544 Sets/gets the maximum number of keepalive probes TCP should send
 545 before dropping the connection.
 546 .BR invalue
 547 must be
 548 .BR "const int *" ;
 549 .BR outvalue
 550 must be
 551 .BR "int *" .
 552 .TP
 553 .B LDAP_OPT_X_KEEPALIVE_INTERVAL
 554 Sets/gets the interval in seconds between individual keepalive probes.
 555 .BR invalue
 556 must be
 557 .BR "const int *" ;
 558 .BR outvalue
 559 must be
 560 .BR "int *" .
 561 .SH TLS OPTIONS
 562 The TLS options are OpenLDAP specific.
 563 .\".TP
 564 .\".B LDAP_OPT_X_TLS
 565 .\"Sets/gets the TLS mode.
 566 .TP
 567 .B LDAP_OPT_X_TLS_CACERTDIR
 568 Sets/gets the path of the directory containing CA certificates.
 569 .BR invalue
 570 must be
 571 .BR "const char *" ;
 572 .BR outvalue
 573 must be
 574 .BR "char **" ,
 575 and its contents need to be freed by the caller using
 576 .BR ldap_memfree (3).
 577 .TP
 578 .B LDAP_OPT_X_TLS_CACERTFILE
 579 Sets/gets the full-path of the CA certificate file.
 580 .BR invalue
 581 must be
 582 .BR "const char *" ;
 583 .BR outvalue
 584 must be
 585 .BR "char **" ,
 586 and its contents need to be freed by the caller using
 587 .BR ldap_memfree (3).
 588 .TP
 589 .B LDAP_OPT_X_TLS_CERTFILE
 590 Sets/gets the full-path of the certificate file.
 591 .BR invalue
 592 must be
 593 .BR "const char *" ;
 594 .BR outvalue
 595 must be
 596 .BR "char **" ,
 597 and its contents need to be freed by the caller using
 598 .BR ldap_memfree (3).
 599 .TP
 600 .B LDAP_OPT_X_TLS_CIPHER_SUITE
 601 Sets/gets the allowed cipher suite.
 602 .BR invalue
 603 must be
 604 .BR "const char *" ;
 605 .BR outvalue
 606 must be
 607 .BR "char **" ,
 608 and its contents need to be freed by the caller using
 609 .BR ldap_memfree (3).
 610 .TP
 611 .B LDAP_OPT_X_TLS_CONNECT_ARG
 612 Sets/gets the connection callback argument.
 613 .BR invalue
 614 must be
 615 .BR "const void *" ;
 616 .BR outvalue
 617 must be
 618 .BR "void **" .
 619 .TP
 620 .B LDAP_OPT_X_TLS_CONNECT_CB
 621 Sets/gets the connection callback handle.
 622 .BR invalue
 623 must be
 624 .BR "const LDAP_TLS_CONNECT_CB *" ;
 625 .BR outvalue
 626 must be
 627 .BR "LDAP_TLS_CONNECT_CB **" .
 628 .TP
 629 .B LDAP_OPT_X_TLS_CRLCHECK
 630 Sets/gets the CRL evaluation strategy, one of
 631 .BR LDAP_OPT_X_TLS_CRL_NONE ,
 632 .BR LDAP_OPT_X_TLS_CRL_PEER ,
 633 or
 634 .BR LDAP_OPT_X_TLS_CRL_ALL .
 635 .BR invalue
 636 must be
 637 .BR "const int *" ;
 638 .BR outvalue
 639 must be
 640 .BR "int *" .
 641 Requires OpenSSL.
 642 .TP
 643 .B LDAP_OPT_X_TLS_CRLFILE
 644 Sets/gets the full-path of the CRL file.
 645 .BR invalue
 646 must be
 647 .BR "const char *" ;
 648 .BR outvalue
 649 must be
 650 .BR "char **" ,
 651 and its contents need to be freed by the caller using
 652 .BR ldap_memfree (3).
 653 This option is only valid for GnuTLS.
 654 .TP
 655 .B LDAP_OPT_X_TLS_CTX
 656 Sets/gets the TLS library context. New TLS sessions will inherit their
 657 default settings from this library context.
 658 .BR invalue
 659 must be
 660 .BR "const void *" ;
 661 .BR outvalue
 662 must be
 663 .BR "void **" .
 664 When using the OpenSSL library this is an SSL_CTX*. When using other
 665 crypto libraries this is a pointer to an OpenLDAP private structure.
 666 Applications generally should not use this option or attempt to
 667 manipulate this structure.
 668 .TP
 669 .B LDAP_OPT_X_TLS_DHFILE
 670 Gets/sets the full-path of the file containing the parameters
 671 for Diffie-Hellman ephemeral key exchange.
 672 .BR invalue
 673 must be
 674 .BR "const char *" ;
 675 .BR outvalue
 676 must be
 677 .BR "char **" ,
 678 and its contents need to be freed by the caller using
 679 .BR ldap_memfree (3).
 680 Ignored by GnuTLS.
 681 .TP
 682 .B LDAP_OPT_X_TLS_KEYFILE
 683 Sets/gets the full-path of the certificate key file.
 684 .BR invalue
 685 must be
 686 .BR "const char *" ;
 687 .BR outvalue
 688 must be
 689 .BR "char **" ,
 690 and its contents need to be freed by the caller using
 691 .BR ldap_memfree (3).
 692 .TP
 693 .B LDAP_OPT_X_TLS_NEWCTX
 694 Instructs the library to create a new TLS library context.
 695 .BR invalue
 696 must be
 697 .BR "const int *" .
 698 A non-zero value pointed to by
 699 .BR invalue
 700 tells the library to create a context for a server.
 701 .TP
 702 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
 703 Sets/gets the minimum protocol version.
 704 .BR invalue
 705 must be
 706 .BR "const int *" ;
 707 .BR outvalue
 708 must be
 709 .BR "int *" .
 710 .TP
 711 .B LDAP_OPT_X_TLS_RANDOM_FILE
 712 Sets/gets the random file when
 713 .B /dev/random
 714 and
 715 .B /dev/urandom
 716 are not available.
 717 .BR invalue
 718 must be
 719 .BR "const char *" ;
 720 .BR outvalue
 721 must be
 722 .BR "char **" ,
 723 and its contents need to be freed by the caller using
 724 .BR ldap_memfree (3).
 725 Ignored by GnuTLS older than version 2.2.
 726 .TP
 727 .B LDAP_OPT_X_TLS_REQUIRE_CERT
 728 Sets/gets the peer certificate checking strategy,
 729 one of
 730 .BR LDAP_OPT_X_TLS_NEVER ,
 731 .BR LDAP_OPT_X_TLS_HARD ,
 732 .BR LDAP_OPT_X_TLS_DEMAND ,
 733 .BR LDAP_OPT_X_TLS_ALLOW ,
 734 .BR LDAP_OPT_X_TLS_TRY .
 735 .TP
 736 .B LDAP_OPT_X_TLS_SSL_CTX
 737 Gets the TLS session context associated with this handle.
 738 .BR outvalue
 739 must be
 740 .BR "void **" .
 741 When using the OpenSSL library this is an SSL*. When using other
 742 crypto libraries this is a pointer to an OpenLDAP private structure.
 743 Applications generally should not use this option.
 744 .SH ERRORS
 745 On success, the functions return
 746 .BR LDAP_OPT_SUCCESS ,
 747 while they may return
 748 .B LDAP_OPT_ERROR
 749 to indicate a generic option handling error.
 750 Occasionally, more specific errors can be returned, like
 751 .B LDAP_NO_MEMORY
 752 to indicate a failure in memory allocation.
 753 .SH NOTES
 754 The LDAP libraries with the
 755 .B LDAP_OPT_REFERRALS
 756 option set to
 757 .B LDAP_OPT_ON
 758 (default value) automatically follow referrals using an anonymous bind.
 759 Application developers are encouraged to either implement consistent
 760 referral chasing features, or explicitly disable referral chasing
 761 by setting that option to
 762 .BR LDAP_OPT_OFF .
 763 .P
 764 The protocol version used by the library defaults to LDAPv2 (now historic),
 765 which corresponds to the
 766 .B LDAP_VERSION2
 767 macro.
 768 Application developers are encouraged to explicitly set
 769 .B LDAP_OPT_PROTOCOL_VERSION
 770 to LDAPv3, using the
 771 .B LDAP_VERSION3
 772 macro, or to allow users to select the protocol version.
 773 .SH SEE ALSO
 774 .BR ldap (3),
 775 .BR ldap_error (3),
 776 .B RFC 4422
 777 (http://www.rfc-editor.org),
 778 .SH ACKNOWLEDGEMENTS
 779 .so ../Project