improve timeout support (ITS#4157, ITS#4663); manpage cleanup

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

diff --git a/doc/man/man3/lber-encode.3 b/doc/man/man3/lber-encode.3
index 40d617c79ae90f947bfc45ae1c421e858cbf8485..ad43d0d0d49d3f32ea25791770378746ab451d06 100644 (file)
--- a/doc/man/man3/lber-encode.3
+++ b/doc/man/man3/lber-encode.3
@@ -1,9 +1,11 @@
 .TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
-.\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2006 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 \- LBER simplified Basic Encoding Rules library routines for encoding
+.SH LIBRARY
+OpenLDAP LBER (liblber, -llber)
 .SH SYNOPSIS
 .B #include <lber.h>
 .LP
@@ -11,6 +13,8 @@ ber_alloc_t, ber_flush, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring,
 .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 ");"
@@ -54,13 +58,13 @@ 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 ()
 provides.  In
 general, these routines return the length of the element encoded, or
-LBER_ERROR if an error occurred.
+-1 if an error occurred.
 .LP
 The
 .BR ber_alloc_t ()
@@ -68,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 ()
@@ -76,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 ()
@@ -242,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 == LBER_ERROR ) {
+      if( rc == -1 ) {
               /* error */
       } else {
               /* success */
       }
 .fi
 .SH ERRORS
-If an error occurs during encoding, generally these routines return LBER_ERROR.
+If an error occurs during encoding, generally these routines return -1.
 .LP
 .SH NOTES
 .LP
@@ -267,7 +285,7 @@ The return values for all of these functions are declared in the
 .BR lber-sockbuf (3),
 .BR lber-types (3)
 .SH ACKNOWLEDGEMENTS
-.B     OpenLDAP
+.B OpenLDAP
 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B     OpenLDAP
+.B OpenLDAP
 is derived from University of Michigan LDAP 3.3 Release.