Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 357 insertions, 0 deletions

diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3
new file mode 100644
index 0000000..97d4932
--- /dev/null
+++ b/doc/man/man3/lber-decode.3
@@ -0,0 +1,357 @@
+.TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.SH NAME
+ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding
+.SH LIBRARY
+OpenLDAP LBER (liblber, \-llber)
+.SH SYNOPSIS
+.B #include <lber.h>
+.LP
+.BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
+.LP
+.BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
+.LP
+.BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
+.LP
+.BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
+.LP
+.BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
+.LP
+.BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
+.LP
+.BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
+.LP
+.BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
+.LP
+.BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
+.LP
+.BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
+.LP
+.BI "ber_tag_t ber_get_null(BerElement *" ber ");"
+.LP
+.BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
+.LP
+.BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
+.LP
+.BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
+.LP
+.BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
+.SH DESCRIPTION
+.LP
+These routines provide a subroutine interface to a simplified
+implementation of the Basic Encoding Rules of ASN.1.  The version
+of BER these routines support is the one defined for the LDAP
+protocol.  The encoding rules are the same as BER, except that 
+only definite form lengths are used, and bitstrings and octet strings
+are always encoded in primitive form.  This man page
+describes the decoding routines in the lber library.  See
+.BR lber-encode (3)
+for details on the corresponding encoding routines.
+Consult
+.BR lber-types (3)
+for information about types, allocators, and deallocators.
+.LP
+Normally, the only routines that need to be called by an application
+are
+.BR ber_get_next ()
+to get the next BER element and
+.BR ber_scanf ()
+to do the actual decoding.  In some cases,
+.BR ber_peek_tag ()
+may also need to be called in normal usage.  The other routines are
+provided for those applications that need more control than
+.BR ber_scanf ()
+provides.  In
+general, these routines return the tag of the element decoded, or
+LBER_ERROR if an error occurred.
+.LP
+The
+.BR ber_get_next ()
+routine is used to read the next BER element from the given Sockbuf,
+\fIsb\fP.  It strips off and returns the leading tag, strips off and
+returns the length of the entire element in \fIlen\fP, and sets up
+\fIber\fP for subsequent calls to 
+.BR ber_scanf ()
+et al to decode the element. See
+.BR lber-sockbuf (3)
+for details of the Sockbuf implementation of the \fIsb\fP parameter.
+.LP
+The
+.BR ber_scanf ()
+routine is used to decode a BER element in much the same way that
+.BR scanf (3)
+works.  It reads from \fIber\fP, a pointer to a BerElement
+such as returned by
+.BR ber_get_next (),
+interprets the bytes according to the format string \fIfmt\fP, and stores the
+results in its additional arguments.  The format string contains
+conversion specifications which are used to direct the interpretation
+of the BER element.  The format string can contain the following
+characters.
+.RS
+.LP
+.TP 3
+.B a
+Octet string.  A char ** should be supplied.  Memory is allocated,
+filled with the contents of the octet string, null-terminated, and
+returned in the parameter.  The caller should free the returned
+string using
+.BR ber_memfree ().
+.TP
+.B A
+Octet string.  A variant of "\fBa\fP".  A char ** should be supplied.
+Memory is allocated, filled with the contents of the octet string, 
+null-terminated, and returned in the parameter, unless a zero-length
+string would result; in that case, the arg is set to NULL.
+The caller should free the returned string using
+.BR ber_memfree ().
+.TP
+.B s
+Octet string.  A char * buffer should be supplied, followed by a pointer to a
+ber_len_t initialized to the size of the buffer.  Upon return, the
+null-terminated octet string is put into the buffer, and the
+ber_len_t is set to the actual size of the octet string.
+.TP
+.B O
+Octet string.  A struct ber_val ** should be supplied, which upon
+return points to a dynamically allocated struct berval
+containing the octet string and its length.
+The caller should free the returned structure using
+.BR ber_bvfree ().
+.TP
+.B o
+Octet string.  A struct ber_val * should be supplied, which upon
+return contains the dynamically allocated
+octet string and its length.  The caller should free the returned octet
+string using
+.BR ber_memfree ().
+.TP
+.B m
+Octet string.  A struct ber_val * should be supplied, which upon return
+contains the octet string and its length.  The string resides in memory
+assigned to the BerElement, and must not be freed by the caller.
+.TP
+.B b
+Boolean.  A pointer to a ber_int_t should be supplied.
+.TP
+.B e
+Enumeration.  A pointer to a ber_int_t should be supplied.
+.TP
+.B i
+Integer.  A pointer to a ber_int_t should be supplied.
+.TP
+.B B
+Bitstring.  A char ** should be supplied which will point to the
+dynamically allocated
+bits, followed by a ber_len_t *, which will point to the length
+(in bits) of the bitstring returned.
+.TP
+.B n
+Null.  No parameter is required.  The element is simply skipped if
+it is recognized.
+.TP
+.B v
+Sequence of octet strings.  A char *** should be supplied, which upon
+return points to a dynamically allocated null-terminated array of char *'s
+containing the octet strings.  NULL is returned if the sequence is empty.
+The caller should free the returned array and octet strings using
+.BR ber_memvfree ().
+.TP
+.B V
+Sequence of octet strings with lengths.
+A struct berval *** should be supplied, which upon
+return points to a dynamically allocated null-terminated array of
+struct berval *'s
+containing the octet strings and their lengths.
+NULL is returned if the sequence is empty.  
+The caller should free the returned structures using
+.BR ber_bvecfree ().
+.TP
+.B W
+Sequence of octet strings with lengths.
+A BerVarray * should be supplied, which upon
+return points to a dynamically allocated array of
+struct berval's
+containing the octet strings and their lengths. The array is terminated
+by a struct berval with a NULL bv_val string pointer.
+NULL is returned if the sequence is empty.  
+The caller should free the returned structures using
+.BR ber_bvarray_free ().
+.TP
+.B M
+Sequence of octet strings with lengths.  This is a generalized form
+of the previous three formats.
+A void ** (ptr) should be supplied, followed by a ber_len_t * (len)
+and a ber_len_t (off).
+Upon return (ptr) will point to a dynamically allocated array
+whose elements are all of size (*len).  A struct berval will be filled
+starting at offset (off) in each element.  The strings in each struct
+berval reside in memory assigned to the BerElement and must not be
+freed by the caller.  The array is terminated by a struct berval
+with a NULL bv_val string pointer.  NULL is returned if the sequence
+is empty.  The number of elements in the array is also stored
+in (*len) on return.  The caller should free the returned array using
+.BR ber_memfree ().
+.TP
+.B l
+Length of the next element.  A pointer to a ber_len_t should be supplied.
+.TP
+.B t
+Tag of the next element.  A pointer to a ber_tag_t should be supplied.
+.TP
+.B T
+Skip element and return its tag.  A pointer to a ber_tag_t should be supplied.
+.TP
+.B x
+Skip element.  The next element is skipped.
+.TP
+.B {
+Begin sequence.  No parameter is required.  The initial sequence tag
+and length are skipped.
+.TP
+.B }
+End sequence.  No parameter is required and no action is taken.
+.TP
+.B [
+Begin set.  No parameter is required.  The initial set tag
+and length are skipped.
+.TP
+.B ]
+End set.  No parameter is required and no action is taken.
+.RE
+.LP
+The
+.BR ber_get_int ()
+routine tries to interpret the next element as an integer,
+returning the result in \fInum\fP.  The tag of whatever it finds is returned
+on success, LBER_ERROR (\-1) on failure.
+.LP
+The
+.BR ber_get_stringb ()
+routine is used to read an octet string into a
+preallocated buffer.  The \fIlen\fP parameter should be initialized to
+the size of the buffer, and will contain the length of the octet string
+read upon return.  The buffer should be big enough to take the octet
+string value plus a terminating NULL byte.
+.LP
+The
+.BR ber_get_stringa ()
+routine is used to dynamically allocate space into
+which an octet string is read.
+The caller should free the returned string using
+.BR ber_memfree().
+.LP
+The
+.BR ber_get_stringal ()
+routine is used to dynamically allocate space
+into which an octet string and its length are read.  It takes a
+struct berval **, and returns the result in this parameter.
+The caller should free the returned structure using
+.BR ber_bvfree().
+.LP
+The
+.BR ber_get_stringbv ()
+routine is used to read an octet string and its length into the 
+provided struct berval *. If the \fIalloc\fP parameter is zero, the string
+will reside in memory assigned to the BerElement, and must not be freed
+by the caller. If the \fIalloc\fP parameter is non-zero, the string will be
+copied into dynamically allocated space which should be returned using
+.BR ber_memfree ().
+.LP
+The
+.BR ber_get_null ()
+routine is used to read a NULL element.  It returns
+the tag of the element it skips over.
+.LP
+The
+.BR ber_get_boolean ()
+routine is used to read a boolean value.  It is called the same way that
+.BR ber_get_int ()
+is called.
+.LP
+The
+.BR ber_get_enum ()
+routine is used to read a enumeration value.  It is called the same way that
+.BR ber_get_int ()
+is called.
+.LP
+The
+.BR ber_get_bitstringa ()
+routine is used to read a bitstring value.  It
+takes a char ** which will hold the dynamically allocated bits, followed by an
+ber_len_t *, which will point to the length (in bits) of the bitstring returned.
+The caller should free the returned string using
+.BR ber_memfree ().
+.LP
+The
+.BR ber_first_element ()
+routine is used to return the tag and length
+of the first element in a set or sequence.  It also returns in \fIcookie\fP
+a magic cookie parameter that should be passed to subsequent calls to
+ber_next_element(), which returns similar information.
+.SH EXAMPLES
+Assume the variable \fIber\fP contains a lightweight BER encoding of
+the following ASN.1 object:
+.LP
+.nf
+      AlmostASearchRequest := SEQUENCE {
+          baseObject      DistinguishedName,
+          scope           ENUMERATED {
+              baseObject    (0),
+              singleLevel   (1),
+              wholeSubtree  (2)
+          },
+          derefAliases    ENUMERATED {
+              neverDerefaliases   (0),
+              derefInSearching    (1),
+              derefFindingBaseObj (2),
+              alwaysDerefAliases  (3)
+          },
+          sizelimit       INTEGER (0 .. 65535),
+          timelimit       INTEGER (0 .. 65535),
+          attrsOnly       BOOLEAN,
+          attributes      SEQUENCE OF AttributeType
+      }
+.fi
+.LP
+The element can be decoded using
+.BR ber_scanf ()
+as follows.
+.LP
+.nf
+      ber_int_t    scope, deref, size, time, attrsonly;
+      char   *dn, **attrs;
+      ber_tag_t tag;
+
+      tag = ber_scanf( ber, "{aeeiib{v}}",
+          &dn, &scope, &deref,
+          &size, &time, &attrsonly, &attrs );
+
+      if( tag == LBER_ERROR ) {
+              /* error */
+      } else {
+              /* success */
+      }
+
+      ber_memfree( dn );
+      ber_memvfree( attrs );
+.fi
+.SH ERRORS
+If an error occurs during decoding, generally these routines return
+LBER_ERROR ((ber_tag_t)\-1).
+.LP
+.SH NOTES
+.LP
+The return values for all of these functions are declared in the
+.B <lber.h>
+header file.  Some routines may dynamically allocate memory
+which must be freed by the caller using supplied deallocation routines.
+.SH SEE ALSO
+.BR lber-encode (3),
+.BR lber-memory (3),
+.BR lber-sockbuf (3),
+.BR lber-types (3)
+.SH ACKNOWLEDGEMENTS
+.so ../Project