1Net::LDAP::Util(3) User Contributed Perl Documentation Net::LDAP::Util(3)
2
6 Net::LDAP::Util - Utility functions
7
9 use Net::LDAP::Util qw(ldap_error_text
10 ldap_error_name
11 ldap_error_desc
12 );
13 $mesg = $ldap->search( .... );
15 die "Error ",ldap_error_name($mesg) if $mesg->code;
17
19 Net::LDAP::Util is a collection of utility functions for use with the
20 Net::LDAP modules.
21
23 ldap_error_name ( ERR )
24 Returns the name corresponding with ERR. ERR can either be an LDAP
25 error number, or a "Net::LDAP::Message" object containing an error
26 code. If the error is not known the a string in the form "LDAP
27 error code %d(0x%02X)" is returned.
28 ldap_error_text ( ERR )
30 Returns the text from the POD description for the given error. ERR
31 can either be an LDAP error code, or a "Net::LDAP::Message" object
32 containing an LDAP error code. If the error code given is unknown
33 then "undef" is returned.
34 ldap_error_desc ( ERR )
36 Returns a short text description of the error. ERR can either be an
37 LDAP error code or a "Net::LDAP::Message" object containing an LDAP
38 error code.
39 canonical_dn ( DN [ , OPTIONS ] )
41 Returns the given DN in a canonical form. Returns undef if DN is
42 not a valid Distinguished Name. (Note: The empty string "" is a
43 valid DN.) DN can either be a string or reference to an array of
44 hashes as returned by ldap_explode_dn, which is useful when
45 constructing a DN.
46 It performs the following operations on the given DN:
48 • Removes the leading 'OID.' characters if the type is an OID
50 instead of a name.
51 • Escapes all RFC 4514 special characters (",", "+", """, "\",
53 "<", ">", ";", "#", "=", " "), slashes ("/"), and any other
54 character where the ASCII code is < 32 as \hexpair.
55 • Converts all leading and trailing spaces in values to be \20.
57 • If an RDN contains multiple parts, the parts are re-ordered so
59 that the attribute type names are in alphabetical order.
60 OPTIONS is a list of name/value pairs, valid options are:
62 casefold
64 Controls case folding of attribute type names. Attribute values
65 are not affected by this option. The default is to uppercase.
66 Valid values are:
67 lower
69 Lowercase attribute type names.
70 upper
72 Uppercase attribute type names. This is the default.
73 none
75 Do not change attribute type names.
76 mbcescape
78 If TRUE, characters that are encoded as a multi-octet UTF-8
79 sequence will be escaped as \(hexpair){2,*}.
80 reverse
82 If TRUE, the RDN sequence is reversed.
83 separator
85 Separator to use between RDNs. Defaults to comma (',').
86 ldap_explode_dn ( DN [ , OPTIONS ] )
88 Explodes the given DN into an array of hashes and returns a
89 reference to this array. Returns undef if DN is not a valid
90 Distinguished Name.
91 A Distinguished Name is a sequence of Relative Distinguished Names
93 (RDNs), which themselves are sets of Attributes. For each RDN a
94 hash is constructed with the attribute type names as keys and the
95 attribute values as corresponding values. These hashes are then
96 stored in an array in the order in which they appear in the DN.
97 For example, the DN 'OU=Sales+CN=J. Smith,DC=example,DC=net' is
99 exploded to:
100 [
101 {
102 'OU' => 'Sales',
103 'CN' => 'J. Smith'
104 },
105 {
106 'DC' => 'example'
107 },
108 {
109 'DC' => 'net'
110 }
111 ]
112 (RFC4514 string) DNs might also contain values, which are the bytes
114 of the BER encoding of the X.500 AttributeValue rather than some
115 LDAP string syntax. These values are hex-encoded and prefixed with
116 a #. To distinguish such BER values, ldap_explode_dn uses
117 references to the actual values, e.g.
118 '1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com' is exploded to:
119 [
120 {
121 '1.3.6.1.4.1.1466.0' => "\004\002Hi"
122 },
123 {
124 'DC' => 'example'
125 },
126 {
127 'DC' => 'com'
128 }
129 ];
130 It also performs the following operations on the given DN:
132 • Unescape "\" followed by ",", "+", """, "\", "<", ">", ";",
134 "#", "=", " ", or a hexpair and strings beginning with "#".
135 • Removes the leading 'OID.' characters if the type is an OID
137 instead of a name.
138 OPTIONS is a list of name/value pairs, valid options are:
140 casefold
142 Controls case folding of attribute types names. Attribute
143 values are not affected by this option. The default is to
144 uppercase. Valid values are:
145 lower
147 Lowercase attribute types names.
148 upper
150 Uppercase attribute type names. This is the default.
151 none
153 Do not change attribute type names.
154 reverse
156 If TRUE, the RDN sequence is reversed.
157 escape_filter_value ( VALUES )
159 Escapes the given VALUES according to RFC 4515 so that they can be
160 safely used in LDAP filters.
161 Any control characters with an ASCII code < 32 as well as the
163 characters with special meaning in LDAP filters "*", "(", ")", and
164 "\" the backslash are converted into the representation of a
165 backslash followed by two hex digits representing the hexadecimal
166 value of the character.
167 Returns the converted list in list mode and the first element in
169 scalar mode.
170 unescape_filter_value ( VALUES )
172 Undoes the conversion done by escape_filter_value().
173 Converts any sequences of a backslash followed by two hex digits
175 into the corresponding character.
176 Returns the converted list in list mode and the first element in
178 scalar mode.
179 escape_dn_value ( VALUES )
181 Escapes the given VALUES according to RFC 4514 so that they can be
182 safely used in LDAP DNs.
183 The characters ",", "+", """, "\", "<", ">", ";", "#", "=" with a
185 special meaning in section 2.4 of RFC 4514 are preceded by a
186 backslash. Control characters with an ASCII code < 32 are
187 represented as \hexpair. Finally all leading and trailing spaces
188 are converted to sequences of \20.
189 Returns the converted list in list mode and the first element in
191 scalar mode.
192 unescape_dn_value ( VALUES )
194 Undoes the conversion done by escape_dn_value().
195 Any escape sequence starting with a backslash - hexpair or special
197 character - will be transformed back to the corresponding
198 character.
199 Returns the converted list in list mode and the first element in
201 scalar mode.
202 ldap_url_parse ( LDAP-URL [, OPTIONS ] )
204 Parse an LDAP-URL conforming to RFC 4516 into a hash containing its
205 elements.
206 For easy cooperation with LDAP queries, the hash keys for the
208 elements used in LDAP search operations are named after the
209 parameters to "search" in Net::LDAP.
210 In extension to RFC 4516, the socket path for URLs with the scheme
212 "ldapi" will be stored in the hash key named "path".
213 If any element is omitted, the result depends on the setting of the
215 option "defaults".
216 OPTIONS is a list of key/value pairs with the following keys
218 recognized:
219 defaults
221 A Boolean option that determines whether default values
222 according to RFC 4516 shall be returned for missing URL
223 elements.
224 If set to TRUE, default values are returned, with
226 "ldap_url_parse" using the following defaults in extension to
227 RFC 4516.
228 • The default port for "ldaps" URLs is 636.
230 • The default path for "ldapi" URLs is the contents of the
232 environment variable "LDAPI_SOCK". If that is not defined
233 or empty, then "/var/run/ldapi" is used.
234 This is consistent with the behaviour of "new" in
236 Net::LDAP.
237 • The default "host" name for "ldap" and "ldaps" URLs is
239 "localhost".
240 When set to FALSE, no default values are used.
242 This leaves all keys in the resulting hash undefined where the
244 corresponding URL element is empty.
245 To distinguish between an empty base DN and an undefined base
247 DN, "ldap_url_parse" uses the slash between the host:port resp.
248 path part of the URL and the base DN part of the URL. With the
249 slash present, the hash key "base" is set to the empty string,
250 without it, it is left undefined.
251 Leaving away the "defaults" option entirely is equivalent to
253 setting it to TRUE.
254 Returns the hash in list mode, or the reference to the hash in
256 scalar mode.
257 generalizedTime_to_time ( GENERALIZEDTIME )
259 Convert the generalizedTime string GENERALIZEDTIME, which is
260 expected to match the template
261 "YYYYmmddHH[MM[SS]][(./,)d...](Z|(+/-)HH[MM])" to a floating point
262 number compatible with UNIX time (i.e. the integral part of the
263 number is a UNIX time).
264 Returns an extended UNIX time or "undef" on error.
266 Times in years smaller than 1000 will lead to "undef" being
268 returned. This restriction is a direct effect of the year value
269 interpretation rules in Time::Local.
270 Note: this function depends on Perl's implementation of time and
272 Time::Local. See "Limits of time_t" in Time::Local, "Negative
273 Epoch Values" in Time::Local, and "gmtime" in perlport for
274 restrictions in older versions of Perl.
275 time_to_generalizedTime ( TIME [, OPTIONS ] )
277 Convert the UNIX time TIME to a generalizedTime string.
278 In extension to UNIX times, TIME may be a floating point number,
280 the decimal part will be used for the resulting generalizedTime.
281 OPTIONS is a list of key/value pairs. The following keys are
283 recognized:
284 AD Take care of an ActiveDirectory peculiarity to always require
286 decimals.
287 Returns the generalizedTime string, or "undef" on error.
289 Times before BC or after year 9999 result in "undef" as they cannot
291 be represented in the generalizedTime format.
292 Note: this function depends on Perl's implementation of gmtime.
294 See "Limits of time_t" in Time::Local, "Negative Epoch Values" in
295 Time::Local, and "gmtime" in perlport for restrictions in older
296 versions of Perl.
297
299 Graham Barr <gbarr@pobox.com>
300
302 Copyright (c) 1999-2004 Graham Barr. All rights reserved. This program
303 is free software; you can redistribute it and/or modify it under the
304 same terms as Perl itself.
305 ldap_explode_dn and canonical_dn also
307 (c) 2002 Norbert Klasen, norbert.klasen@daasi.de, All Rights Reserved.
309perl v5.34.0 2022-01-21 Net::LDAP::Util(3)