git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_add.3

   1 .TH LDAP_ADD 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2004 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_add, ldap_add_s, ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .B #include <ldap.h>
  12 .sp
  13 .BI "int ldap_add(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[]);"
  14 .sp
  15 .BI "int ldap_add_s(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[]);"
  16 .sp
  17 .BI "int ldap_add_ext(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[],"
  18 .RS
  19 .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[], int *" msgidp ");"
  20 .RE
  21 .sp
  22 .BI "int ldap_add_ext_s(LDAP *" ld ", const char *" dn ", LDAPMod *" attrs "[],"
  23 .RS
  24 .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]);"
  25 .RE
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .B ldap_add_s()
  30 routine is used to perform an LDAP add operation.
  31 It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a
  32 null-terminated array of the entry's attributes.  The LDAPMod structure
  33 is used to represent attributes, with the \fImod_type\fP and
  34 \fImod_values\fP fields being used as described under
  35 .BR ldap_modify (3),
  36 and the \fIldap_op\fP field being used only if you need to specify
  37 the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero.
  38 .LP
  39 Note that all entries except that
  40 specified by the last component in the given DN must already exist.
  41 .B ldap_add_s()
  42 returns an LDAP error code indicating success or failure
  43 of the operation.  See
  44 .BR ldap_error (3)
  45 for more details.
  46 .LP
  47 The
  48 .B ldap_add()
  49 routine works just like
  50 .BR ldap_add_s() ,
  51 but it is asynchronous.  It returns the message id of the request it
  52 initiated.  The result of this operation can be obtained by calling
  53 .BR ldap_result (3).
  54 .LP
  55 The
  56 .B ldap_add_ext()
  57 routine allows server and client controls to be specified to extend
  58 the add request. This routine is asynchronous like
  59 .BR ldap_add() ,
  60 but its return value is an LDAP error code.  It stores the message id
  61 of the request in the integer pointed to
  62 by
  63 .IR msgidp .
  64 .LP
  65 The
  66 .B ldap_add_ext_s()
  67 routine is the synchronous version of
  68 .BR ldap_add_ext() .
  69 It also returns an LDAP error code indicating success or failure
  70 of the operation.
  71 .SH ERRORS
  72 .B ldap_add()
  73 returns -1 in case of error initiating the request, and
  74 will set the \fIld_errno\fP field in the \fIld\fP parameter
  75 to indicate the error.
  76 .B ldap_add_s()
  77 will return an LDAP error code
  78 directly (LDAP_SUCCESS if everything went ok, some error otherwise).
  79 .B ldap_add_ext()
  80 and
  81 .B ldap_add_ext_s()
  82 also directly return LDAP error codes.
  83 .SH SEE ALSO
  84 .BR ldap (3),
  85 .BR ldap_modify (3)
  86 .SH ACKNOWLEDGEMENTS
  87 .B OpenLDAP
  88 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
  89 .B OpenLDAP
  90 is derived from University of Michigan LDAP 3.3 Release.