Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::LDAP::Util(3)    User Contributed Perl Documentation   Net::LDAP::Util(3)

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 DN	in a canonical form. Returns undef if DN is
	   not a valid Distinguished Name. (Note: The empty string "" is a
	   valid DN.)  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 DN:

	   o   Removes the leading 'OID.' characters if	the type is an OID
	       instead of a name.

	   o   Escapes all RFC 4514 special characters (",", "+", """, "\",
	       "<", ">", ";", "#", "=",	" "), slashes ("/"), and any other
	       character where the ASCII code is < 32 as \hexpair.

	   o   Converts	all leading and	trailing spaces	in values to be	\20.

	   o   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
	       If TRUE,	characters that	are encoded as a multi-octet UTF-8
	       sequence	will be	escaped	as \(hexpair){2,*}.

	   reverse
	       If TRUE,	the RDN	sequence is reversed.

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

       ldap_explode_dn ( DN [ ,	OPTIONS	] )
	   Explodes the	given DN into an array of hashes and returns a
	   reference to	this array. Returns undef if DN	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 DN 'OU=Sales+CN=J. Smith,DC=example,DC=net'	is
	   exploded to:
	    [
	      {
		'OU' =>	'Sales',
		'CN' =>	'J. Smith'
	      },
	      {
		'DC' =>	'example'
	      },
	      {
		'DC' =>	'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"
	      },
	      {
		'DC' =>	'example'
	      },
	      {
		'DC' =>	'com'
	      }
	    ];

	   It also performs the	following operations on	the given DN:

	   o   Unescape	"\" followed by	",", "+", """, "\", "<", ">", ";",
	       "#", "=", " ", or a hexpair and strings beginning with "#".

	   o   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
	       If 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.

	       o   The default port for	"ldaps"	URLs is	636.

	       o   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.

	       o   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 DN and an undefined	base
	       DN, "ldap_url_parse" 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 "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	BC 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
       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.

       ldap_explode_dn and canonical_dn	also

       (c) 2002	Norbert	Klasen,	norbert.klasen@daasi.de, All Rights Reserved.

perl v5.32.1			  2015-04-02		    Net::LDAP::Util(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::LDAP::Util&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help