/usr/man/cat.3/ldap_dn2ufn.3.Z(/usr/man/cat.3/ldap_dn2ufn.3.Z)

     LDAP_GET_DN(3)           OpenLDAP 2.1.12           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;

     Page 1                                         (printed 1/20/103)

     LDAP_GET_DN(3)           OpenLDAP 2.1.12           LDAP_GET_DN(3)

          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 component separators ('+' for
          LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (','
          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.

     Page 2                                         (printed 1/20/103)

     LDAP_GET_DN(3)           OpenLDAP 2.1.12           LDAP_GET_DN(3)

          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 values 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 freeing 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 significant 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 canonical 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

     Page 3                                         (printed 1/20/103)

     LDAP_GET_DN(3)           OpenLDAP 2.1.12           LDAP_GET_DN(3)

          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.

     Page 4                                         (printed 1/20/103)

See also ldap_dcedn2dn(3):  man 3 ldap_dcedn2dn
See also ldap_dn2ad_canonical(3):  man 3 ldap_dn2ad_canonical
See also ldap_dn2dcedn(3):  man 3 ldap_dn2dcedn
See also ldap_dn2str(3):  man 3 ldap_dn2str
See also ldap_explode_dn(3):  man 3 ldap_explode_dn
See also ldap_explode_rdn(3):  man 3 ldap_explode_rdn
See also ldap_get_dn(3):  man 3 ldap_get_dn
See also ldap_str2dn(3):  man 3 ldap_str2dn