LDAPGETDN(3) LDAPGETDN(3)

NAME
       ldapgetdn,  ldapexplodedn,  ldapexploderdn, ldapdn2ufn - LDAP DN
       handling routines

LLIIBBRRAARRYY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       ##iinncclluuddee <>

       cchhaarr **llddaappggeettddnn(( LLDDAAPP **lldd,, LLDDAAPPMMeessssaaggee **eennttrryy ))

       iinntt llddaappssttrr22ddnn(( ccoonnsstt cchhaarr **ssttrr,, LLDDAAPPDDNN ****ddnn,, uunnssiiggnneedd ffllaaggss ))

       iinntt llddaappddnn22ssttrr(( LLDDAAPPDDNN **ddnn,, cchhaarr ****ssttrr,, uunnssiiggnneedd ffllaaggss ))

       cchhaarr ****llddaappeexxppllooddeeddnn(( ccoonnsstt cchhaarr **ddnn,, iinntt nnoottyyppeess ))

       cchhaarr ****llddaappeexxppllooddeerrddnn(( ccoonnsstt cchhaarr **rrddnn,, iinntt nnoottyyppeess ))

       cchhaarr **llddaappddnn22uuffnn(( ccoonnsstt cchhaarr ** ddnn ))

       cchhaarr **llddaappddnn22ddcceeddnn(( ccoonnsstt cchhaarr ** ddnn ))

       cchhaarr **llddaappddcceeddnn22ddnn(( ccoonnsstt cchhaarr ** ddnn ))

       cchhaarr **llddaappddnn22aaddccaannoonniiccaall(( ccoonnsstt cchhaarr ** ddnn ))

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   llddaappggeettddnn(())   routine   takes   an   entry   as   returned   by
       llddaappffiirrsstteennttrryy(3) or llddaappnneexxtteennttrryy(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 llddaappmmeemmffrreeee(3).

       llddaappssttrr22ddnn(()) parses a string representation of  a  distinguished  name
       contained  in  ssttrr  into  its  components,  which  are  stored in ddnn as
       llddaappaavvaa structures, arranged in LLDDAAPPAAVVAA,, LLDDAAPPRRDDNN,,  and  LLDDAAPPDDNN  terms,
       defined as:

       ttyyppeeddeeff ssttrruucctt llddaappaavvaa {{
           cchhaarr **llaaaattttrr;;
           ssttrruucctt bbeerrvvaall **llaavvaalluuee;;
           uunnssiiggnneedd llaaffllaaggss;;
       }} LLDDAAPPAAVVAA;;

       ttyyppeeddeeff LLDDAAPPAAVVAA**** LLDDAAPPRRDDNN;;
       ttyyppeeddeeff LLDDAAPPRRDDNN**** LLDDAAPPDDNN;;

       The  attribute  types and the attribute values are not normalized.  The
       llaaffllaaggss can be either LLDDAAPPAAVVAASSTTRRIINNGG or LLDDAAPPAAVVAABBIINNAARRYY,,  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  ffllaaggss  parameter  to
       llddaappssttrr22ddnn(()) can be

            LDAPDNFORMATLDAPV3
            LDAPDNFORMATLDAPV2
            LDAPDNFORMATDCE

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

            LDAPDNPNOSPACES
            LDAPDNPNOSPACEAFTERRDN
            ...
            LDAPDNPEDANTIC

       The latter is a shortcut for all the previous limitations.

       LLDDAAPPDDNNPPNNOOSSPPAACCEESS 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).

       LLDDAAPPDDNNPPNNOOSSPPAACCEEAAFFTTEERRRRDDNN  does  not  allow a single space after RDN
       separators.

       llddaappddnn22ssttrr(()) performs the inverse operation, yielding in ssttrr a  string
       representation  of  ddnn..   It  allows  the  same  values  for  ffllaaggss  as
       llddaappssttrr22ddnn(()),, plus

            LDAPDNFORMATUFN
            LDAPDNFORMATADCANONICAL

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

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

       The llddaappeexxppllooddeeddnn(()) routine takes a DN as returned  by  llddaappggeettddnn(())
       and  breaks  it  up  into its component parts.  Each part is known as a
       Relative Distinguished Name, or RDN.  llddaappeexxppllooddeeddnn(()) 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 llddaappvvaalluueeffrreeee(3).

       Similarly,  the  llddaappeexxppllooddeerrddnn(()) routine takes an RDN as returned by
       llddaappeexxppllooddeeddnn((ddnn,,00)) 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
       llddaappvvaalluueeffrreeee(3).

       llddaappddnn22uuffnn(()) is used to turn a DN as returned by llddaappggeettddnn(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 llddaappmmeemmffrreeee(3).

       llddaappddnn22ddcceeddnn(()) is used to turn a DN as returned by llddaappggeettddnn(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.  llddaappddcceeddnn22ddnn(()) performs the
       opposite operation.  llddaappddnn22aaddccaannoonniiccaall(()) 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 llddaappmmeemmffrreeee(3).

EERRRROORRSS
       If an error occurs in llddaappggeettddnn(()), NULL is returned and the  llddeerrrrnnoo
       field  in  the  ld  parameter  is  set  to  indicate  the  error.   See
       llddaappeerrrroorr(3)   for   a   description   of   possible   error    codes.
       llddaappeexxppllooddeeddnn(()),  llddaappeexxppllooddeerrddnn(()), llddaappddnn22uuffnn(()),, llddaappddnn22ddcceeddnn(()),,
       llddaappddcceeddnn22ddnn(()),,  and  llddaappddnn22aaddccaannoonniiccaall(())  will  return  NULL  with
       eerrrrnnoo(3) set appropriately in case of trouble.

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

SEE ALSO
       llddaapp(3),     llddaappeerrrroorr(3),    llddaappffiirrsstteennttrryy(3),    llddaappmmeemmffrreeee(3),
       llddaappvvaalluueeffrreeee(3)

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



OpenLDAP 2.2.19                   2004/11/26                    LDAPGETDN(3)