| blob | 66808e19bb9cc1ba173762f710e9a56f4e87be3f |
1 '\" te
2 .\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved.
3 .\" Portions Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH LDAP_GET_OPTION 3LDAP "Jan 15, 2004"
8 .SH NAME
9 ldap_get_option, ldap_set_option \- get or set session preferences in the
10 \fBldap\fR structure.
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lldap\fR [ \fIlibrary\fR... ]
15 #include <lber.h>
16 #include <ldap.h>
18 \fBLDAP\fR \fBldap_set_option\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fIoption\fR, \fBvoid\fR \fI*optdata\fR[]);
19 .fi
21 .LP
22 .nf
23 \fBLDAP\fR \fBldap_get_option\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fIoption\fR, \fBvoid\fR \fIoptdata\fR[]);
24 .fi
26 .SH DESCRIPTION
27 .sp
28 .LP
29 These functions provide an \fBLDAP\fR structure with access to session
30 preferences. The \fBldap_get_option()\fR function gets session preferences from
31 the \fBLDAP\fR structure. The \fBldap_set_option()\fR function sets session
32 preferences in the \fBLDAP\fR structure.
33 .sp
34 .LP
35 The \fIld\fR parameter specifies the connection handle, a pointer to an
36 \fBLDAP\fR structure that contains information about the \fBLDAP\fR server
37 connection. The \fIoption\fR parameter specifies the name of the option to be
38 read or modified. The \fIoptdata\fR parameter serves as a pointer to the value
39 of the option that you set or get.
40 .SH PARAMETERS
41 .sp
42 .LP
43 The following values can be specified for the \fIoption\fR parameter:
44 .sp
45 .ne 2
46 .na
47 \fB\fBLDAP_OPT_API_INFO\fR\fR
48 .ad
49 .sp .6
50 .RS 4n
51 Retrieves basic information about the \fBLDAP\fR \fBAPI\fR implementation at
52 execution time. The data type for the \fIoptdata\fR parameter is
53 \fB(LDAPAPIInfo *)\fR. This option is READ-ONLY and cannot be set.
54 .RE
56 .sp
57 .ne 2
58 .na
59 \fB\fBLDAP_OPT_DEREF\fR\fR
60 .ad
61 .sp .6
62 .RS 4n
63 Determines how aliases are handled during a search. The data type for the
64 \fIoptdata\fR parameter is \fB(int *)\fR. The following values can be specified
65 for the \fIoptdata\fR parameter:
66 .sp
67 .ne 2
68 .na
69 \fB\fBLDAP_DEREF_NEVER\fR\fR
70 .ad
71 .RS 24n
72 Specifies that aliases are never dereferenced.
73 .RE
75 .sp
76 .ne 2
77 .na
78 \fB\fBLDAP_DEREF_SEARCHING\fR\fR
79 .ad
80 .RS 24n
81 Specifies that aliases are dereferenced when searching under the base object,
82 but not when finding the base object.
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fBLDAP_DEREF_FINDING\fR\fR
89 .ad
90 .RS 24n
91 Specifies that aliases are dereferenced when finding the base object, but not
92 when searching under the base object.
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fBLDAP_DEREF_ALWAYS\fR\fR
99 .ad
100 .RS 24n
101 Specifies that aliases are always dereferenced when finding the base object and
102 searching under the base object.
103 .RE
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fBLDAP_OPT_SIZELIMIT\fR\fR
111 .ad
112 .sp .6
113 .RS 4n
114 Specifies the maximum number of entries returned by the server in search
115 results. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR.
116 Setting the \fIoptdata\fR parameter to \fBLDAP_NO_LIMIT\fR removes any size
117 limit enforced by the client.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fBLDAP_OPT_TIMELIMIT\fR\fR
124 .ad
125 .sp .6
126 .RS 4n
127 Specifies the maximum number of seconds spent by the server when answering a
128 search request. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR.
129 Setting the \fIoptdata\fR parameter to \fBLDAP_NO_LIMIT\fR removes any time
130 limit enforced by the client.
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fB\fBLDAP_OPT_REFERRALS\fR\fR
137 .ad
138 .sp .6
139 .RS 4n
140 Determines whether the client should follow referrals. The data type for the
141 \fIoptdata\fR parameter is \fB(int *)\fR. The following values can be specified
142 for the \fIoptdata\fR parameter:
143 .sp
144 .ne 2
145 .na
146 \fB\fBLDAP_OPT_ON\fR\fR
147 .ad
148 .RS 16n
149 Specifies that the client should follow referrals.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fBLDAP_OPT_OFF\fR\fR
156 .ad
157 .RS 16n
158 Specifies that the client should not follow referrals.
159 .RE
161 By default, the client follows referrals.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBLDAP_OPT_RESTART\fR\fR
168 .ad
169 .sp .6
170 .RS 4n
171 Determines whether \fBLDAP\fR I/O operations are automatically restarted if
172 aborted prematurely. It can be set to one of the constants \fBLDAP_OPT_ON\fR or
173 \fBLDAP_OPT_OFF\fR.
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fBLDAP_OPT_PROTOCOL_VERSION\fR\fR
180 .ad
181 .sp .6
182 .RS 4n
183 Specifies the version of the protocol supported by the client. The data type
184 for the \fIoptdata\fR parameter is \fB(int *)\fR. The version
185 \fBLDAP_VERSION2\fR or \fBLDAP_VERSION3\fR can be specified. If no version is
186 set, the default version \fBLDAP_VERSION2\fR is set. To use \fBLDAP\fR v3
187 features, set the protocol version to \fBLDAP_VERSION3\fR.
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fBLDAP_OPT_SERVER_CONTROLS\fR\fR
194 .ad
195 .sp .6
196 .RS 4n
197 Specifies a pointer to an array of \fBLDAPControl\fR structures that represent
198 the \fBLDAP\fR v3 server controls sent by default with every request. The data
199 type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is
200 \fB(LDAPControl **)\fR. For \fBldap_get_option()\fR, the data type is
201 \fB(LDAPControl ***)\fR.
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fB\fBLDAP_OPT_CLIENT_CONTROLS\fR\fR
208 .ad
209 .sp .6
210 .RS 4n
211 Specifies a pointer to an array of \fBLDAPControl\fR structures that represent
212 the \fBLDAP\fR v3 client controls sent by default with every request. The data
213 type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is
214 \fB(LDAPControl **)\fR. For \fBldap_get_option()\fR, the data type is
215 \fB(LDAPControl ***)\fR.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fBLDAP_OPT_API_FEATURE_INFO\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 Retrieves version information at execution time about extended features of the
226 \fBLDAP\fR \fBAPI\fR. The data type for the \fIoptdata\fR parameter is
227 \fB(LDAPAPIFeatureInfo *)\fR. This option is READ-ONLY and cannot be set.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBLDAP_OPT_HOST_NAME\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 Sets the host name or a list of hosts for the primary \fBLDAP\fR server. The
238 data type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is
239 \fB(char *)\fR. For \fBldap_get_option()\fR, the data type is \fB(char **)\fR.
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fB\fBLDAP_OPT_ERROR_NUMBER\fR\fR
246 .ad
247 .sp .6
248 .RS 4n
249 Specifies the code of the most recent \fBLDAP\fR error that occurred for this
250 session. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBLDAP_OPT_ERROR_STRING\fR\fR
257 .ad
258 .sp .6
259 .RS 4n
260 Specifies the message returned with the most recent \fBLDAP\fR error that
261 occurred for this session. The data type for the \fIoptdata\fR parameter for
262 \fBldap_set_option()\fR is \fB(char *)\fR and for \fBldap_get_option()\fR is
263 \fB(char **)\fR.
264 .RE
266 .sp
267 .ne 2
268 .na
269 \fB\fBLDAP_OPT_MATCHED_DN\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 Specifies the matched \fBDN\fR value returned with the most recent \fBLDAP\fR
274 error that occurred for this session. The data type for the \fIoptdata\fR
275 parameter for \fBldap_set_option()\fR is \fB(char *)\fR and for
276 \fBldap_get_option()\fR is \fB(char **)\fR.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBLDAP_OPT_REBIND_ARG\fR\fR
283 .ad
284 .sp .6
285 .RS 4n
286 Sets the last argument passed to the routine specified by
287 \fBLDAP_OPT_REBIND_FN\fR. This option can also be set by calling the
288 \fBldap_set_rebind_proc()\fR function. The data type for the \fIoptdata\fR
289 parameter is \fB(void * )\fR.
290 .RE
292 .sp
293 .ne 2
294 .na
295 \fB\fBLDAP_OPT_REBIND_FN\fR\fR
296 .ad
297 .sp .6
298 .RS 4n
299 Sets the routine to be called to authenticate a connection with another LDAP
300 server. For example, the option is used to set the routine called during the
301 course of a referral. This option can also be by calling the
302 \fBldap_set_rebind_proc()\fR function. The data type for the \fIoptdata\fR
303 parameter is \fB(\fR\fBLDAP_REBINDPROC_CALLBACK\fR\fB *)\fR.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fB\fBLDAP_OPT_X_SASL_MECH\fR\fR
310 .ad
311 .sp .6
312 .RS 4n
313 Sets the default SASL mechanism to call \fBldap_interactive_bind_s()\fR. The
314 data type for the \fIoptdata\fR parameter is \fB(char * )\fR.
315 .RE
317 .sp
318 .ne 2
319 .na
320 \fB\fBLDAP_OPT_X_SASL_REALM\fR\fR
321 .ad
322 .sp .6
323 .RS 4n
324 Sets the default \fBSASL_REALM\fR. The default \fBSASL_REALM\fR should be used
325 during a SASL challenge in response to a \fBSASL_CB_GETREALM\fR request when
326 using the \fBldap_interactive_bind_s()\fR function. The data type for the
327 \fIoptdata\fR parameter is \fB(char * )\fR.
328 .RE
330 .sp
331 .ne 2
332 .na
333 \fB\fBLDAP_OPT_X_SASL_AUTHCID\fR\fR
334 .ad
335 .sp .6
336 .RS 4n
337 Sets the default \fBSASL_AUTHNAME\fR used during a SASL challenge in response
338 to a \fBSASL_CB_AUTHNAME\fR request when using the
339 \fBldap_interactive_bind_s()\fR function. The data type for the \fIoptdata\fR
340 parameter is \fB(char * )\fR.
341 .RE
343 .sp
344 .ne 2
345 .na
346 \fB\fBLDAP_OPT_X_SASL_AUTHZID\fR\fR
347 .ad
348 .sp .6
349 .RS 4n
350 Sets the default \fBSASL_USER\fR that should be used during a SASL challenge in
351 response to a \fBSASL_CB_USER\fR request when using the
352 \fBldap_interactive_bind_s\fR function. The data type for the \fIoptdata\fR
353 parameter is \fB(char * )\fR.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fBLDAP_OPT_X_SASL_SSF\fR\fR
360 .ad
361 .sp .6
362 .RS 4n
363 A read-only option used exclusively with the \fBldap_get_option()\fR function.
364 The \fBldap_get_option()\fR function performs a \fBsasl_getprop()\fR operation
365 that gets the \fBSASL_SSF\fR value for the current connection. The data type
366 for the \fIoptdata\fR parameter is \fB(sasl_ssf_t * )\fR.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBLDAP_OPT_X_SASL_SSF_EXTERNAL\fR\fR
373 .ad
374 .sp .6
375 .RS 4n
376 A write-only option used exclusively with the \fBldap_set_option()\fR function.
377 The \fBldap_set_option()\fR function performs a \fBsasl_setprop()\fR operation
378 to set the \fBSASL_SSF_EXTERNAL\fR value for the current connection. The data
379 type for the \fIoptdata\fR parameter is \fB(sasl_ssf_t * )\fR.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fB\fBLDAP_OPT_X_SASL_SECPROPS\fR\fR
386 .ad
387 .sp .6
388 .RS 4n
389 A write-only option used exclusively with the \fBldap_set_option()\fR. This
390 function performs a \fBsasl_setprop\fR(3SASL) operation for the
391 \fBSASL_SEC_PROPS\fR value for the current connection during an
392 \fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
393 parameter is \fB(char * )\fR, a comma delimited string containing text values
394 for any of the \fBSASL_SEC_PROPS\fR that should be set. The text values are:
395 .sp
396 .ne 2
397 .na
398 \fB\fBnoanonymous\fR\fR
399 .ad
400 .RS 16n
401 Sets the \fBSASL_SEC_NOANONYMOUS\fR flag
402 .RE
404 .sp
405 .ne 2
406 .na
407 \fB\fBnodict\fR\fR
408 .ad
409 .RS 16n
410 Sets the \fBSASL_SEC_NODICTIONARY\fR flag
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBnoplain\fR\fR
417 .ad
418 .RS 16n
419 Sets the \fBSASL_SEC_NOPLAINTEXT\fR flag
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fBforwardsec\fR\fR
426 .ad
427 .RS 16n
428 Sets the \fBSASL_SEC_FORWARD_SECRECY\fR flag
429 .RE
431 .sp
432 .ne 2
433 .na
434 \fB\fBpasscred\fR\fR
435 .ad
436 .RS 16n
437 Sets the \fBSASL_SEC_PASS_CREDENTIALS\fR flag
438 .RE
440 .sp
441 .ne 2
442 .na
443 \fB\fBminssf=N\fR\fR
444 .ad
445 .RS 16n
446 Sets \fBminssf\fR to the integer value \fBN\fR
447 .RE
449 .sp
450 .ne 2
451 .na
452 \fB\fBmaxssf=N\fR\fR
453 .ad
454 .RS 16n
455 Sets \fBmaxssf\fR to the integer value \fBN\fR
456 .RE
458 .sp
459 .ne 2
460 .na
461 \fB\fBmaxbufsize=N\fR\fR
462 .ad
463 .RS 16n
464 Sets \fBmaxbufsize\fR to the integer value \fBN\fR
465 .RE
467 .RE
469 .sp
470 .ne 2
471 .na
472 \fB\fBLDAP_OPT_X_SASL_SSF_MIN\fR\fR
473 .ad
474 .sp .6
475 .RS 4n
476 Sets the default \fBSSF_MIN\fR value used during a
477 \fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
478 parameter is \fB(char * )\fR numeric string.
479 .RE
481 .sp
482 .ne 2
483 .na
484 \fB\fBLDAP_OPT_X_SASL_SSF_MAX\fR\fR
485 .ad
486 .sp .6
487 .RS 4n
488 Sets the default \fBSSF_MAX\fR value used during a
489 \fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
490 parameter is \fB(char * )\fR numeric string.
491 .RE
493 .sp
494 .ne 2
495 .na
496 \fB\fBLDAP_OPT_X_SASL_MAXBUFSIZE\fR\fR
497 .ad
498 .sp .6
499 .RS 4n
500 Sets the default \fBSSF_MAXBUFSIZE\fR value used during a
501 \fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
502 parameter is \fB(char * )\fR numeric string.
503 .RE
505 .SH RETURN VALUES
506 .sp
507 .LP
508 The \fBldap_set_option()\fR and \fBldap_get_option()\fR functions return:
509 .sp
510 .ne 2
511 .na
512 \fB\fBLDAP_SUCCESS\fR\fR
513 .ad
514 .RS 16n
515 If successful
516 .RE
518 .sp
519 .ne 2
520 .na
521 \fB\fB-1\fR\fR
522 .ad
523 .RS 16n
524 If unsuccessful
525 .RE
527 .SH ATTRIBUTES
528 .sp
529 .LP
530 See \fBattributes\fR(5) for descriptions of the following attributes:
531 .sp
533 .sp
534 .TS
535 box;
536 c | c
537 l | l .
538 ATTRIBUTE TYPE ATTRIBUTE VALUE
539 _
540 Interface Stability Evolving
541 _
542 MT-Level Safe
543 .TE
545 .SH SEE ALSO
546 .sp
547 .LP
548 \fBldap_init\fR(3LDAP), \fBsasl_setprop\fR(3SASL), \fBattributes\fR(5)
549 .SH NOTES
550 .sp
551 .LP
552 There are other elements in the \fBLDAP\fR structure that should not be
553 changed. No assumptions should be made about the order of elements in the
554 \fBLDAP\fR structure.