'\" te
.\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH LDAP_MODIFY 3LDAP "Jan 28, 2002"
.SH NAME
ldap_modify, ldap_modify_s, ldap_mods_free, ldap_modify_ext, ldap_modify_ext_s
\- LDAP entry modification functions
.SH SYNOPSIS
.LP
.nf
cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
#include <lber.h>
#include <ldap.h>

\fBint\fR \fBldap_modify\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*mods\fR[]);
.fi

.LP
.nf
\fBint\fR \fBldap_modify_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*mods\fR[]);
.fi

.LP
.nf
\fBvoid\fR \fBldap_mods_free\fR(\fBLDAPMod\fR \fI**mods\fR, \fBint\fR \fIfreemods\fR);
.fi

.LP
.nf
\fBint\fR \fBldap_modify_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**mods\fR,
     \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR, \fBint\fR \fI*msgidp\fR);
.fi

.LP
.nf
\fBint\fR \fBldap_modify_ext_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**mods\fR,
     \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The function \fBldap_modify_s()\fR is used to perform an LDAP modify operation.
\fIdn\fR is the DN of the entry to modify, and \fImods\fR is a null-terminated
array of modifications to make to the entry.   Each element of the \fImods\fR
array is a pointer to an  \fBLDAPMod\fR structure, which is defined below.
.sp
.in +2
.nf
	typedef struct ldapmod {
	    int mod_op;
	    char *mod_type;
	    union {
		char **modv_strvals;
		struct berval **modv_bvals;
	      } mod_vals;
	    } LDAPMod;
	#define mod_values mod_vals.modv_strvals
	#define mod_bvalues mod_vals.modv_bvals
.fi
.in -2

.sp
.LP
The \fImod_op\fR field is used to specify the type of modification to perform
and should be one of  \fBLDAP_MOD_ADD\fR, \fBLDAP_MOD_DELETE\fR, or
\fBLDAP_MOD_REPLACE\fR. The \fImod_type\fR and \fImod_values\fR fields specify
the attribute type to modify and a null-terminated array of values to add,
delete, or replace respectively.
.sp
.LP
If you need to specify a non-string value (for example, to add a photo or audio
attribute value), you should set \fImod_op\fR to the logical OR of the
operation as above (for example,  \fBLDAP_MOD_REPLACE\fR) and the constant
\fBLDAP_MOD_BVALUES\fR. In this case, \fImod_bvalues\fR should be used instead
of \fImod_values\fR, and it should point to a null-terminated array of struct
bervals, as defined in  <\fBlber.h\fR>.
.sp
.LP
For  \fBLDAP_MOD_ADD\fR modifications, the given values are added to the entry,
creating the attribute if necessary.  For  \fBLDAP_MOD_DELETE\fR modifications,
the given values are deleted from the entry, removing the attribute if no
values remain.  If the entire attribute is to be deleted, the \fImod_values\fR
field should be set to NULL.  For  \fBLDAP_MOD_REPLACE\fR modifications, the
attribute will have the listed values after the modification, having been
created if necessary.  All modifications are performed in the order in which
they are listed.
.sp
.LP
\fBldap_modify_s()\fR returns the LDAP error code resulting from the modify
operation.
.sp
.LP
The \fBldap_modify()\fR operation works the same way as \fBldap_modify_s()\fR,
except that it is asynchronous, returning the message id of the request it
initiates, or  \fB\(mi1\fR on error.  The result of the operation can be
obtained by calling \fBldap_result\fR(3LDAP).
.sp
.LP
\fBldap_mods_free()\fR can be used to free each element of a null-terminated
array of mod structures.  If \fIfreemods\fR is non-zero, the \fImods\fR pointer
itself is freed as well.
.sp
.LP
The  \fBldap_modify_ext()\fR function initiates an asynchronous modify
operation and returns  \fBLDAP_SUCCESS\fR if the request was successfully sent
to the server, or else it returns a LDAP error code if not. See
\fBldap_error\fR(3LDAP). If successful,  \fBldap_modify_ext()\fR places the
message id of the request in  \fI*msgidp\fR. A subsequent call to
\fBldap_result\fR(3LDAP), can be used to obtain the result of the add request.
.sp
.LP
The  \fBldap_modify_ext_s()\fR function initiates a synchronous modify
operation and returns the result of the operation itself.
.SH ERRORS
.sp
.LP
\fBldap_modify_s()\fR returns an LDAP error code, either  \fBLDAP_SUCCESS\fR or
an error. See \fBldap_error\fR(3LDAP).
.sp
.LP
\fBldap_modify()\fR returns  \fB\(mi1\fR in case of trouble, setting the
\fBerror\fR field of \fIld\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBldap\fR(3LDAP), \fBldap_add\fR(3LDAP), \fBldap_error\fR(3LDAP),
\fBldap_get_option\fR(3LDAP), \fBattributes\fR(5)