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 07a19b1088dd3e2d3cf209eec849a537709c0ad7..ad43d0d0d49d3f32ea25791770378746ab451d06 100644 (file)
--- a/doc/man/man3/lber-encode.3
+++ b/doc/man/man3/lber-encode.3
@@ -1,9 +1,9 @@
 .TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
 .TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$

-.\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.

 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
 .SH NAME
 .\" 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
 .SH LIBRARY
 OpenLDAP LBER (liblber, -llber)
 .SH SYNOPSIS


@@ -13,6 +13,8 @@ OpenLDAP LBER (liblber, -llber)
 .LP
 .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
 .LP
 .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 ");"
 .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,13 +58,13 @@ are
 to allocate a BER element for encoding,
 .BR ber_printf ()
 to do the actual encoding, and
 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
 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 ()
 .LP
 The
 .BR ber_alloc_t ()


@@ -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
 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 ()
 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
 .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 ()
 .LP
 The
 .BR ber_printf ()


@@ -244,20 +260,20 @@ can be achieved like so:
       ber = ber_alloc_t( LBER_USE_DER );
 
       if ( ber == NULL ) {
       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 );
 
       }
 
       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
               /* 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
 .LP
 .SH NOTES
 .LP


@@ -269,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
 .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/).
 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.  
 is derived from University of Michigan LDAP 3.3 Release.