.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::LDAP::Util 3pm"
.TH Net::LDAP::Util 3pm "2012-01-29" "perl v5.14.2" "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 ( \s-1ERR\s0 )" 4
.IX Item "ldap_error_name ( ERR )"
Returns the name corresponding with \s-1ERR\s0. \s-1ERR\s0 can either be an \s-1LDAP\s0
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 ( \s-1ERR\s0 )" 4
.IX Item "ldap_error_text ( ERR )"
Returns the text from the \s-1POD\s0 description for the given error. \s-1ERR\s0 can
either be an \s-1LDAP\s0 error code, or a \f(CW\*(C`Net::LDAP::Message\*(C'\fR object
containing an \s-1LDAP\s0 error code. If the error code given is unknown then
\&\f(CW\*(C`undef\*(C'\fR is returned.
.IP "ldap_error_desc ( \s-1ERR\s0 )" 4
.IX Item "ldap_error_desc ( ERR )"
Returns a short text description of the error. \s-1ERR\s0 can either be an
\&\s-1LDAP\s0 error code or a \f(CW\*(C`Net::LDAP::Message\*(C'\fR object containing an \s-1LDAP\s0
error code.
.IP "canonical_dn ( \s-1DN\s0 [ , \s-1OPTIONS\s0 ] )" 4
.IX Item "canonical_dn ( DN [ , OPTIONS ] )"
Returns the given \fB\s-1DN\s0\fR in a canonical form. Returns undef if \fB\s-1DN\s0\fR is
not a valid Distinguished Name. (Note: The empty string "" is a valid \s-1DN\s0.)
\&\fB\s-1DN\s0\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 \s-1DN\s0.
.Sp
It performs the following operations on the given \fB\s-1DN\s0\fR:
.RS 4
.IP "\(bu" 4
Removes the leading '\s-1OID\s0.' characters if the type is an \s-1OID\s0 instead
of a name.
.IP "\(bu" 4
Escapes all \s-1RFC\s0 2253 special characters (\*(L",\*(R", \*(L"+\*(R", ""\*(L", \*(R"\e\*(L", \*(R"<\*(L",
\&\*(R">\*(L", \*(R";\*(L", \*(R"#\*(L", \*(R"=\*(L", \*(R" \*(L"), slashes (\*(R"/"), and any other character
where the \s-1ASCII\s0 code is < 32 as \ehexpair.
.IP "\(bu" 4
Converts all leading and trailing spaces in values to be \e20.
.IP "\(bu" 4
If an \s-1RDN\s0 contains multiple parts, the parts are re-ordered so that
the attribute type names are in alphabetical order.
.RE
.RS 4
.Sp
\&\fB\s-1OPTIONS\s0\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 \s-1TRUE\s0, characters that are encoded as a multi-octet \s-1UTF\-8\s0 sequence 
will be escaped as \e(hexpair){2,*}.
.IP "reverse" 4
.IX Item "reverse"
If \s-1TRUE\s0, the \s-1RDN\s0 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 ( \s-1DN\s0 [ , \s-1OPTIONS\s0 ] )" 4
.IX Item "ldap_explode_dn ( DN [ , OPTIONS ] )"
Explodes the given \fB\s-1DN\s0\fR into an array of hashes and returns a reference to this 
array. Returns undef if \fB\s-1DN\s0\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 \s-1RDN\s0 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 \s-1DN\s0.
.Sp
For example, the \s-1DN\s0 'OU=Sales+CN=J. Smith,DC=example,DC=net' is exploded to:
 [
   {
     '\s-1OU\s0' => 'Sales',
     '\s-1CN\s0' => 'J. Smith'
   },
   {
     '\s-1DC\s0' => 'example'
   },
   {
     '\s-1DC\s0' => 'net'
   }
 ]
.Sp
(\s-1RFC2253\s0 string) DNs might also contain values, which are the bytes of the 
\&\s-1BER\s0 encoding of the X.500 AttributeValue rather than some \s-1LDAP\s0 string syntax. 
These values are hex-encoded and prefixed with a #. To distinguish such \s-1BER\s0 
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' => \*(L"\e004\e002Hi\*(R"
   },
   {
     '\s-1DC\s0' => 'example'
   },
   {
     '\s-1DC\s0' => 'com'
   }
 ];
.Sp
It also performs the following operations on the given \s-1DN:\s0
.RS 4
.IP "\(bu" 4
Unescape \*(L"\e\*(R" followed by \*(L",\*(R", \*(L"+\*(R", ""\*(L", \*(R"\e\*(L", \*(R"<\*(L", \*(R">\*(L", \*(R";\*(L",
\&\*(R"#\*(L", \*(R"=\*(L", \*(R" \*(L", or a hexpair and and strings beginning with \*(R"#".
.IP "\(bu" 4
Removes the leading '\s-1OID\s0.' characters if the type is an \s-1OID\s0 instead
of a name.
.RE
.RS 4
.Sp
\&\fB\s-1OPTIONS\s0\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 \s-1TRUE\s0, the \s-1RDN\s0 sequence is reversed.
.RE
.RS 4
.RE
.IP "escape_filter_value ( \s-1VALUES\s0 )" 4
.IX Item "escape_filter_value ( VALUES )"
Escapes the given \fB\s-1VALUES\s0\fR according to \s-1RFC\s0 2254 so that they
can be safely used in \s-1LDAP\s0 filters.
.Sp
Any control characters with an \s-1ACII\s0 code < 32 as well as the
characters with special meaning in \s-1LDAP\s0 filters \*(L"*\*(R", \*(L"(\*(R", \*(L")\*(R",
and \*(L"\e\*(R" 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 ( \s-1VALUES\s0 )" 4
.IX Item "unescape_filter_value ( VALUES )"
Undoes the conversion done by \fB\f(BIescape_filter_value()\fB\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 ( \s-1VALUES\s0 )" 4
.IX Item "escape_dn_value ( VALUES )"
Escapes the given \fB\s-1VALUES\s0\fR according to \s-1RFC\s0 2253 so that they
can be safely used in \s-1LDAP\s0 DNs.
.Sp
The characters \*(L",\*(R", \*(L"+\*(R", ""\*(L", \*(R"\e\*(L", \*(R"<\*(L", \*(R">\*(L", \*(R";\*(L", \*(R"#\*(L", \*(R"="
with a special meaning in \s-1RFC\s0 2252 are preceded by ba backslash.
Control characters with an \s-1ASCII\s0 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 ( \s-1VALUES\s0 )" 4
.IX Item "unescape_dn_value ( VALUES )"
Undoes the conversion done by \fB\f(BIescape_dn_value()\fB\fR.
.Sp
Any escape sequence starting with a baskslash \- 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.
.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.