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