Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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 )

       void ldap_dnfree( LDAPDN dn )

       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 4414 "Lightweight  Directory
       Access Protocol (LDAP): 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 compo-nents, components,
       nents, which are stored in dn as ldap_ava structures, arranged in LDAPAVA, LDAPRDN, and LDAPDN terms.
       Space  for  dn  will  be obtained dynamically and should be freed by the caller using ldap_dnfree(3).
       The LDAPDN is 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 4514, " ... an octothorpe character ('#' ASCII 35)  followed
       by  the  hexadecimal  representation of each of the bytes of the BER encoding of the X.500 Attribute-Value." AttributeValue."
       Value."  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 4514, 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 spa-ces spaces
       ces 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 com-ponent component
       ponent 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 }, depend-ing depending
       ing 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 ambiguous 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  sepa-rated separated
       rated  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 trail-ing trailing
       ing 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 Software is developed and maintained by  The  OpenLDAP  Project  <http://www.openldap.org/>.
       OpenLDAP Software is derived from University of Michigan LDAP 3.3 Release.



OpenLDAP 2.4.28                                  2011/11/24                                   LDAP_GET_DN(3)