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