Merge remote-tracking branch 'origin/mdb.master'

[openldap] / doc / man / man3 / lber-encode.3

diff --git a/doc/man/man3/lber-encode.3 b/doc/man/man3/lber-encode.3
index c9a11150748a606926be585de2232fbc6c6724df..bdbcbd35ab5a1bb302470f2411c3295765ed1a0d 100644 (file)
--- a/doc/man/man3/lber-encode.3
+++ b/doc/man/man3/lber-encode.3
@@ -1,11 +1,11 @@
 .TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
-.\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2013 The OpenLDAP Foundation All Rights Reserved.
 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
-ber_alloc_t, ber_flush, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- LBER simplified Basic Encoding Rules library routines for encoding
+ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding
 .SH LIBRARY
-OpenLDAP LBER (liblber, -llber)
+OpenLDAP LBER (liblber, \-llber)
 .SH SYNOPSIS
 .B #include <lber.h>
 .LP
@@ -13,6 +13,8 @@ OpenLDAP LBER (liblber, -llber)
 .LP
 .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
 .LP
+.BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
+.LP
 .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);"
 .LP
 .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
@@ -56,7 +58,7 @@ are
 to allocate a BER element for encoding,
 .BR ber_printf ()
 to do the actual encoding, and
-.BR ber_flush ()
+.BR ber_flush2 ()
 to actually write the element.  The other routines are provided for those
 applications that need more control than
 .BR ber_printf ()
@@ -70,7 +72,7 @@ routine is used to allocate a new BER element.  It
 should be called with an argument of LBER_USE_DER.
 .LP
 The
-.BR ber_flush ()
+.BR ber_flush2 ()
 routine is used to actually write the element to a socket
 (or file) descriptor, once it has been fully encoded (using
 .BR ber_printf ()
@@ -78,7 +80,21 @@ and friends).  See
 .BR lber-sockbuf (3)
 for more details on the Sockbuf implementation of the \fIsb\fP parameter.
 If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will
-be freed after its contents have been flushed.
+be freed.
+If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed
+when successfully flushed, otherwise it is left intact;
+if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed
+when an error occurs, otherwise it is left intact;
+if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway.
+This function differs from the original
+.BR ber_flush (3)
+function, whose behavior corresponds to that indicated
+for \fILBER_FLUSH_FREE_ON_SUCCESS\fP.
+Note that in the future, the behavior of
+.BR ber_flush (3)
+with \fIfreeit\fP non-zero might change into that of
+.BR ber_flush2 (3)
+with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP.
 .LP
 The
 .BR ber_printf ()
@@ -244,20 +260,20 @@ can be achieved like so:
       ber = ber_alloc_t( LBER_USE_DER );
 
       if ( ber == NULL ) {
-               /* error */
+              /* error */
       }
 
       rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
           size, time, attrsonly, attrs );
 
-      if( rc == -1 ) {
+      if( rc == \-1 ) {
               /* error */
       } else {
               /* success */
       }
 .fi
 .SH ERRORS
-If an error occurs during encoding, generally these routines return -1.
+If an error occurs during encoding, generally these routines return \-1.
 .LP
 .SH NOTES
 .LP
@@ -269,7 +285,4 @@ The return values for all of these functions are declared in the
 .BR lber-sockbuf (3),
 .BR lber-types (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.  
+.so ../Project