.TH LDAP_ADD 3 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_add.3,v 1.15.2.4 2007/01/02 21:43:44 kurt Exp $
.\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
ldap_add, ldap_add_s, ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation
.SH LIBRARY
OpenLDAP LDAP (libldap, -lldap)
.SH SYNOPSIS
.nf
.B #include <ldap.h>
.sp
.BI "int ldap_add(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[]);"
.sp
.BI "int ldap_add_s(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[]);"
.sp
.BI "int ldap_add_ext(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[],"
.RS
.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[], int *" msgidp ");"
.RE
.sp
.BI "int ldap_add_ext_s(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[],"
.RS
.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]);"
.RE
.fi
.SH DESCRIPTION
The
.B ldap_add_s()
routine is used to perform an LDAP add operation.
It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a
null-terminated array of the entry's attributes.  The LDAPMod structure
is used to represent attributes, with the \fImod_type\fP and
\fImod_values\fP fields being used as described under
.BR ldap_modify (3),
and the \fIldap_op\fP field being used only if you need to specify
the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero.
.LP
Note that all entries except that
specified by the last component in the given DN must already exist.
.B ldap_add_s()
returns an LDAP error code indicating success or failure
of the operation.  See
.BR ldap_error (3)
for more details.
.LP
The
.B ldap_add()
routine works just like
.BR ldap_add_s() ,
but it is asynchronous.  It returns the message id of the request it
initiated.  The result of this operation can be obtained by calling
.BR ldap_result (3).
.LP
The
.B ldap_add_ext()
routine allows server and client controls to be specified to extend
the add request. This routine is asynchronous like
.BR ldap_add() ,
but its return value is an LDAP error code.  It stores the message id
of the request in the integer pointed to
by
.IR msgidp .
.LP
The
.B ldap_add_ext_s()
routine is the synchronous version of
.BR ldap_add_ext() .
It also returns an LDAP error code indicating success or failure
of the operation.
.SH ERRORS
.B ldap_add()
returns -1 in case of error initiating the request, and
will set the \fIld_errno\fP field in the \fIld\fP parameter
to indicate the error.
.B ldap_add_s()
will return an LDAP error code
directly (LDAP_SUCCESS if everything went ok, some error otherwise).
.B ldap_add_ext()
and
.B ldap_add_ext_s()
also directly return LDAP error codes.
.SH SEE ALSO
.BR ldap (3),
.BR ldap_modify (3)
.SH ACKNOWLEDGEMENTS
.B OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.