1ldap_get_dn(3LDAP)          LDAP Library Functions          ldap_get_dn(3LDAP)
2
3
4

NAME

6       ldap_get_dn,      ldap_explode_dn,     ldap_dn2ufn,     ldap_is_dns_dn,
7       ldap_explode_dns, ldap_dns_to_dn - LDAP DN handling functions
8

SYNOPSIS

10       cc[ flag... ] file... -lldap[ library... ]
11       #include <lber.h>
12       #include <ldap.h>
13
14       char *ldap_get_dn(LDAP *ld, LDAPMessage *entry);
15
16
17       char **ldap_explode_dn(char *dn, int notypes);
18
19
20       char *ldap_dn2ufn(char *dn);
21
22
23       int ldap_is_dns_dn(char *dn);
24
25
26       char **ldap_explode_dns(char *dn);
27
28
29       char *ldap_dns_to_dn(char *dns_name, int *nameparts);
30
31

DESCRIPTION

33       These functions allow LDAP entry names (Distinguished Names, or DNs) to
34       be  obtained,  parsed, converted to a user-friendly form, and tested. A
35       DN has the form described in RFC 1779  A String Representation of  Dis‐
36       tinguished Names, unless it is an experimental DNS-style DN which takes
37       the form of an RFC 822 mail address.
38
39
40       The  ldap_get_dn()   function   takes   an   entry   as   returned   by
41       ldap_first_entry(3LDAP) or ldap_next_entry(3LDAP) and returns a copy of
42       the entry's DN.  Space for the DN will have been obtained by  means  of
43       malloc(3C), and should be freed by the caller by a call to free(3C).
44
45
46       The  ldap_explode_dn() function takes a DN as returned by ldap_get_dn()
47       and breaks it up into its component parts.  Each part  is  known  as  a
48       Relative  Distinguished Name, or RDN. ldap_explode_dn() returns a null-
49       terminated array, each component of which contains an RDN from the  DN.
50       The  notypes  parameter  is used to request that only the RDN values be
51       returned, not their types.  For example, the DN  "cn=Bob,  c=US"  would
52       return  as  either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL },
53       depending on whether notypes was 0 or 1, respectively. The  result  can
54       be freed by calling ldap_value_free(3LDAP).
55
56
57       ldap_dn2ufn()  is used to turn a DN as returned by ldap_get_dn() into a
58       more user-friendly form, stripping off type names.  See RFC 1781 "Using
59       the  Directory to Achieve User Friendly Naming" for more details on the
60       UFN format.  The space for the UFN returned is obtained by  a  call  to
61       malloc(3C),  and  the  user is responsible for freeing it by means of a
62       call to free(3C).
63
64
65       ldap_is_dns_dn() returns non-zero if the dn string is  an  experimental
66       DNS-style  DN (generally in the form of an RFC 822 e-mail address).  It
67       returns zero if the dn appears to be an RFC 1779 format DN.
68
69
70       ldap_explode_dns() takes a DNS-style DN and breaks it up into its  com‐
71       ponent  parts.  ldap_explode_dns() returns a null-terminated array. For
72       example, the DN "mcs.umich.edu" will return {  "mcs",  "umich",  "edu",
73       NULL }.  The result can be freed by calling ldap_value_free(3LDAP).
74
75
76       ldap_dns_to_dn() converts a DNS domain name into an X.500 distinguished
77       name. A string distinguished  name  and  the  number  of  nameparts  is
78       returned.
79

ERRORS

81       If  an error occurs in ldap_get_dn(), NULL is returned and the ld_errno
82       field  in  the  ld  parameter  is  set  to  indicate  the  error.   See
83       ldap_error(3LDAP)   for   a   description   of  possible  error  codes.
84       ldap_explode_dn(), ldap_explode_dns()  and  ldap_dn2ufn()  will  return
85       NULL with errno(3C) set appropriately in case of trouble.
86
87
88       If  an  error  in ldap_dns_to_dn() is encountered zero is returned. The
89       caller should free the returned string if it is non-zero.
90

ATTRIBUTES

92       See attributes(5) for a description of the following attributes:
93
94
95
96
97       ┌─────────────────────────────┬─────────────────────────────┐
98       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
99       │Availability                 │SUNWcsl (32-bit)             │
100       │                             │SUNWcslx (64-bit)            │
101       │Interface Stability          │Evolving                     │
102       └─────────────────────────────┴─────────────────────────────┘
103

SEE ALSO

105       ldap(3LDAP),        ldap_first_entry(3LDAP),         ldap_error(3LDAP),
106       ldap_value_free(3LDAP)
107

NOTES

109       These functions allocate memory that the caller must free.
110
111
112
113SunOS 5.11                        27 Jan 2002               ldap_get_dn(3LDAP)
Impressum