.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::LDAP::Util 3"
.TH Net::LDAP::Util 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::LDAP::Util \- Utility functions
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  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;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBNet::LDAP::Util\fR is a collection of utility functions for use with
the Net::LDAP modules.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.IP "ldap_error_name ( ERR )" 4
.IX Item "ldap_error_name ( ERR )"
Returns the name corresponding with ERR. ERR can either be an LDAP
error number, or a \f(CW\*(C`Net::LDAP::Message\*(C'\fR object containing an error
code. If the error is not known the a string in the form \f(CW"LDAP error
code %d(0x%02X)"\fR is returned.
.IP "ldap_error_text ( ERR )" 4
.IX Item "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 \f(CW\*(C`Net::LDAP::Message\*(C'\fR object
containing an LDAP error code. If the error code given is unknown then
\&\f(CW\*(C`undef\*(C'\fR is returned.
.IP "ldap_error_desc ( ERR )" 4
.IX Item "ldap_error_desc ( ERR )"
Returns a short text description of the error. ERR can either be an
LDAP error code or a \f(CW\*(C`Net::LDAP::Message\*(C'\fR object containing an LDAP
error code.
.IP "canonical_dn ( DN [ , OPTIONS ] )" 4
.IX Item "canonical_dn ( DN [ , OPTIONS ] )"
Returns the given \fBDN\fR in a canonical form. Returns undef if \fBDN\fR is
not a valid Distinguished Name. (Note: The empty string "" is a valid DN.)
\&\fBDN\fR 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.
.Sp
It performs the following operations on the given \fBDN\fR:
.RS 4
.IP \(bu 4
Removes the leading 'OID.' characters if the type is an OID instead
of a name.
.IP \(bu 4
Escapes all RFC 4514 special characters (",", "+", """, "\e", "<",
">", ";", "#", "=", " "), slashes ("/"), and any other character
where the ASCII code is < 32 as \ehexpair.
.IP \(bu 4
Converts all leading and trailing spaces in values to be \e20.
.IP \(bu 4
If an RDN contains multiple parts, the parts are re-ordered so that
the attribute type names are in alphabetical order.
.RE
.RS 4
.Sp
\&\fBOPTIONS\fR is a list of name/value pairs, valid options are:
.IP casefold 4
.IX Item "casefold"
Controls case folding of attribute type names. Attribute values are not
affected by this option. The default is to uppercase. Valid values are:
.RS 4
.IP lower 4
.IX Item "lower"
Lowercase attribute type names.
.IP upper 4
.IX Item "upper"
Uppercase attribute type names. This is the default.
.IP none 4
.IX Item "none"
Do not change attribute type names.
.RE
.RS 4
.RE
.IP mbcescape 4
.IX Item "mbcescape"
If TRUE, characters that are encoded as a multi-octet UTF\-8 sequence
will be escaped as \e(hexpair){2,*}.
.IP reverse 4
.IX Item "reverse"
If TRUE, the RDN sequence is reversed.
.IP separator 4
.IX Item "separator"
Separator to use between RDNs. Defaults to comma (',').
.RE
.RS 4
.RE
.IP "ldap_explode_dn ( DN [ , OPTIONS ] )" 4
.IX Item "ldap_explode_dn ( DN [ , OPTIONS ] )"
Explodes the given \fBDN\fR into an array of hashes and returns a reference to this
array. Returns undef if \fBDN\fR is not a valid Distinguished Name.
.Sp
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.
.Sp
For example, the DN 'OU=Sales+CN=J. Smith,DC=example,DC=net' is exploded to:
 [
   {
     'OU' => 'Sales',
     'CN' => 'J. Smith'
   },
   {
     'DC' => 'example'
   },
   {
     'DC' => 'net'
   }
 ]
.Sp
(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' => "\e004\e002Hi"
   },
   {
     'DC' => 'example'
   },
   {
     'DC' => 'com'
   }
 ];
.Sp
It also performs the following operations on the given DN:
.RS 4
.IP \(bu 4
Unescape "\e" followed by ",", "+", """, "\e", "<", ">", ";",
"#", "=", " ", or a hexpair and strings beginning with "#".
.IP \(bu 4
Removes the leading 'OID.' characters if the type is an OID instead
of a name.
.RE
.RS 4
.Sp
\&\fBOPTIONS\fR is a list of name/value pairs, valid options are:
.IP casefold 4
.IX Item "casefold"
Controls case folding of attribute types names. Attribute values are not
affected by this option. The default is to uppercase. Valid values are:
.RS 4
.IP lower 4
.IX Item "lower"
Lowercase attribute types names.
.IP upper 4
.IX Item "upper"
Uppercase attribute type names. This is the default.
.IP none 4
.IX Item "none"
Do not change attribute type names.
.RE
.RS 4
.RE
.IP reverse 4
.IX Item "reverse"
If TRUE, the RDN sequence is reversed.
.RE
.RS 4
.RE
.IP "escape_filter_value ( VALUES )" 4
.IX Item "escape_filter_value ( VALUES )"
Escapes the given \fBVALUES\fR according to RFC 4515 so that they
can be safely used in LDAP filters.
.Sp
Any control characters with an ASCII code < 32 as well as the
characters with special meaning in LDAP filters "*", "(", ")",
and "\e" the backslash are converted into the representation
of a backslash followed by two hex digits representing the
hexadecimal value of the character.
.Sp
Returns the converted list in list mode and the first element
in scalar mode.
.IP "unescape_filter_value ( VALUES )" 4
.IX Item "unescape_filter_value ( VALUES )"
Undoes the conversion done by \fBescape_filter_value()\fR.
.Sp
Converts any sequences of a backslash followed by two hex digits
into the corresponding character.
.Sp
Returns the converted list in list mode and the first element
in scalar mode.
.IP "escape_dn_value ( VALUES )" 4
.IX Item "escape_dn_value ( VALUES )"
Escapes the given \fBVALUES\fR according to RFC 4514 so that they
can be safely used in LDAP DNs.
.Sp
The characters ",", "+", """, "\e", "<", ">", ";", "#", "=" 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 \ehexpair.
Finally all leading and trailing spaces are converted to
sequences of \e20.
.Sp
Returns the converted list in list mode and the first element
in scalar mode.
.IP "unescape_dn_value ( VALUES )" 4
.IX Item "unescape_dn_value ( VALUES )"
Undoes the conversion done by \fBescape_dn_value()\fR.
.Sp
Any escape sequence starting with a backslash \- hexpair or
special character \- will be transformed back to the
corresponding character.
.Sp
Returns the converted list in list mode and the first element
in scalar mode.
.IP "ldap_url_parse ( LDAP-URL [, OPTIONS ] )" 4
.IX Item "ldap_url_parse ( LDAP-URL [, OPTIONS ] )"
Parse an \fBLDAP-URL\fR conforming to RFC 4516 into a hash containing its elements.
.Sp
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.
.Sp
In extension to RFC 4516, the socket path for URLs with the scheme \f(CW\*(C`ldapi\*(C'\fR
will be stored in the hash key named \f(CW\*(C`path\*(C'\fR.
.Sp
If any element is omitted, the result depends on the setting of the option
\&\f(CW\*(C`defaults\*(C'\fR.
.Sp
\&\fBOPTIONS\fR is a list of key/value pairs with the following keys recognized:
.RS 4
.IP defaults 4
.IX Item "defaults"
A Boolean option that determines whether default values according to RFC 4516
shall be returned for missing URL elements.
.Sp
If set to TRUE, default values are returned, with \f(CW\*(C`ldap_url_parse\*(C'\fR
using the following defaults in extension to RFC 4516.
.RS 4
.IP \(bu 4
The default port for \f(CW\*(C`ldaps\*(C'\fR URLs is \f(CW636\fR.
.IP \(bu 4
The default path for \f(CW\*(C`ldapi\*(C'\fR URLs is the contents of the environment variable
\&\f(CW\*(C`LDAPI_SOCK\*(C'\fR. If that is not defined or empty, then \f(CW\*(C`/var/run/ldapi\*(C'\fR is used.
.Sp
This is consistent with the behaviour of "new" in Net::LDAP.
.IP \(bu 4
The default \f(CW\*(C`host\*(C'\fR name for \f(CW\*(C`ldap\*(C'\fR and \f(CW\*(C`ldaps\*(C'\fR URLs is \f(CW\*(C`localhost\*(C'\fR.
.RE
.RS 4
.Sp
When set to FALSE, no default values are used.
.Sp
This leaves all keys in the resulting hash undefined where the corresponding
URL element is empty.
.Sp
To distinguish between an empty base DN and an undefined base DN,
\&\f(CW\*(C`ldap_url_parse\*(C'\fR uses the slash between the host:port resp. path
part of the URL and the base DN part of the URL.
With the slash present, the hash key \f(CW\*(C`base\*(C'\fR is set to the empty string,
without it, it is left undefined.
.Sp
Leaving away the \f(CW\*(C`defaults\*(C'\fR option entirely is equivalent to setting it to TRUE.
.RE
.RE
.RS 4
.Sp
Returns the hash in list mode, or the reference to the hash in scalar mode.
.RE
.IP "generalizedTime_to_time ( GENERALIZEDTIME )" 4
.IX Item "generalizedTime_to_time ( GENERALIZEDTIME )"
Convert the generalizedTime string \fBGENERALIZEDTIME\fR, which is expected
to match the template \f(CW\*(C`YYYYmmddHH[MM[SS]][(./,)d...](Z|(+/\-)HH[MM])\*(C'\fR
to a floating point number compatible with UNIX time
(i.e. the integral part of the number is a UNIX time).
.Sp
Returns an extended UNIX time or \f(CW\*(C`undef\*(C'\fR on error.
.Sp
Times in years smaller than 1000 will lead to \f(CW\*(C`undef\*(C'\fR being returned.
This restriction is a direct effect of the year value interpretation rules
in Time::Local.
.Sp
\&\fBNote:\fR 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.
.IP "time_to_generalizedTime ( TIME [, OPTIONS ] )" 4
.IX Item "time_to_generalizedTime ( TIME [, OPTIONS ] )"
Convert the UNIX time \fBTIME\fR to a generalizedTime string.
.Sp
In extension to UNIX times, \fBTIME\fR may be a floating point number,
the decimal part will be used for the resulting generalizedTime.
.Sp
\&\fBOPTIONS\fR is a list of key/value pairs. The following keys are recognized:
.RS 4
.IP AD 4
.IX Item "AD"
Take care of an ActiveDirectory peculiarity to always require decimals.
.RE
.RS 4
.Sp
Returns the generalizedTime string, or \f(CW\*(C`undef\*(C'\fR on error.
.Sp
Times before BC or after year 9999 result in \f(CW\*(C`undef\*(C'\fR
as they cannot be represented in the generalizedTime format.
.Sp
\&\fBNote:\fR 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.
.RE
.SH AUTHOR
.IX Header "AUTHOR"
Graham Barr <gbarr@pobox.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 1999\-2004 Graham Barr. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
.PP
ldap_explode_dn and canonical_dn also
.PP
(c) 2002 Norbert Klasen, norbert.klasen@daasi.de, All Rights Reserved.