ldap_get_dn man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

LDAP_GET_DN(3)							LDAP_GET_DN(3)

NAME
       ldap_get_dn,  ldap_explode_dn,  ldap_explode_rdn, ldap_dn2ufn - LDAP DN
       handling routines

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       #include <ldap.h>

       char *ldap_get_dn( LDAP *ld, LDAPMessage *entry )

       int ldap_str2dn( const char *str, LDAPDN **dn, unsigned flags )

       int ldap_dn2str( LDAPDN *dn, char **str, unsigned flags )

       char **ldap_explode_dn( const char *dn, int notypes )

       char **ldap_explode_rdn( const char *rdn, int notypes )

       char *ldap_dn2ufn( const char * dn )

       char *ldap_dn2dcedn( const char * dn )

       char *ldap_dcedn2dn( const char * dn )

       char *ldap_dn2ad_canonical( const char * dn )

DESCRIPTION
       These routines allow LDAP entry names (Distinguished Names, or DNs)  to
       be  obtained, parsed, converted to a user-friendly form, and tested.  A
       DN has the form described in RFC	 2253  "Lightweight  Directory	Access
       Protocol (v3): UTF-8 String Representation of Distinguished Names".

       The   ldap_get_dn()   routine   takes   an   entry   as	 returned   by
       ldap_first_entry(3) or ldap_next_entry(3) and returns  a	 copy  of  the
       entry's	DN.   Space for the DN will be obtained dynamically and should
       be freed by the caller using ldap_memfree(3).

       ldap_str2dn() parses a string representation of	a  distinguished  name
       contained  in  str  into	 its  components,  which  are  stored in dn as
       ldap_ava structures, arranged in LDAPAVA, LDAPRDN,  and	LDAPDN	terms,
       defined as:

       typedef struct ldap_ava {
	   char *la_attr;
	   struct berval *la_value;
	   unsigned la_flags;
       } LDAPAVA;

       typedef LDAPAVA** LDAPRDN;
       typedef LDAPRDN** LDAPDN;

       The  attribute  types and the attribute values are not normalized.  The
       la_flags can be either LDAP_AVA_STRING or LDAP_AVA_BINARY,  the	latter
       meaning	that the value is BER/DER encoded and thus must be represented
       as, quoting from RFC 2253, " ... an octothorpe character ('#' ASCII 35)
       followed	 by the hexadecimal representation of each of the bytes of the
       BER encoding of the X.500  AttributeValue."   The  flags	 parameter  to
       ldap_str2dn() can be

	    LDAP_DN_FORMAT_LDAPV3
	    LDAP_DN_FORMAT_LDAPV2
	    LDAP_DN_FORMAT_DCE

       which  defines  what  DN syntax is expected (according to RFC 2253, RFC
       1779 and DCE, respectively).  The format can be ORed to the flags

	    LDAP_DN_P_NO_SPACES
	    LDAP_DN_P_NO_SPACE_AFTER_RDN
	    ...
	    LDAP_DN_PEDANTIC

       The latter is a shortcut for all the previous limitations.

       LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the  default
       is to silently eliminate spaces around AVA separators ('='), RDN compo‐
       nent separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN  separa‐
       tors (',' LDAPv3/LDAPv2 or '/' for DCE).

       LDAP_DN_P_NO_SPACE_AFTER_RDN  does  not	allow a single space after RDN
       separators.

       ldap_dn2str() performs the inverse operation, yielding in str a	string
       representation  of  dn.	 It  allows  the  same	values	for  flags  as
       ldap_str2dn(), plus

	    LDAP_DN_FORMAT_UFN
	    LDAP_DN_FORMAT_AD_CANONICAL

       for user-friendly naming (RFC 1781) and AD canonical.

       The  following  routines	 are  viewed  as  deprecated   in   favor   of
       ldap_str2dn()  and  ldap_dn2str().  They are provided to support legacy
       applications.

       The ldap_explode_dn() routine takes a DN as returned  by	 ldap_get_dn()
       and  breaks  it	up  into its component parts.  Each part is known as a
       Relative Distinguished Name, or RDN.  ldap_explode_dn() returns a NULL-
       terminated  array, each component of which contains an RDN from the DN.
       The notypes parameter is used to request that only the  RDN  values  be
       returned,  not  their  types.  For example, the DN "cn=Bob, c=US" would
       return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US",  NULL  },
       depending  on whether notypes was 0 or 1, respectively.	Assertion val‐
       ues in RDN strings may included escaped characters.  The result can  be
       freed by calling ldap_value_free(3).

       Similarly,  the	ldap_explode_rdn() routine takes an RDN as returned by
       ldap_explode_dn(dn,0) and breaks it up into its "type=value"  component
       parts  (or  just	 "value",  if the notypes parameter is set).  Note the
       value  is  not  unescaped.   The	 result	 can  be  freed	  by   calling
       ldap_value_free(3).

       ldap_dn2ufn() is used to turn a DN as returned by ldap_get_dn(3) into a
       more user-friendly form, stripping off all type names.  See "Using  the
       Directory  to Achieve User Friendly Naming" (RFC 1781) for more details
       on the UFN format.  Due to the ambigious nature of the  format,	it  is
       generally  only	used  for  display  purposes.	The  space for the UFN
       returned is obtained dynamically and the user is responsible for	 free‐
       ing it via a call to ldap_memfree(3).

       ldap_dn2dcedn() is used to turn a DN as returned by ldap_get_dn(3) into
       a DCE-style DN, e.g. a string with most-significant to  least  signifi‐
       cant  rdns  separated by slashes ('/'); rdn components are separated by
       commas (',').  Only printable chars (e.g. LDAPv2 printable string)  are
       allowed, at least in this implementation.  ldap_dcedn2dn() performs the
       opposite operation.  ldap_dn2ad_canonical() turns a DN into a AD canon‐
       ical  name,  which  is basically a DCE dn with attribute types omitted.
       The trailing domain, if present, is turned in a DNS-like	 domain.   The
       space  for  the	returned value is obtained dynamically and the user is
       responsible for freeing it via a call to ldap_memfree(3).

ERRORS
       If an error occurs in ldap_get_dn(), NULL is returned and the  ld_errno
       field  in  the  ld  parameter  is  set  to  indicate  the  error.   See
       ldap_error(3)   for   a	 description   of   possible   error	codes.
       ldap_explode_dn(),  ldap_explode_rdn(), ldap_dn2ufn(), ldap_dn2dcedn(),
       ldap_dcedn2dn(),	 and  ldap_dn2ad_canonical()  will  return  NULL  with
       errno(3) set appropriately in case of trouble.

NOTES
       These routines dynamically allocate memory that the caller must free.

SEE ALSO
       ldap(3),	    ldap_error(3),    ldap_first_entry(3),    ldap_memfree(3),
       ldap_value_free(3)

ACKNOWLEDGEMENTS
       OpenLDAP	 is  developed	and  maintained	 by   The   OpenLDAP   Project
       (http://www.openldap.org/).   OpenLDAP  is  derived  from University of
       Michigan LDAP 3.3 Release.

OpenLDAP 2.1.X			  RELEASEDATE			LDAP_GET_DN(3)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net