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_SESSION_REFCNT
 326 Returns the reference count associated with the LDAP handle passed in as
 327 .BR ld ;
 328 .BR outvalue
 329 must be a
 330 .BR "int *" .
 331 This is a read-only, handle-specific option.
 332 This option is OpenLDAP specific.
 333 .TP
 334 .B LDAP_OPT_SIZELIMIT
 335 Sets/gets the value that defines the maximum number of entries
 336 to be returned by a search operation.
 337 .BR invalue
 338 must be
 339 .BR "const int *" ,
 340 while
 341 .BR outvalue
 342 must be
 343 .BR "int *" ;
 344 They cannot be NULL.
 345 .TP
 346 .B LDAP_OPT_SOCKBUF
 347 Returns a pointer to the socket buffer of the LDAP handle passed in as
 348 .BR ld ;
 349 .BR outvalue
 350 must be a
 351 .BR "Sockbuf **" .
 352 This is a read-only, handle-specific option.
 353 This option is OpenLDAP specific.
 354 .TP
 355 .B LDAP_OPT_TIMELIMIT
 356 Sets/gets the value that defines the time limit after which
 357 a search operation should be terminated by the server.
 358 .BR invalue
 359 must be
 360 .BR "const int *" ,
 361 while
 362 .BR outvalue
 363 must be
 364 .BR "int *" ,
 365 and they cannot be NULL.
 366 .TP
 367 .B LDAP_OPT_TIMEOUT
 368 Sets/gets a timeout value for the synchronous API calls.
 369 .B outvalue
 370 must be a
 371 .BR "struct timeval **"
 372 (the caller has to free
 373 .BR *outvalue ) ,
 374 and
 375 .B invalue
 376 must be a
 377 .BR "struct timeval *" ,
 378 and they cannot be NULL. Using a struct with seconds set to \-1 results
 379 in an infinite timeout, which is the default.
 380 This option is OpenLDAP specific.
 381 .TP
 382 .B LDAP_OPT_URI
 383 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
 384 when trying to establish a connection.
 385 .BR outvalue
 386 must be a
 387 .BR "char **" ,
 388 and the caller is responsible of freeing the resulting string by calling
 389 .BR ldap_memfree (3),
 390 while
 391 .BR invalue
 392 must be a
 393 .BR "const char *" ;
 394 the library parses the string into a list of
 395 .BR LDAPURLDesc
 396 structures, so the invocation of
 397 .BR ldap_set_option (3)
 398 may fail if URL parsing fails.
 399 URIs may only contain the
 400 .BR schema ,
 401 the
 402 .BR host ,
 403 and the
 404 .BR port
 405 fields.
 406 This option is OpenLDAP specific.
 407 .SH SASL OPTIONS
 408 The SASL options are OpenLDAP specific.
 409 .TP
 410 .B LDAP_OPT_X_SASL_AUTHCID
 411 Gets the SASL authentication identity;
 412 .BR outvalue
 413 must be a
 414 .BR "char **" ,
 415 its content needs to be freed by the caller using
 416 .BR ldap_memfree (3).
 417 .TP
 418 .B LDAP_OPT_X_SASL_AUTHZID
 419 Gets the SASL authorization identity;
 420 .BR outvalue
 421 must be a
 422 .BR "char **" ,
 423 its content needs to be freed by the caller using
 424 .BR ldap_memfree (3).
 425 .TP
 426 .B LDAP_OPT_X_SASL_MAXBUFSIZE
 427 Gets/sets SASL maximum buffer size;
 428 .BR invalue
 429 must be
 430 .BR "const ber_len_t *" ,
 431 while
 432 .BR outvalue
 433 must be
 434 .BR "ber_len_t *" .
 435 See also
 436 .BR LDAP_OPT_X_SASL_SECPROPS .
 437 .TP
 438 .B LDAP_OPT_X_SASL_MECH
 439 Gets the SASL mechanism;
 440 .BR outvalue
 441 must be a
 442 .BR "char **" ,
 443 its content needs to be freed by the caller using
 444 .BR ldap_memfree (3).
 445 .TP
 446 .B LDAP_OPT_X_SASL_MECHLIST
 447 Gets the list of the available mechanisms,
 448 in form of a NULL-terminated array of strings;
 449 .BR outvalue
 450 must be
 451 .BR "char ***" .
 452 The caller must not free or otherwise muck with it.
 453 .TP
 454 .B LDAP_OPT_X_SASL_NOCANON
 455 Sets/gets the NOCANON flag.
 456 When unset, the hostname is canonicalized.
 457 .BR invalue
 458 must be
 459 .BR "const int *" ;
 460 its value should either be
 461 .BR LDAP_OPT_OFF
 462 or
 463 .BR LDAP_OPT_ON .
 464 .BR outvalue
 465 must be
 466 .BR "int *" .
 467 .TP
 468 .B LDAP_OPT_X_SASL_REALM
 469 Gets the SASL realm;
 470 .BR outvalue
 471 must be a
 472 .BR "char **" ,
 473 its content needs to be freed by the caller using
 474 .BR ldap_memfree (3).
 475 .TP
 476 .B LDAP_OPT_X_SASL_SECPROPS
 477 Sets the SASL secprops;
 478 .BR invalue
 479 must be a
 480 .BR "char *" ,
 481 containing a comma-separated list of properties.
 482 Legal values are:
 483 .BR none ,
 484 .BR nodict ,
 485 .BR noplain ,
 486 .BR noactive ,
 487 .BR passcred ,
 488 .BR forwardsec ,
 489 .BR noanonymous ,
 490 .BR minssf=<minssf> ,
 491 .BR maxssf=<maxssf> ,
 492 .BR maxbufsize=<maxbufsize> .
 493 .TP
 494 .B LDAP_OPT_X_SASL_SSF
 495 Gets the SASL SSF;
 496 .BR outvalue
 497 must be a
 498 .BR "ber_len_t *" .
 499 .TP
 500 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
 501 Sets the SASL SSF value related to an authentication
 502 performed using an EXTERNAL mechanism;
 503 .BR invalue
 504 must be a
 505 .BR "const ber_len_t *" .
 506 .TP
 507 .B LDAP_OPT_X_SASL_SSF_MAX
 508 Gets/sets SASL maximum SSF;
 509 .BR invalue
 510 must be
 511 .BR "const ber_len_t *" ,
 512 while
 513 .BR outvalue
 514 must be
 515 .BR "ber_len_t *" .
 516 See also
 517 .BR LDAP_OPT_X_SASL_SECPROPS .
 518 .TP
 519 .B LDAP_OPT_X_SASL_SSF_MIN
 520 Gets/sets SASL minimum SSF;
 521 .BR invalue
 522 must be
 523 .BR "const ber_len_t *" ,
 524 while
 525 .BR outvalue
 526 must be
 527 .BR "ber_len_t *" .
 528 See also
 529 .BR LDAP_OPT_X_SASL_SECPROPS .
 530 .TP
 531 .B LDAP_OPT_X_SASL_USERNAME
 532 Gets the SASL username;
 533 .BR outvalue
 534 must be a
 535 .BR "char **" .
 536 Its content needs to be freed by the caller using
 537 .BR ldap_memfree (3).
 538 .SH TCP OPTIONS
 539 The TCP options are OpenLDAP specific.
 540 Mainly intended for use with Linux, they may not be portable.
 541 .TP
 542 .B LDAP_OPT_X_KEEPALIVE_IDLE
 543 Sets/gets the number of seconds a connection needs to remain idle
 544 before TCP starts sending keepalive probes.
 545 .BR invalue
 546 must be
 547 .BR "const int *" ;
 548 .BR outvalue
 549 must be
 550 .BR "int *" .
 551 .TP
 552 .B LDAP_OPT_X_KEEPALIVE_PROBES
 553 Sets/gets the maximum number of keepalive probes TCP should send
 554 before dropping the connection.
 555 .BR invalue
 556 must be
 557 .BR "const int *" ;
 558 .BR outvalue
 559 must be
 560 .BR "int *" .
 561 .TP
 562 .B LDAP_OPT_X_KEEPALIVE_INTERVAL
 563 Sets/gets the interval in seconds between individual keepalive probes.
 564 .BR invalue
 565 must be
 566 .BR "const int *" ;
 567 .BR outvalue
 568 must be
 569 .BR "int *" .
 570 .SH TLS OPTIONS
 571 The TLS options are OpenLDAP specific.
 572 .\".TP
 573 .\".B LDAP_OPT_X_TLS
 574 .\"Sets/gets the TLS mode.
 575 .TP
 576 .B LDAP_OPT_X_TLS_CACERTDIR
 577 Sets/gets the path of the directory containing CA certificates.
 578 .BR invalue
 579 must be
 580 .BR "const char *" ;
 581 .BR outvalue
 582 must be
 583 .BR "char **" ,
 584 and its contents need to be freed by the caller using
 585 .BR ldap_memfree (3).
 586 .TP
 587 .B LDAP_OPT_X_TLS_CACERTFILE
 588 Sets/gets the full-path of the CA certificate file.
 589 .BR invalue
 590 must be
 591 .BR "const char *" ;
 592 .BR outvalue
 593 must be
 594 .BR "char **" ,
 595 and its contents need to be freed by the caller using
 596 .BR ldap_memfree (3).
 597 .TP
 598 .B LDAP_OPT_X_TLS_CERTFILE
 599 Sets/gets the full-path of the certificate file.
 600 .BR invalue
 601 must be
 602 .BR "const char *" ;
 603 .BR outvalue
 604 must be
 605 .BR "char **" ,
 606 and its contents need to be freed by the caller using
 607 .BR ldap_memfree (3).
 608 .TP
 609 .B LDAP_OPT_X_TLS_CIPHER_SUITE
 610 Sets/gets the allowed cipher suite.
 611 .BR invalue
 612 must be
 613 .BR "const char *" ;
 614 .BR outvalue
 615 must be
 616 .BR "char **" ,
 617 and its contents need to be freed by the caller using
 618 .BR ldap_memfree (3).
 619 .TP
 620 .B LDAP_OPT_X_TLS_CONNECT_ARG
 621 Sets/gets the connection callback argument.
 622 .BR invalue
 623 must be
 624 .BR "const void *" ;
 625 .BR outvalue
 626 must be
 627 .BR "void **" .
 628 .TP
 629 .B LDAP_OPT_X_TLS_CONNECT_CB
 630 Sets/gets the connection callback handle.
 631 .BR invalue
 632 must be
 633 .BR "const LDAP_TLS_CONNECT_CB *" ;
 634 .BR outvalue
 635 must be
 636 .BR "LDAP_TLS_CONNECT_CB **" .
 637 .TP
 638 .B LDAP_OPT_X_TLS_CRLCHECK
 639 Sets/gets the CRL evaluation strategy, one of
 640 .BR LDAP_OPT_X_TLS_CRL_NONE ,
 641 .BR LDAP_OPT_X_TLS_CRL_PEER ,
 642 or
 643 .BR LDAP_OPT_X_TLS_CRL_ALL .
 644 .BR invalue
 645 must be
 646 .BR "const int *" ;
 647 .BR outvalue
 648 must be
 649 .BR "int *" .
 650 Requires OpenSSL.
 651 .TP
 652 .B LDAP_OPT_X_TLS_CRLFILE
 653 Sets/gets the full-path of the CRL file.
 654 .BR invalue
 655 must be
 656 .BR "const char *" ;
 657 .BR outvalue
 658 must be
 659 .BR "char **" ,
 660 and its contents need to be freed by the caller using
 661 .BR ldap_memfree (3).
 662 This option is only valid for GnuTLS.
 663 .TP
 664 .B LDAP_OPT_X_TLS_CTX
 665 Sets/gets the TLS library context. New TLS sessions will inherit their
 666 default settings from this library context.
 667 .BR invalue
 668 must be
 669 .BR "const void *" ;
 670 .BR outvalue
 671 must be
 672 .BR "void **" .
 673 When using the OpenSSL library this is an SSL_CTX*. When using other
 674 crypto libraries this is a pointer to an OpenLDAP private structure.
 675 Applications generally should not use this option or attempt to
 676 manipulate this structure.
 677 .TP
 678 .B LDAP_OPT_X_TLS_DHFILE
 679 Gets/sets the full-path of the file containing the parameters
 680 for Diffie-Hellman ephemeral key exchange.
 681 .BR invalue
 682 must be
 683 .BR "const char *" ;
 684 .BR outvalue
 685 must be
 686 .BR "char **" ,
 687 and its contents need to be freed by the caller using
 688 .BR ldap_memfree (3).
 689 Ignored by GnuTLS and Mozilla NSS.
 690 .TP
 691 .B LDAP_OPT_X_TLS_KEYFILE
 692 Sets/gets the full-path of the certificate key file.
 693 .BR invalue
 694 must be
 695 .BR "const char *" ;
 696 .BR outvalue
 697 must be
 698 .BR "char **" ,
 699 and its contents need to be freed by the caller using
 700 .BR ldap_memfree (3).
 701 .TP
 702 .B LDAP_OPT_X_TLS_NEWCTX
 703 Instructs the library to create a new TLS library context.
 704 .BR invalue
 705 must be
 706 .BR "const int *" .
 707 A non-zero value pointed to by
 708 .BR invalue
 709 tells the library to create a context for a server.
 710 .TP
 711 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
 712 Sets/gets the minimum protocol version.
 713 .BR invalue
 714 must be
 715 .BR "const int *" ;
 716 .BR outvalue
 717 must be
 718 .BR "int *" .
 719 .TP
 720 .B LDAP_OPT_X_TLS_RANDOM_FILE
 721 Sets/gets the random file when
 722 .B /dev/random
 723 and
 724 .B /dev/urandom
 725 are not available.
 726 .BR invalue
 727 must be
 728 .BR "const char *" ;
 729 .BR outvalue
 730 must be
 731 .BR "char **" ,
 732 and its contents need to be freed by the caller using
 733 .BR ldap_memfree (3).
 734 Ignored by GnuTLS older than version 2.2.  Ignored by Mozilla NSS.
 735 .TP
 736 .B LDAP_OPT_X_TLS_REQUIRE_CERT
 737 Sets/gets the peer certificate checking strategy,
 738 one of
 739 .BR LDAP_OPT_X_TLS_NEVER ,
 740 .BR LDAP_OPT_X_TLS_HARD ,
 741 .BR LDAP_OPT_X_TLS_DEMAND ,
 742 .BR LDAP_OPT_X_TLS_ALLOW ,
 743 .BR LDAP_OPT_X_TLS_TRY .
 744 .TP
 745 .B LDAP_OPT_X_TLS_SSL_CTX
 746 Gets the TLS session context associated with this handle.
 747 .BR outvalue
 748 must be
 749 .BR "void **" .
 750 When using the OpenSSL library this is an SSL*. When using other
 751 crypto libraries this is a pointer to an OpenLDAP private structure.
 752 Applications generally should not use this option.
 753 .SH ERRORS
 754 On success, the functions return
 755 .BR LDAP_OPT_SUCCESS ,
 756 while they may return
 757 .B LDAP_OPT_ERROR
 758 to indicate a generic option handling error.
 759 Occasionally, more specific errors can be returned, like
 760 .B LDAP_NO_MEMORY
 761 to indicate a failure in memory allocation.
 762 .SH NOTES
 763 The LDAP libraries with the
 764 .B LDAP_OPT_REFERRALS
 765 option set to
 766 .B LDAP_OPT_ON
 767 (default value) automatically follow referrals using an anonymous bind.
 768 Application developers are encouraged to either implement consistent
 769 referral chasing features, or explicitly disable referral chasing
 770 by setting that option to
 771 .BR LDAP_OPT_OFF .
 772 .P
 773 The protocol version used by the library defaults to LDAPv2 (now historic),
 774 which corresponds to the
 775 .B LDAP_VERSION2
 776 macro.
 777 Application developers are encouraged to explicitly set
 778 .B LDAP_OPT_PROTOCOL_VERSION
 779 to LDAPv3, using the
 780 .B LDAP_VERSION3
 781 macro, or to allow users to select the protocol version.
 782 .SH SEE ALSO
 783 .BR ldap (3),
 784 .BR ldap_error (3),
 785 .B RFC 4422
 786 (http://www.rfc-editor.org),
 787 .SH ACKNOWLEDGEMENTS
 788 .so ../Project