LDAP_ERROR

Edit online

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.

See also

ldap_memfree, ldap_parse routines