usr/src/man/man3ldap/ldap_get_dn.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_GET_DN 3LDAP "Jan 27, 2002"
   8 .SH NAME
   9 ldap_get_dn, ldap_explode_dn, ldap_dn2ufn, ldap_is_dns_dn, ldap_explode_dns,
  10 ldap_dns_to_dn \- LDAP DN handling functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  15 #include <lber.h>
  16 #include <ldap.h>
  17
  18 \fBchar *\fR\fBldap_get_dn\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBchar **\fR\fBldap_explode_dn\fR(\fBchar\fR \fI*dn\fR, \fBint\fR \fInotypes\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBchar *\fR\fBldap_dn2ufn\fR(\fBchar\fR \fI*dn\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBldap_is_dns_dn\fR(\fBchar\fR \fI*dn\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBchar **\fR\fBldap_explode_dns\fR(\fBchar\fR \fI*dn\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBchar *\fR\fBldap_dns_to_dn\fR(\fBchar\fR \fI*dns_name\fR, \fBint\fR \fI*nameparts\fR);
  44 .fi
  45
  46 .SH DESCRIPTION
  47 .sp
  48 .LP
  49 These functions allow LDAP entry names (Distinguished Names, or DNs) to be
  50 obtained, parsed, converted to a user-friendly form, and tested. A DN has the
  51 form described in RFC 1779  \fIA String Representation of Distinguished
  52 Names\fR, unless it is an experimental DNS-style DN which takes the form of an
  53 \fIRFC 822\fR mail address.
  54 .sp
  55 .LP
  56 The \fBldap_get_dn()\fR function takes an \fIentry\fR as returned by
  57 \fBldap_first_entry\fR(3LDAP) or \fBldap_next_entry\fR(3LDAP) and returns a
  58 copy of the entry's DN.  Space for the DN will have been obtained by means of
  59 \fBmalloc\fR(3C), and should be freed by the caller by a call to
  60 \fBfree\fR(3C).
  61 .sp
  62 .LP
  63 The \fBldap_explode_dn()\fR function takes a DN as returned by
  64 \fBldap_get_dn()\fR and breaks it up into its component parts.  Each part is
  65 known as a Relative Distinguished Name, or RDN. \fBldap_explode_dn()\fR returns
  66 a null-terminated array, each component of which contains an RDN from the DN.
  67 The \fInotypes\fR parameter is used to request that only the RDN values be
  68 returned, not their types.  For example, the DN "cn=Bob, c=US" would return as
  69 either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on
  70 whether notypes was 0 or 1, respectively. The result can be freed by calling
  71 \fBldap_value_free\fR(3LDAP).
  72 .sp
  73 .LP
  74 \fBldap_dn2ufn()\fR is used to turn a DN as returned by \fBldap_get_dn()\fR
  75 into a more user-friendly form, stripping off type names.  See \fIRFC 1781\fR
  76 "Using the Directory to Achieve User Friendly Naming" for more details on the
  77 UFN format.  The space for the UFN returned is obtained by a call to
  78 \fBmalloc\fR(3C), and the user is responsible for freeing it by means of a call
  79 to \fBfree\fR(3C).
  80 .sp
  81 .LP
  82 \fBldap_is_dns_dn()\fR returns non-zero if the dn string is an experimental
  83 DNS-style DN (generally in the form of an \fIRFC 822\fR e-mail address).  It
  84 returns zero if the dn appears to be an \fIRFC 1779\fR format DN.
  85 .sp
  86 .LP
  87 \fBldap_explode_dns()\fR takes a DNS-style DN and breaks it up into its
  88 component parts. \fBldap_explode_dns()\fR returns a null-terminated array. For
  89 example, the DN "mcs.umich.edu" will return { "mcs", "umich", "edu", NULL }.
  90 The result can be freed by calling \fBldap_value_free\fR(3LDAP).
  91 .sp
  92 .LP
  93 \fBldap_dns_to_dn()\fR converts a DNS domain name into an X.500 distinguished
  94 name. A string distinguished name and the number of nameparts is returned.
  95 .SH ERRORS
  96 .sp
  97 .LP
  98 If an error occurs in \fBldap_get_dn()\fR, \fINULL\fR is returned and the
  99 \fBld_errno\fR field in the \fIld\fR parameter is set to indicate the error.
 100 See \fBldap_error\fR(3LDAP) for a description of possible error codes.
 101 \fBldap_explode_dn()\fR, \fBldap_explode_dns()\fR and \fBldap_dn2ufn()\fR will
 102 return  \fINULL\fR with \fBerrno\fR(3C) set appropriately in case of trouble.
 103 .sp
 104 .LP
 105 If an error in \fBldap_dns_to_dn()\fR is encountered zero is returned. The
 106 caller should free the returned string if it is non-zero.
 107 .SH ATTRIBUTES
 108 .sp
 109 .LP
 110 See \fBattributes\fR(5) for a description of the following attributes:
 111 .sp
 112
 113 .sp
 114 .TS
 115 box;
 116 c | c
 117 l | l .
 118 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 119 Interface Stability     Evolving
 120 .TE
 121
 122 .SH SEE ALSO
 123 .sp
 124 .LP
 125 \fBldap\fR(3LDAP), \fBldap_first_entry\fR(3LDAP), \fBldap_error\fR(3LDAP),
 126 \fBldap_value_free\fR(3LDAP)
 127 .SH NOTES
 128 .sp
 129 .LP
 130 These functions allocate memory that the caller must free.