| blob | 42720765e20503370ad69feaebbe79b9168a665b |
1 '\" te
2 .\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved.
3 .\" Portions Copyright (C) 2002, 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_ERROR 3LDAP "Nov 11, 2008"
8 .SH NAME
9 ldap_error, ldap_err2string, ldap_perror, ldap_result2error \- LDAP protocol
10 error handling functions
11 .SH SYNOPSIS
12 .LP
13 .nf
14 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
15 #include <lber.h>
16 #include <ldap.h>
18 \fBchar *\fR\fBldap_err2string\fR(\fBint\fR \fIerr\fR);
19 .fi
21 .LP
22 .nf
23 \fBvoid\fR \fBldap_perror\fR(\fBLDAP *\fR\fIld\fR, \fBconst char *\fR\fIs\fR);
24 .fi
26 .LP
27 .nf
28 \fBint\fR \fBldap_result2error\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIres\fR, \fBint\fR \fIfreeit\fR);
29 .fi
31 .SH DESCRIPTION
32 .sp
33 .LP
34 These functions interpret the error codes that are returned by the LDAP API
35 routines. The \fBldap_perror()\fR and \fBldap_result2error()\fR functions are
36 deprecated for all new development. Use \fBldap_err2string()\fR instead.
37 .sp
38 .LP
39 You can also use \fBldap_parse_sasl_bind_result\fR(3LDAP),
40 \fBldap_parse_extended_result\fR(3LDAP), and \fBldap_parse_result\fR(3LDAP) to
41 provide error handling and interpret error codes returned by LDAP API
42 functions.
43 .sp
44 .LP
45 The \fBldap_err2string()\fR function takes \fIerr\fR, a numeric LDAP error
46 code, returned either by \fBldap_parse_result\fR(3LDAP) or another LDAP API
47 call. It returns an informative, null-terminated, character string that
48 describes the error.
49 .sp
50 .LP
51 The \fBldap_result2error()\fR function takes \fIres\fR, a result produced by
52 \fBldap_result\fR(3LDAP) or other synchronous LDAP calls, and returns the
53 corresponding error code. If the \fIfreeit\fR parameter is non-zero, it
54 indicates that the \fIres\fR parameter should be freed by a call to
55 \fBldap_result\fR(3LDAP) after the error code has been extracted.
56 .sp
57 .LP
58 Similar to the way \fBperror\fR(3C) works, the \fBldap_perror()\fR function can
59 be called to print an indication of the error to standard error.
60 .SH ERRORS
61 .sp
62 .LP
63 The possible values for an LDAP error code are:
64 .sp
65 .ne 2
66 .na
67 \fB\fBLDAP_SUCCESS\fR\fR
68 .ad
69 .sp .6
70 .RS 4n
71 The request was successful.
72 .RE
74 .sp
75 .ne 2
76 .na
77 \fB\fBLDAP_OPERATIONS_ERROR\fR\fR
78 .ad
79 .sp .6
80 .RS 4n
81 An operations error occurred.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fBLDAP_PROTOCOL_ERROR\fR\fR
88 .ad
89 .sp .6
90 .RS 4n
91 A protocol violation was detected.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fBLDAP_TIMELIMIT_EXCEEDED\fR\fR
98 .ad
99 .sp .6
100 .RS 4n
101 An LDAP time limit was exceeded.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fBLDAP_SIZELIMIT_EXCEEDED\fR\fR
108 .ad
109 .sp .6
110 .RS 4n
111 An LDAP size limit was exceeded.
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB\fBLDAP_COMPARE_FALSE\fR\fR
118 .ad
119 .sp .6
120 .RS 4n
121 A compare operation returned false.
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBLDAP_COMPARE_TRUE\fR\fR
128 .ad
129 .sp .6
130 .RS 4n
131 A compare operation returned true.
132 .RE
134 .sp
135 .ne 2
136 .na
137 \fB\fBLDAP_STRONG_AUTH_NOT_SUPPORTED\fR\fR
138 .ad
139 .sp .6
140 .RS 4n
141 The LDAP server does not support strong authentication.
142 .RE
144 .sp
145 .ne 2
146 .na
147 \fB\fBLDAP_STRONG_AUTH_REQUIRED\fR\fR
148 .ad
149 .sp .6
150 .RS 4n
151 Strong authentication is required for the operation.
152 .RE
154 .sp
155 .ne 2
156 .na
157 \fB\fBLDAP_PARTIAL_RESULTS\fR\fR
158 .ad
159 .sp .6
160 .RS 4n
161 Only partial results are returned.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBLDAP_NO_SUCH_ATTRIBUTE\fR\fR
168 .ad
169 .sp .6
170 .RS 4n
171 The attribute type specified does not exist in the entry.
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBLDAP_UNDEFINED_TYPE\fR\fR
178 .ad
179 .sp .6
180 .RS 4n
181 The attribute type specified is invalid.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBLDAP_INAPPROPRIATE_MATCHING\fR\fR
188 .ad
189 .sp .6
190 .RS 4n
191 The filter type is not supported for the specified attribute.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBLDAP_CONSTRAINT_VIOLATION\fR\fR
198 .ad
199 .sp .6
200 .RS 4n
201 An attribute value specified violates some constraint. For example, a
202 \fBpostalAddress\fR has too many lines, or a line that is too long.
203 .RE
205 .sp
206 .ne 2
207 .na
208 \fB\fBLDAP_TYPE_OR_VALUE_EXISTS\fR\fR
209 .ad
210 .sp .6
211 .RS 4n
212 An attribute type or attribute value specified already exists in the entry.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fBLDAP_INVALID_SYNTAX\fR\fR
219 .ad
220 .sp .6
221 .RS 4n
222 An invalid attribute value was specified.
223 .RE
225 .sp
226 .ne 2
227 .na
228 \fB\fBLDAP_NO_SUCH_OBJECT\fR\fR
229 .ad
230 .sp .6
231 .RS 4n
232 The specified object does not exist in the directory.
233 .RE
235 .sp
236 .ne 2
237 .na
238 \fB\fBLDAP_ALIAS_PROBLEM\fR\fR
239 .ad
240 .sp .6
241 .RS 4n
242 An alias in the directory points to a nonexistent entry.
243 .RE
245 .sp
246 .ne 2
247 .na
248 \fB\fBLDAP_INVALID_DN_SYNTAX\fR\fR
249 .ad
250 .sp .6
251 .RS 4n
252 A syntactically invalid DN was specified.
253 .RE
255 .sp
256 .ne 2
257 .na
258 \fB\fBLDAP_IS_LEAF\fR\fR
259 .ad
260 .sp .6
261 .RS 4n
262 The object specified is a leaf.
263 .RE
265 .sp
266 .ne 2
267 .na
268 \fB\fBLDAP_ALIAS_DEREF_PROBLEM\fR\fR
269 .ad
270 .sp .6
271 .RS 4n
272 A problem was encountered when dereferencing an alias.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fBLDAP_INAPPROPRIATE_AUTH\fR\fR
279 .ad
280 .sp .6
281 .RS 4n
282 Inappropriate authentication was specified. For example,
283 \fBLDAP_AUTH_SIMPLE\fR was specified and the entry does not have a
284 \fBuserPassword\fR attribute.
285 .RE
287 .sp
288 .ne 2
289 .na
290 \fB\fBLDAP_INVALID_CREDENTIALS\fR\fR
291 .ad
292 .sp .6
293 .RS 4n
294 Invalid credentials were presented, for example, the wrong password.
295 .RE
297 .sp
298 .ne 2
299 .na
300 \fB\fBLDAP_INSUFFICIENT_ACCESS\fR\fR
301 .ad
302 .sp .6
303 .RS 4n
304 The user has insufficient access to perform the operation.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fBLDAP_BUSY\fR\fR
311 .ad
312 .sp .6
313 .RS 4n
314 The DSA is busy.
315 .RE
317 .sp
318 .ne 2
319 .na
320 \fB\fBLDAP_UNAVAILABLE\fR\fR
321 .ad
322 .sp .6
323 .RS 4n
324 The DSA is unavailable.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fB\fBLDAP_UNWILLING_TO_PERFORM\fR\fR
331 .ad
332 .sp .6
333 .RS 4n
334 The DSA is unwilling to perform the operation.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fBLDAP_LOOP_DETECT\fR\fR
341 .ad
342 .sp .6
343 .RS 4n
344 A loop was detected.
345 .RE
347 .sp
348 .ne 2
349 .na
350 \fB\fBLDAP_NAMING_VIOLATION\fR\fR
351 .ad
352 .sp .6
353 .RS 4n
354 A naming violation occurred.
355 .RE
357 .sp
358 .ne 2
359 .na
360 \fB\fBLDAP_OBJECT_CLASS_VIOLATION\fR\fR
361 .ad
362 .sp .6
363 .RS 4n
364 An object class violation occurred. For example, a \fBmust\fR attribute was
365 missing from the entry.
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBLDAP_NOT_ALLOWED_ON_NONLEAF\fR\fR
372 .ad
373 .sp .6
374 .RS 4n
375 The operation is not allowed on a nonleaf object.
376 .RE
378 .sp
379 .ne 2
380 .na
381 \fB\fBLDAP_NOT_ALLOWED_ON_RDN\fR\fR
382 .ad
383 .sp .6
384 .RS 4n
385 The operation is not allowed on an RDN.
386 .RE
388 .sp
389 .ne 2
390 .na
391 \fB\fBLDAP_ALREADY_EXISTS\fR\fR
392 .ad
393 .sp .6
394 .RS 4n
395 The entry already exists.
396 .RE
398 .sp
399 .ne 2
400 .na
401 \fB\fBLDAP_NO_OBJECT_CLASS_MODS\fR\fR
402 .ad
403 .sp .6
404 .RS 4n
405 Object class modifications are not allowed.
406 .RE
408 .sp
409 .ne 2
410 .na
411 \fB\fBLDAP_OTHER\fR\fR
412 .ad
413 .sp .6
414 .RS 4n
415 An unknown error occurred.
416 .RE
418 .sp
419 .ne 2
420 .na
421 \fB\fBLDAP_SERVER_DOWN\fR\fR
422 .ad
423 .sp .6
424 .RS 4n
425 The LDAP library cannot contact the LDAP server.
426 .RE
428 .sp
429 .ne 2
430 .na
431 \fB\fBLDAP_LOCAL_ERROR\fR\fR
432 .ad
433 .sp .6
434 .RS 4n
435 Some local error occurred. This is usually the result of a failed
436 \fBmalloc\fR(3C) call or a failure to \fBfflush\fR(3C) the \fBstdio\fR stream
437 to files, even when the LDAP requests were processed successfully by the remote
438 server.
439 .RE
441 .sp
442 .ne 2
443 .na
444 \fB\fBLDAP_ENCODING_ERROR\fR\fR
445 .ad
446 .sp .6
447 .RS 4n
448 An error was encountered encoding parameters to send to the LDAP server.
449 .RE
451 .sp
452 .ne 2
453 .na
454 \fB\fBLDAP_DECODING_ERROR\fR\fR
455 .ad
456 .sp .6
457 .RS 4n
458 An error was encountered decoding a result from the LDAP server.
459 .RE
461 .sp
462 .ne 2
463 .na
464 \fB\fBLDAP_TIMEOUT\fR\fR
465 .ad
466 .sp .6
467 .RS 4n
468 A time limit was exceeded while waiting for a result.
469 .RE
471 .sp
472 .ne 2
473 .na
474 \fB\fBLDAP_AUTH_UNKNOWN\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 The authentication method specified to \fBldap_bind\fR(3LDAP) is not known.
479 .RE
481 .sp
482 .ne 2
483 .na
484 \fB\fBLDAP_FILTER_ERROR\fR\fR
485 .ad
486 .sp .6
487 .RS 4n
488 An invalid filter was supplied to \fBldap_search\fR(3LDAP), for example,
489 unbalanced parentheses.
490 .RE
492 .sp
493 .ne 2
494 .na
495 \fB\fBLDAP_PARAM_ERROR\fR\fR
496 .ad
497 .sp .6
498 .RS 4n
499 An LDAP function was called with a bad parameter, for example, a \fINULL\fR
500 \fIld\fR pointer, and the like.
501 .RE
503 .sp
504 .ne 2
505 .na
506 \fB\fBLDAP_NO_MEMORY\fR\fR
507 .ad
508 .sp .6
509 .RS 4n
510 A memory allocation call failed in an LDAP library function, for example,
511 \fBmalloc\fR(3C).
512 .RE
514 .sp
515 .ne 2
516 .na
517 \fB\fBLDAP_CONNECT_ERROR\fR\fR
518 .ad
519 .sp .6
520 .RS 4n
521 The LDAP client has either lost its connetion to an LDAP server or it cannot
522 establish a connection.
523 .RE
525 .sp
526 .ne 2
527 .na
528 \fB\fBLDAP_NOT_SUPPORTED\fR\fR
529 .ad
530 .sp .6
531 .RS 4n
532 The requested functionality is not supported., for example, when an LDAPv2
533 client requests some LDAPv3 functionality.
534 .RE
536 .sp
537 .ne 2
538 .na
539 \fB\fBLDAP_CONTROL_NOT_FOUND\fR\fR
540 .ad
541 .sp .6
542 .RS 4n
543 An LDAP client requested a control not found in the list of supported controls
544 sent by the server.
545 .RE
547 .sp
548 .ne 2
549 .na
550 \fB\fBLDAP_NO_RESULTS_RETURNED\fR\fR
551 .ad
552 .sp .6
553 .RS 4n
554 The LDAP server sent no results.
555 .RE
557 .sp
558 .ne 2
559 .na
560 \fB\fBLDAP_MORE_RESULTS_TO_RETURN\fR\fR
561 .ad
562 .sp .6
563 .RS 4n
564 More results are chained in the message chain.
565 .RE
567 .sp
568 .ne 2
569 .na
570 \fB\fBLDAP_CLIENT_LOOP\fR\fR
571 .ad
572 .sp .6
573 .RS 4n
574 A loop has been detected, for example, when following referrals.
575 .RE
577 .sp
578 .ne 2
579 .na
580 \fB\fBLDAP_REFERRAL_LIMIT_EXCEEDED\fR\fR
581 .ad
582 .sp .6
583 .RS 4n
584 The referral exceeds the hop limit. The hop limit determines the number of
585 servers that the client can hop through to retrieve data.
586 .RE
588 .SH ATTRIBUTES
589 .sp
590 .LP
591 See \fBattributes\fR(5) for a description of the following attributes:
592 .sp
594 .sp
595 .TS
596 box;
597 c | c
598 l | l .
599 ATTRIBUTE TYPE ATTRIBUTE VALUE
600 _
601 Interface Stability Committed
602 .TE
604 .SH SEE ALSO
605 .sp
606 .LP
607 \fBfflush\fR(3C), \fBldap\fR(3LDAP), \fBldap_bind\fR(3LDAP),
608 \fBldap_result\fR(3LDAP), \fBldap_parse_extended_result\fR(3LDAP),
609 \fBldap_parse_result\fR(3LDAP), \fBldap_parse_sasl_bind_result\fR(3LDAP),
610 \fBldap_search\fR(3LDAP), \fBmalloc\fR(3C), \fBperror\fR(3C) ,
611 \fBattributes\fR(5)