Net::LDAP::Util • man page

Net::LDAP::Util (3)

Leading comments

Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Net::LDAP::Util.3pm".)

NAME

Net::LDAP::Util - Utility functions

SYNOPSIS

  use Net::LDAP::Util qw(ldap_error_text
                         ldap_error_name
                         ldap_error_desc
                        );

  $mesg = $ldap->search( .... );

  die "Error ",ldap_error_name($mesg)  if $mesg->code;

DESCRIPTION

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

FUNCTIONS

ldap_error_name ( ERR )

Returns the name corresponding with

ERR. ERR

can either be an

LDAP

error number, or a "Net::LDAP::Message" object containing an error code. If the error is not known the a string in the form "LDAP error code %d(0x%02X)" is returned.

ldap_error_text ( ERR )

Returns the text from the

POD

description for the given error.

ERR

can either be an

LDAP

error code, or a "Net::LDAP::Message" object containing an

LDAP

error code. If the error code given is unknown then "undef" is returned.

ldap_error_desc ( ERR )

Returns a short text description of the error.

ERR

can either be an

LDAP

error code or a "Net::LDAP::Message" object containing an

LDAP

error code.

canonical_dn ( DN [ , OPTIONS ] )

Returns the given

in a canonical form. Returns undef if

is not a valid Distinguished Name. (Note: The empty string "" is a valid

DN.

)

can either be a string or reference to an array of hashes as returned by ldap_explode_dn, which is useful when constructing a

DN.

It performs the following operations on the given

*: Removes the leading '
OID.
' characters if the type is an
OID
instead of a name.
*: Escapes all
RFC 4514
special characters (``,'', ``+'', ""``, ''\``, ''<``, ''>``, '';``, ''#``, ''=``, '' ``), slashes (''/"), and any other character where the
ASCII
code is < 32 as \hexpair.
*: Converts all leading and trailing spaces in values to be \20.
*: If an
RDN
contains multiple parts, the parts are re-ordered so that the attribute type names are in alphabetical order.

OPTIONS

is a list of name/value pairs, valid options are:

casefold

Controls case folding of attribute type names. Attribute values are not affected by this option. The default is to uppercase. Valid values are:

lower: Lowercase attribute type names.
upper: Uppercase attribute type names. This is the default.
none: Do not change attribute type names.

mbcescape

TRUE,

characters that are encoded as a multi-octet

UTF-8

sequence will be escaped as \(hexpair){2,*}.

reverse

TRUE,

the

RDN

sequence is reversed.

separator

Separator to use between RDNs. Defaults to comma (',').

ldap_explode_dn ( DN [ , OPTIONS ] )

Explodes the given

into an array of hashes and returns a reference to this array. Returns undef if

is not a valid Distinguished Name.

A Distinguished Name is a sequence of Relative Distinguished Names (RDNs), which themselves are sets of Attributes. For each

RDN

a hash is constructed with the attribute type names as keys and the attribute values as corresponding values. These hashes are then stored in an array in the order in which they appear in the

DN.

For example, the

'OU=Sales+CN=J. Smith,DC=example,DC=net' is exploded to:
[
{
'

' => 'Sales',
'

' => 'J. Smith'
   },
   {
     '

' => 'example'
   },
   {
     '

' => 'net'
}
]

(

RFC4514

string) DNs might also contain values, which are the bytes of the

BER

encoding of the X.500 AttributeValue rather than some

LDAP

string syntax. These values are hex-encoded and prefixed with a #. To distinguish such

BER

values, ldap_explode_dn uses references to the actual values, e.g. '1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com' is exploded to:
[
   {
     '1.3.6.1.4.1.1466.0' => ``\004\002Hi''
   },
   {
     '

' => 'example'
   },
   {
     '

' => 'com'
}
];

It also performs the following operations on the given

DN:

*: Unescape ``\'' followed by ``,'', ``+'', ""``, ''\``, ''<``, ''>``, '';``, ''#``, ''=``, '' ``, or a hexpair and strings beginning with ''#".
*: Removes the leading '
OID.
' characters if the type is an
OID
instead of a name.

OPTIONS

is a list of name/value pairs, valid options are:

casefold

Controls case folding of attribute types names. Attribute values are not affected by this option. The default is to uppercase. Valid values are:

lower: Lowercase attribute types names.
upper: Uppercase attribute type names. This is the default.
none: Do not change attribute type names.

reverse

TRUE,

the

RDN

sequence is reversed.

escape_filter_value ( VALUES )

Escapes the given

VALUES

according to

RFC 4515

so that they can be safely used in

LDAP

filters.

Any control characters with an

ASCII

code < 32 as well as the characters with special meaning in

LDAP

filters ``*'', ``('', ``)'', and ``\'' the backslash are converted into the representation of a backslash followed by two hex digits representing the hexadecimal value of the character.

Returns the converted list in list mode and the first element in scalar mode.

unescape_filter_value ( VALUES )

Undoes the conversion done by escape_filter_value().

Converts any sequences of a backslash followed by two hex digits into the corresponding character.

Returns the converted list in list mode and the first element in scalar mode.

escape_dn_value ( VALUES )

Escapes the given

VALUES

according to

RFC 4514

so that they can be safely used in

LDAP

DNs.

The characters ``,'', ``+'', ""``, ''\``, ''<``, ''>``, '';``, ''#``, ''=" with a special meaning in section 2.4 of

RFC 4514

are preceded by a backslash. Control characters with an

ASCII

code < 32 are represented as \hexpair. Finally all leading and trailing spaces are converted to sequences of \20.

Returns the converted list in list mode and the first element in scalar mode.

unescape_dn_value ( VALUES )

Undoes the conversion done by escape_dn_value().

Any escape sequence starting with a backslash - hexpair or special character - will be transformed back to the corresponding character.

Returns the converted list in list mode and the first element in scalar mode.

ldap_url_parse ( LDAP-URL [, OPTIONS ] )

Parse an LDAP-URL conforming to

RFC 4516

into a hash containing its elements.

For easy cooperation with

LDAP

queries, the hash keys for the elements used in

LDAP

search operations are named after the parameters to ``search'' in Net::LDAP.

In extension to

RFC 4516,

the socket path for URLs with the scheme "ldapi" will be stored in the hash key named "path".

If any element is omitted, the result depends on the setting of the option "defaults".

OPTIONS

is a list of key/value pairs with the following keys recognized:

defaults

A Boolean option that determines whether default values according to

RFC 4516

shall be returned for missing

URL

elements.

If set to

TRUE,

default values are returned, with "ldap_url_parse" using the following defaults in extension to

RFC 4516.

*: The default port for "ldaps" URLs is 636.
*: The default path for "ldapi" URLs is the contents of the environment variable "LDAPI_SOCK". If that is not defined or empty, then "/var/run/ldapi" is used.
This is consistent with the behaviour of ``new'' in Net::LDAP.
*: The default "host" name for "ldap" and "ldaps" URLs is "localhost".

When set to

FALSE,

no default values are used.

This leaves all keys in the resulting hash undefined where the corresponding

URL

element is empty.

To distinguish between an empty base

and an undefined base

DN,

"ldap_url_parse" uses the slash between the host:port resp. path part of the

URL

and the base

part of the

URL.

With the slash present, the hash key "base" is set to the empty string, without it, it is left undefined.

Leaving away the "defaults" option entirely is equivalent to setting it to

TRUE.

: Returns the hash in list mode, or the reference to the hash in scalar mode.

generalizedTime_to_time ( GENERALIZEDTIME )

Convert the generalizedTime string

GENERALIZEDTIME

, which is expected to match the template "YYYYmmddHH[MM[SS]][(./,)d...](Z|(+/-)HH[MM])" to a floating point number compatible with

UNIX

time (i.e. the integral part of the number is a

UNIX

time).

Returns an extended

UNIX

time or "undef" on error.

Times in years smaller than 1000 will lead to "undef" being returned. This restriction is a direct effect of the year value interpretation rules in Time::Local.

Note: this function depends on Perl's implementation of time and Time::Local. See ``Limits of time_t'' in Time::Local, ``Negative Epoch Values'' in Time::Local, and ``gmtime'' in perlport for restrictions in older versions of Perl.

time_to_generalizedTime ( TIME [, OPTIONS ] )

Convert the

UNIX

time

TIME

to a generalizedTime string.

In extension to

UNIX

times,

TIME

may be a floating point number, the decimal part will be used for the resulting generalizedTime.

OPTIONS

is a list of key/value pairs. The following keys are recognized:

AD: Take care of an ActiveDirectory peculiarity to always require decimals.

Returns the generalizedTime string, or "undef" on error.

Times before

or after year 9999 result in "undef" as they cannot be represented in the generalizedTime format.

Note: this function depends on Perl's implementation of gmtime. See ``Limits of time_t'' in Time::Local, ``Negative Epoch Values'' in Time::Local, and ``gmtime'' in perlport for restrictions in older versions of Perl.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

ldap_explode_dn and canonical_dn also

Net::LDAP::Util • man page

Net::LDAP::Util • man page

Net::LDAP::Util (3)

Leading comments

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

AUTHOR

COPYRIGHT

Man Section

extra • Version

extra • Source

extra • Book