IBM Security Directory Server, Version 6.3.1

LDAP_ERROR

Use the LDAP_ERROR API or LDAP routine to manage or handle protocol errors.

ldap_get_errno
ldap_get_lderrno
ldap_set_lderrno
ldap_perror (deprecated)
ldap_result2error (deprecated)
ldap_err2string
ldap_get_exterror

Synopsis

#include ldap.h


int ldap_get_errno(
         LDAP        *ld);

int ldap_get_lderrno (
         LDAP        *ld,
         char        **dn,
         char        **errmsg);

int ldap_set_lderrno (
         LDAP        *ld,
         int         errnum,
         char        *dn,
         char        *errmsg);

void ldap_perror(
        LDAP         *ld,
        const char   *s);

int ldap_result2error(
        LDAP         *ld,
        LDAPMessage  *res,
        int          freeit);
const char *ldap_err2string(
        int          error);

int ldap_get_exterror(
         LDAP        *ld);

Input parameters

ld: Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init() or ldap_open().
dn: Specifies a DN that identifies an existing entry, indicating how much of the name in the request that is recognized by the server. The DN is returned when an LDAP_NO_SUCH_OBJECT error is returned from the server. The matched DN string must be freed by calling ldap_memfree().
errmsg: Specifies the text of the error message, as returned from the server. The error message string must be freed by calling ldap_memfree().
s: Specifies the message prefix, which is prefixed to the string form of the error code held that is stored under the LDAP structure. The string form of the error is the same string that is returned by a call to ldap_err2string().
res: Specifies the result, as produced by ldap_result() or ldap_search_s(), to be converted to the error code with which it is associated.
freeit: Specifies whether the result, res, must be freed as a result of calling ldap_result2error(). If nonzero, the result, res, is freed by the call. If zero, res is not freed by the call.
errnum: Specifies the LDAP error code, as returned by ldap_parse_result() or another LDAP API call.

Usage

These routines provide interpretation of the various error codes that are returned by the LDAP protocol and LDAP library routines.

The ldap_get_errno() and ldap_get_lderrno() APIs obtain information for the most recent error that occurred for an LDAP operation. When an error occurs at the LDAP server, the server returns the following information back to the client:

The LDAP result code for the error that occurred.
A message that contains any additional information about the error from the server.

If the error occurred because an entry specified by a DN cannot be found, the server might also return the DN portion that identifies an existing entry.

Both APIs return the error result code of the server. Use ldap_get_lderrno() to obtain the message and matched DN.

The ldap_set_lderrno() API sets an error code and other information about an error in the specified LDAP structure. This function can be called to set error information that is retrieved by subsequent ldap_get_lderrno() calls.

The ldap_result2error() routine takes res, a result as produced by ldap_result() or ldap_search_s(), and returns the corresponding error code. Possible error codes follow. See the tables in the following section. If the freeit parameter is nonzero, it indicates that the res parameter must be freed by a call to ldap_msgfree() after the error code is extracted. The ld_errno field in ld is set and returned.

The returned value can be passed to ldap_err2string(), which returns a pointer to a character string which is a textual description of the LDAP error code. The character string must not be freed when use of the string is complete.

The ldap_perror() routine can be called to print an indication of the error on standard error.

The ldap_get_exterror() routine returns the current extended error code that is returned by an LDAP server or other library, such as Kerberos or SSL, for the LDAP session. For some error codes, it might be possible to further interpret the error condition. For example, for SSL errors the extended error code might indicate why an SSL handshake failed.

Errors

The possible values for an LDAP error code are shown in the following tables.

Table 1. Return codes and their description
Dec value	Value	Hex value	Brief description	Detailed description
00	`LDAP_SUCCESS`	00	Success	The request was successful.
00	`LDAP_OPERATIONS_ERROR`	01	Operations error	An operations error occurred.
02	`LDAP_PROTOCOL_ERROR`	02	Protocol error	A protocol violation was detected.
03	`LDAP_TIMELIMIT_EXCEEDED`	03	Time limit that exceeded	An LDAP time limit was exceeded.
04	`LDAP_SIZELIMIT_EXCEEDED`	04	Size limit that exceeded	An LDAP size limit was exceeded.
05	`LDAP_COMPARE_FALSE`	05	Compare false	A compare operation returned false.
06	`LDAP_COMPARE_TRUE`	06	Compare true	A compare operation returned true.
07	`LDAP_STRONG_AUTH_NOT_SUPPORTED`	07	Strong authentication that is not supported	The LDAP server does not support strong authentication.
08	`LDAP_STRONG_AUTH_REQUIRED`	08	Strong authentication that is required	Strong authentication is required for the operation.
09	`LDAP_PARTIAL_RESULTS`	09	Partial results and referral received	Partial results that are only returned.
10	`LDAP_REFERRAL`	0A	Referral returned	Referral returned.
11	`LDAP_ADMIN_LIMIT_EXCEEDED`	0B	Administration limit that exceeded	Administration limit that exceeded.
12	`LDAP_UNAVAILABLE_CRITICAL_EXTENSION`	0C	Critical extension that is not supported	Critical extension is not supported.
13	`LDAP_CONFIDENTIALITY_REQUIRED`	0D	Confidentiality is required	Confidentiality is required.
14	`LDAP_SASLBIND_IN_PROGRESS`	0E	SASL bind in progress	An SASL bind is in progress.
16	`LDAP_NO_SUCH_ATTRIBUTE`	10	No such attribute	The attribute type that is specified does not exist in the entry.
17	`LDAP_UNDEFINED_TYPE`	11	Undefined attribute type	The attribute type that is specified is not valid.
18	`LDAP_INAPPROPRIATE_MATCHING`	12	Inappropriate matching	Filter type that is not supported for the specified attribute.
19	`LDAP_CONSTRAINT_VIOLATION`	13	Constraint violation	An attribute value that is specified violates some constraint. For example, a postal address has too many lines, or a line that is too long.
20	`LDAP_TYPE_OR_VALUE_EXISTS`	14	Type or value exists	An attribute type or attribute value that is specified exists in the entry.
21	`LDAP_INVALID_SYNTAX`	15	Invalid syntax	An attribute value that is not valid was specified.
32	`LDAP_NO_SUCH_OBJECT`	20	No such object	The specified object does not exist in the directory.
33	`LDAP_ALIAS_PROBLEM`	21	Alias problem	An alias in the directory points to a nonexistent entry.
34	`LDAP_INVALID_DN_SYNTAX`	22	Invalid DN syntax	A DN that is syntactically not valid was specified.
35	`LDAP_IS_LEAF`	23	Object is a leaf	The object that is specified is a leaf.
36	`LDAP_ALIAS_DEREF_PROBLEM`	24	Alias dereferencing problem	A problem was encountered when you dereferenced an alias.
48	`LDAP_INAPPROPRIATE_AUTH`	30	Inappropriate authentication	Inappropriate authentication was specified. For example, `LDAP_AUTH_SIMPLE` was specified and the entry does not have a `userPassword` attribute.
49	`LDAP_INVALID_CREDENTIALS`	31	Invalid credentials	Invalid credentials were presented. For example, the wrong password.
50	`LDAP_INSUFFICIENT_ACCESS`	32	Insufficient access	The user has insufficient access to run the operation.
51	`LDAP_BUSY`	33	DSA is busy	The DSA is busy.
52	`LDAP_UNAVAILABLE`	34	DSA is unavailable	The DSA is unavailable.
53	`LDAP_UNWILLING_TO_PERFORM`	35	DSA cannot run	The DSA cannot run the operation.
54	`LDAP_LOOP_DETECT`	36	Loop detected	A loop was detected.
64	`LDAP_NAMING_VIOLATION`	40	Naming violation	A naming violation occurred.
65	`LDAP_OBJECT_CLASS_VIOLATION`	41	Object class violation	An object class violation occurred. For example, a "required" attribute was missing from the entry.
66	`LDAP_NOT_ALLOWED_ON_NONLEAF`	42	Operation that is not allowed on nonleaf	The operation is not allowed on a nonleaf object.
67	`LDAP_NOT_ALLOWED_ON_RDN`	43	Operation that is not allowed on RDN	The operation is not allowed on an RDN.
68	`LDAP_ALREADY_EXISTS`	44	Exists	The entry exists.
69	`LDAP_NO_OBJECT_CLASS_MODS`	45	Cannot modify object class	Object class modifications are not allowed.
70	`LDAP_RESULTS_TOO_LARGE`	46	Results too large	Results too large.
71	`LDAP_AFFECTS_MULTIPLE_DSAS`	47	Affects multiple DSAs	Affects multiple DSAs.
80	`LDAP_OTHER`	50	Unknown error	An unknown error occurred.
81	`LDAP_SERVER_DOWN`	51	Cannot contact LDAP server	The LDAP library cannot contact the LDAP server.
82	`LDAP_LOCAL_ERROR`	52	Local error	Some local error occurred. This error is usually a failed memory allocation.
83	`LDAP_ENCODING_ERROR`	53	Encoding error	An error was encountered encoding parameters to send to the LDAP server.
84	`LDAP_DECODING_ERROR`	54	Decoding error	An error was encountered decoding a result from the LDAP server.
85	`LDAP_TIMEOUT`	55	Timed out	A time limit was exceeded while you waited for a result.
86	`LDAP_AUTH_UNKNOWN`	56	Unknown authentication method	The authentication method that is specified on a bind operation is not known.
87	`LDAP_FILTER_ERROR`	57	Bad search filter	An invalid filter that is supplied to ldap_search. For example, unbalanced parentheses.
88	`LDAP_USER_CANCELLED`	58	User canceled operation	The user canceled the operation.
89	`LDAP_PARAM_ERROR`	59	Bad parameter to an LDAP routine	An LDAP routine that is called with a bad parameter. For example, a NULL ld pointer, and others.
90	`LDAP_NO_MEMORY`	5A	Out of memory	A memory allocation call, such as `malloc`, failed in an LDAP library routine.
91	`LDAP_CONNECT_ERROR`	5B	Connection error	Connection error.
92	`LDAP_NOT_SUPPORTED`	5C	Not supported	Not supported.
93	`LDAP_CONTROL_NOT_FOUND`	5D	Control not found	Control not found.
94	`LDAP_NO_RESULTS_RETURNED`	5E	No results that returned	No results that returned.
95	`LDAP_MORE_RESULTS_TO_RETURN`	5F	More results to return	More results to return.
96	`LDAP_URL_ERR_NOTLDAP`	60	URL does not begin with `ldap://`	The URL does not begin with `ldap://`.
97	`LDAP_URL_ERR_NODN`	61	URL has no DN (required)	The URL does not have a DN (required).
98	`LDAP_URL_ERR_BADSCOPE`	62	URL scope string is invalid	The URL scope string is not valid.
99	`LDAP_URL_ERR_MEM`	63	Cannot allocate memory space	Cannot allocate memory space.
100	`LDAP_CLIENT_LOOP`	64	Client loop	Client loop.
101	`LDAP_REFERRAL_LIMIT_EXCEEDED`	65	Referral limit that exceeded	Referral limit that exceeded.
112	`LDAP_SSL_ALREADY_INITIALIZED`	70	ldap_ssl_client_init successfully called previously in this process	The ldap_ssl_client_init was successfully called previously in this process.
113	`LDAP_SSL_INITIALIZE_FAILED`	71	Initialization call that failed	SSL Initialization call failed.
114	`LDAP_SSL_CLIENT_INIT_NOT_CALLED`	72	Must call ldap_ssl_client_init before you attempt to use SSL connection	Must call ldap_ssl_client_init before you attempt to use the SSL connection.
115	`LDAP_SSL_PARAM_ERROR`	73	Invalid SSL parameter previously specified	An SSL parameter that was not valid was previously specified.
116	`LDAP_SSL_HANDSHAKE_FAILED`	74	Failed to connect to SSL server	Failed to connect to SSL server.
117	`LDAP_SSL_GET_CIPHER_FAILED`	75	Not used	Deprecated
118	`LDAP_SSL_NOT_AVAILABLE`	76	SSL library cannot be located	Ensure that `GSKit` is installed.
128	`LDAP_NO_EXPLICIT_OWNER`	80	No explicit owner found	No explicit owner was found.
129	`LDAP_NO_LOCK`	81	Cannot obtain lock	Client library was not able to lock a required resource.

In addition, the following DNS-related error codes are defined in the ldap.h file:

Table 2. DNS-related return codes
Dec value	Value	Hex value	Detailed description
133	`LDAP_DNS_NO_SERVERS`	85	No LDAP servers found.
134	`LDAP_DNS_TRUNCATED`	86	Warning: truncated DNS results.
135	`LDAP_DNS_INVALID_DATA`	87	Invalid DNS Data.
136	`LDAP_DNS_RESOLVE_ERROR`	88	Cannot resolve system domain or name server.
137	`LDAP_DNS_CONF_FILE_ERROR`	89	DNS Configuration file error.

The following UTF8-related error codes are defined in the ldap.h file:

Table 3. UTF8-related return codes
Dec value	Value	Hex value	Detailed description
160	`LDAP_XLATE_E2BIG`	A0	Output buffer overflow.
161	`LDAP_XLATE_EINVAL`	A1	Input buffer that is truncated.
162	`LDAP_XLATE_EILSEQ`	A2	Unusable input character.
163	`LDAP_XLATE_NO_ENTRY`	A3	No code set point to map to.
176	`LDAP_REG_FILE_NOT_FOUND`	B0	NT Registry file not found.
177	`LDAP_REG_CANNOT_OPEN`	B1	NT Registry cannot open.
178	`LDAP_REG_ENTRY_NOT_FOUND`	B2	NT Registry entry not found.
192	`LDAP_CONF_FILE_NOT_OPENED`	C0	Plug-in configuration file not opened.
193	`LDAP_PLUGIN_NOT_LOADED`	C1	Plug-in library that is not loaded.
194	`LDAP_PLUGIN_FUNCTION_NOT_RESOLVED`	C2	Plug-in function that is not resolved.
195	`LDAP_PLUGIN_NOT_INITIALIZED`	C3	Plug-in library not initialized.
196	`LDAP_PLUGIN_COULD_NOT_BIND`	C4	Plug-in function cannot bind.
208	`LDAP_SASL_GSS_NO_SEC_CONTEXT`	D0	gss_init_sec_context failed.

LDAP_ERROR

Synopsis

Input parameters

Usage

Errors

See also