1Net::LDAP::Util(3)    User Contributed Perl Documentation   Net::LDAP::Util(3)
2
3
4

NAME

6       Net::LDAP::Util - Utility functions
7

SYNOPSIS

9         use Net::LDAP::Util qw(ldap_error_text
10                                ldap_error_name
11                                ldap_error_desc
12                               );
13
14         $mesg = $ldap->search( .... );
15
16         die "Error ",ldap_error_name($mesg)  if $mesg->code;
17

DESCRIPTION

19       Net::LDAP::Util is a collection of utility functions for use with the
20       Net::LDAP modules.
21

FUNCTIONS

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
29       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
35       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
40       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
47           It performs the following operations on the given DN:
48
49           •   Removes the leading 'OID.' characters if the type is an OID
50               instead of a name.
51
52           •   Escapes all RFC 4514 special characters (",", "+", """, "\",
53               "<", ">", ";", "#", "=", " "), slashes ("/"), and any other
54               character where the ASCII code is < 32 as \hexpair.
55
56           •   Converts all leading and trailing spaces in values to be \20.
57
58           •   If an RDN contains multiple parts, the parts are re-ordered so
59               that the attribute type names are in alphabetical order.
60
61           OPTIONS is a list of name/value pairs, valid options are:
62
63           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
68               lower
69                   Lowercase attribute type names.
70
71               upper
72                   Uppercase attribute type names. This is the default.
73
74               none
75                   Do not change attribute type names.
76
77           mbcescape
78               If TRUE, characters that are encoded as a multi-octet UTF-8
79               sequence will be escaped as \(hexpair){2,*}.
80
81           reverse
82               If TRUE, the RDN sequence is reversed.
83
84           separator
85               Separator to use between RDNs. Defaults to comma (',').
86
87       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
92           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
98           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
113           (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
131           It also performs the following operations on the given DN:
132
133           •   Unescape "\" followed by ",", "+", """, "\", "<", ">", ";",
134               "#", "=", " ", or a hexpair and strings beginning with "#".
135
136           •   Removes the leading 'OID.' characters if the type is an OID
137               instead of a name.
138
139           OPTIONS is a list of name/value pairs, valid options are:
140
141           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
146               lower
147                   Lowercase attribute types names.
148
149               upper
150                   Uppercase attribute type names. This is the default.
151
152               none
153                   Do not change attribute type names.
154
155           reverse
156               If TRUE, the RDN sequence is reversed.
157
158       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
162           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
168           Returns the converted list in list mode and the first element in
169           scalar mode.
170
171       unescape_filter_value ( VALUES )
172           Undoes the conversion done by escape_filter_value().
173
174           Converts any sequences of a backslash followed by two hex digits
175           into the corresponding character.
176
177           Returns the converted list in list mode and the first element in
178           scalar mode.
179
180       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
184           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
190           Returns the converted list in list mode and the first element in
191           scalar mode.
192
193       unescape_dn_value ( VALUES )
194           Undoes the conversion done by escape_dn_value().
195
196           Any escape sequence starting with a backslash - hexpair or special
197           character - will be transformed back to the corresponding
198           character.
199
200           Returns the converted list in list mode and the first element in
201           scalar mode.
202
203       ldap_url_parse ( LDAP-URL [, OPTIONS ] )
204           Parse an LDAP-URL conforming to RFC 4516 into a hash containing its
205           elements.
206
207           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
211           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
214           If any element is omitted, the result depends on the setting of the
215           option "defaults".
216
217           OPTIONS is a list of key/value pairs with the following keys
218           recognized:
219
220           defaults
221               A Boolean option that determines whether default values
222               according to RFC 4516 shall be returned for missing URL
223               elements.
224
225               If set to TRUE, default values are returned, with
226               "ldap_url_parse" using the following defaults in extension to
227               RFC 4516.
228
229               •   The default port for "ldaps" URLs is 636.
230
231               •   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
235                   This is consistent with the behaviour of "new" in
236                   Net::LDAP.
237
238               •   The default "host" name for "ldap" and "ldaps" URLs is
239                   "localhost".
240
241               When set to FALSE, no default values are used.
242
243               This leaves all keys in the resulting hash undefined where the
244               corresponding URL element is empty.
245
246               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
252               Leaving away the "defaults" option entirely is equivalent to
253               setting it to TRUE.
254
255           Returns the hash in list mode, or the reference to the hash in
256           scalar mode.
257
258       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
265           Returns an extended UNIX time or "undef" on error.
266
267           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
271           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
276       time_to_generalizedTime ( TIME [, OPTIONS ] )
277           Convert the UNIX time TIME to a generalizedTime string.
278
279           In extension to UNIX times, TIME may be a floating point number,
280           the decimal part will be used for the resulting generalizedTime.
281
282           OPTIONS is a list of key/value pairs. The following keys are
283           recognized:
284
285           AD  Take care of an ActiveDirectory peculiarity to always require
286               decimals.
287
288           Returns the generalizedTime string, or "undef" on error.
289
290           Times before BC or after year 9999 result in "undef" as they cannot
291           be represented in the generalizedTime format.
292
293           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

AUTHOR

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
306       ldap_explode_dn and canonical_dn also
307
308       (c) 2002 Norbert Klasen, norbert.klasen@daasi.de, All Rights Reserved.
309
310
311
312perl v5.36.0                      2023-01-24                Net::LDAP::Util(3)
Impressum