| blob | d79ad4bbe294001bc4ec45168a1c4623d565449a |
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_MODIFY 3LDAP "Jan 28, 2002"
8 .SH NAME
9 ldap_modify, ldap_modify_s, ldap_mods_free, ldap_modify_ext, ldap_modify_ext_s
10 \- LDAP entry modification 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>
18 \fBint\fR \fBldap_modify\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*mods\fR[]);
19 .fi
21 .LP
22 .nf
23 \fBint\fR \fBldap_modify_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*mods\fR[]);
24 .fi
26 .LP
27 .nf
28 \fBvoid\fR \fBldap_mods_free\fR(\fBLDAPMod\fR \fI**mods\fR, \fBint\fR \fIfreemods\fR);
29 .fi
31 .LP
32 .nf
33 \fBint\fR \fBldap_modify_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**mods\fR,
34 \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR, \fBint\fR \fI*msgidp\fR);
35 .fi
37 .LP
38 .nf
39 \fBint\fR \fBldap_modify_ext_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**mods\fR,
40 \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR);
41 .fi
43 .SH DESCRIPTION
44 .sp
45 .LP
46 The function \fBldap_modify_s()\fR is used to perform an LDAP modify operation.
47 \fIdn\fR is the DN of the entry to modify, and \fImods\fR is a null-terminated
48 array of modifications to make to the entry. Each element of the \fImods\fR
49 array is a pointer to an \fBLDAPMod\fR structure, which is defined below.
50 .sp
51 .in +2
52 .nf
53 typedef struct ldapmod {
54 int mod_op;
55 char *mod_type;
56 union {
57 char **modv_strvals;
58 struct berval **modv_bvals;
59 } mod_vals;
60 } LDAPMod;
61 #define mod_values mod_vals.modv_strvals
62 #define mod_bvalues mod_vals.modv_bvals
63 .fi
64 .in -2
66 .sp
67 .LP
68 The \fImod_op\fR field is used to specify the type of modification to perform
69 and should be one of \fBLDAP_MOD_ADD\fR, \fBLDAP_MOD_DELETE\fR, or
70 \fBLDAP_MOD_REPLACE\fR. The \fImod_type\fR and \fImod_values\fR fields specify
71 the attribute type to modify and a null-terminated array of values to add,
72 delete, or replace respectively.
73 .sp
74 .LP
75 If you need to specify a non-string value (for example, to add a photo or audio
76 attribute value), you should set \fImod_op\fR to the logical OR of the
77 operation as above (for example, \fBLDAP_MOD_REPLACE\fR) and the constant
78 \fBLDAP_MOD_BVALUES\fR. In this case, \fImod_bvalues\fR should be used instead
79 of \fImod_values\fR, and it should point to a null-terminated array of struct
80 bervals, as defined in <\fBlber.h\fR>.
81 .sp
82 .LP
83 For \fBLDAP_MOD_ADD\fR modifications, the given values are added to the entry,
84 creating the attribute if necessary. For \fBLDAP_MOD_DELETE\fR modifications,
85 the given values are deleted from the entry, removing the attribute if no
86 values remain. If the entire attribute is to be deleted, the \fImod_values\fR
87 field should be set to NULL. For \fBLDAP_MOD_REPLACE\fR modifications, the
88 attribute will have the listed values after the modification, having been
89 created if necessary. All modifications are performed in the order in which
90 they are listed.
91 .sp
92 .LP
93 \fBldap_modify_s()\fR returns the LDAP error code resulting from the modify
94 operation.
95 .sp
96 .LP
97 The \fBldap_modify()\fR operation works the same way as \fBldap_modify_s()\fR,
98 except that it is asynchronous, returning the message id of the request it
99 initiates, or \fB\(mi1\fR on error. The result of the operation can be
100 obtained by calling \fBldap_result\fR(3LDAP).
101 .sp
102 .LP
103 \fBldap_mods_free()\fR can be used to free each element of a null-terminated
104 array of mod structures. If \fIfreemods\fR is non-zero, the \fImods\fR pointer
105 itself is freed as well.
106 .sp
107 .LP
108 The \fBldap_modify_ext()\fR function initiates an asynchronous modify
109 operation and returns \fBLDAP_SUCCESS\fR if the request was successfully sent
110 to the server, or else it returns a LDAP error code if not. See
111 \fBldap_error\fR(3LDAP). If successful, \fBldap_modify_ext()\fR places the
112 message id of the request in \fI*msgidp\fR. A subsequent call to
113 \fBldap_result\fR(3LDAP), can be used to obtain the result of the add request.
114 .sp
115 .LP
116 The \fBldap_modify_ext_s()\fR function initiates a synchronous modify
117 operation and returns the result of the operation itself.
118 .SH ERRORS
119 .sp
120 .LP
121 \fBldap_modify_s()\fR returns an LDAP error code, either \fBLDAP_SUCCESS\fR or
122 an error. See \fBldap_error\fR(3LDAP).
123 .sp
124 .LP
125 \fBldap_modify()\fR returns \fB\(mi1\fR in case of trouble, setting the
126 \fBerror\fR field of \fIld\fR.
127 .SH ATTRIBUTES
128 .sp
129 .LP
130 See \fBattributes\fR(5) for a description of the following attributes:
131 .sp
133 .sp
134 .TS
135 box;
136 c | c
137 l | l .
138 ATTRIBUTE TYPE ATTRIBUTE VALUE
139 Interface Stability Evolving
140 .TE
142 .SH SEE ALSO
143 .sp
144 .LP
145 \fBldap\fR(3LDAP), \fBldap_add\fR(3LDAP), \fBldap_error\fR(3LDAP),
146 \fBldap_get_option\fR(3LDAP), \fBattributes\fR(5)