'\" te
.\" Copyright (c) 1990, Regents of the University of Michigan.  All Rights Reserved.
.\" Portions Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
.TH ldap_modify 3LDAP "23 Aug 2011" "SunOS 5.11" "LDAP Library Functions"
.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
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/library
_
Interface StabilityCommitted
.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)