Up to Contents

Back to Comparing a Value Against an Entry

Modifying an Entry

The following routines are used to modify an existing LDAP entry. There are four variations:

           typedef struct ldapmod {
                   int             mod_op;
                   char            *mod_type;
                   union {
                           char            **modv_strvals;
                           struct berval   **modv_bvals;
                   } mod_vals;

		   /* not used by clients */
		   struct ldapmod *mod_next;
           } LDAPMod;
           #define mod_values      mod_vals.modv_strvals
           #define mod_bvalues     mod_vals.modv_bvals

           int ldap_modify_ext(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );

           int ldap_modify_ext_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls
           );

           int ldap_modify(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods
           );

           int ldap_modify_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods
           );

(The mod_next field is specific to this implementation.)

Parameters are:

ld

The session handle.

dn

The name of the entry to modify.

mods

A NULL-terminated array of modifications to make to the entry.

serverctrls

List of LDAP server controls.

clientctrls

List of client controls.

msgidp

This result parameter will be set to the message id of the request if the ldap_modify_ext() call succeeds.

The fields in the LDAPMod structure have the following meanings:

mod_op

The modification operation to perform. It should be one of LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or LDAP_MOD_REPLACE (0x02). This field also indicates the type of values included in the mod_vals union. It is logically ORed with LDAP_MOD_BVALUES (0x80) to select the mod_bvalues form. Otherwise, the mod_values form is used.

mod_type

The type of the attribute to modify.

mod_vals

The values (if any) to add, delete, or replace. Only one of the mod_values or mod_bvalues variants should be used, selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of zero-terminated strings and mod_bvalues is a NULL-terminated array of berval structures that can be used to pass binary values such as images.

For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if necessary.

For LDAP_MOD_DELETE 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 mod_vals field should be set to NULL.

For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary, or removed if the mod_vals field is NULL. All modifications are performed in the order in which they are listed.

The ldap_modify_ext() function initiates an asynchronous modify operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_modify_ext() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the modify.

Similar to ldap_modify_ext(), the ldap_modify() function initiates an asynchronous modify operation and returns the message id of the operation initiated. As for ldap_modify_ext(), a subsequent call to ldap_result(), described below, can be used to obtain the result of the modify. In case of error, ldap_modify() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about possible errors and how to interpret them.

The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 server controls and client controls.

Up to Contents

Forward to Modifying the Name of an Entry