mirror of
https://git.openldap.org/openldap/openldap.git
synced 2025-12-25 17:19:43 -05:00
Update LBER man pages to latest API.
Need to add lber-types(3) to document BER types, allocation, and deallocation. May need to add additional pages to document other new features.
This commit is contained in:
Kurt Zeilenga
parent
865e24a8ac
commit
40d749ed6b
2 changed files with 137 additions and 164 deletions
|
|
@ -1,4 +1,4 @@
|
|||
.TH LBER_DECODE 3 "22 September 1998" "OpenLDAP LDVERSION"
|
||||
.TH LBER_DECODE 3 "12 May 2000" "OpenLDAP LDVERSION"
|
||||
.\" $OpenLDAP$
|
||||
.\" Copyright 1998-1999 The OpenLDAP Foundation All Rights Reserved.
|
||||
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
||||
|
|
@ -13,144 +13,109 @@ ber_get_next, ber_skiptag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_stringb
|
|||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
typedef struct berelement BerElement;
|
||||
ber_tag_t ber_get_next(
|
||||
Sockbuf *sb,
|
||||
ber_len_t \(**len,
|
||||
BerElement \(**ber);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
typedef struct sockbuf Sockbuf;
|
||||
ber_tag_t ber_skip_tag(
|
||||
BerElement \(**ber,
|
||||
ber_len_t long \(**len);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
typedef struct berval {
|
||||
unsigned long bv_len;
|
||||
char *bv_val;
|
||||
};
|
||||
ber_tag_t ber_peek_tag(
|
||||
BerElement \(**ber,
|
||||
ber_len_t \(**len);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_next(sb, len, ber)
|
||||
Sockbuf *sb;
|
||||
unsigned long \(**len;
|
||||
BerElement \(**ber;
|
||||
ber_tag_t ber_scanf(
|
||||
BerElement \(**ber,
|
||||
const char \(**fmt, ...);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_skip_tag(ber, len)
|
||||
BerElement \(**ber;
|
||||
unsigned long \(**len;
|
||||
ber_tag_t ber_get_int(ber, num)
|
||||
BerElement \(**ber,
|
||||
ber_int_t \(**num);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_peek_tag(ber, len)
|
||||
BerElement \(**ber;
|
||||
unsigned long \(**len;
|
||||
ber_tag_t ber_get_stringb(
|
||||
BerElement \(**ber,
|
||||
char \(**buf,
|
||||
ber_len_t \(**len);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_int(ber, num)
|
||||
BerElement \(**ber;
|
||||
long \(**num;
|
||||
ber_tag_t ber_get_stringa(
|
||||
BerElement \(**ber,
|
||||
char \(***buf);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_stringb(ber, buf, len)
|
||||
BerElement \(**ber;
|
||||
char \(**buf;
|
||||
unsigned long \(**len;
|
||||
ber_tag_t ber_get_stringal(
|
||||
BerElement \(**ber,
|
||||
struct berval \(***bv);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_stringa(ber, buf)
|
||||
BerElement \(**ber;
|
||||
char \(***buf;
|
||||
ber_tag_t ber_get_null(
|
||||
BerElement \(**ber );
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_stringal(ber, bv)
|
||||
BerElement \(**ber;
|
||||
struct berval \(***bv;
|
||||
ber_tag_t ber_get_boolean(
|
||||
BerElement \(**ber,
|
||||
ber_int_t \(**bool);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_null(ber)
|
||||
BerElement \(**ber;
|
||||
ber_tag_t ber_get_bitstringa(
|
||||
BerElement \(**ber,
|
||||
char \(***buf,
|
||||
ber_len_t \(**blen);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_boolean(ber, bool)
|
||||
BerElement \(**ber;
|
||||
int \(**bool;
|
||||
ber_tag_t ber_first_element(
|
||||
BerElement \(**ber,
|
||||
ber_len_t \(**len,
|
||||
char \(***cookie);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_get_bitstringa(ber, buf, blen)
|
||||
BerElement \(**ber;
|
||||
char \(***buf;
|
||||
unsigned long \(**blen;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_first_element(ber, len, cookie)
|
||||
BerElement \(**ber;
|
||||
unsigned long \(**len;
|
||||
char \(***cookie;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_next_element(ber, len, cookie)
|
||||
BerElement \(**ber;
|
||||
unsigned long \(**len;
|
||||
char \(**cookie;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_scanf(ber, fmt [, arg...] )
|
||||
BerElement \(**ber;
|
||||
char \(**fmt;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_bvfree(bv)
|
||||
struct berval \(**bv;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_bvecfree(bvec)
|
||||
struct berval \(***bvec;
|
||||
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
|
||||
|
|
@ -165,6 +130,7 @@ in the descriptions below, it refers to the tag, class, and primitive
|
|||
or constructed bit in the first octet of the encoding. This man page
|
||||
describes the decoding routines in the lber library. See lber-encode(3)
|
||||
for details on the corresponding encoding routines.
|
||||
Consult lber-types(3) for information about types, allocators, and deallocators.
|
||||
.LP
|
||||
Normally, the only routines that need be called by an application
|
||||
are ber_get_next() to get the next BER element and ber_scanf()
|
||||
|
|
@ -200,29 +166,30 @@ characters.
|
|||
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 ber_val using ber_memfree();
|
||||
.TP
|
||||
.SM s
|
||||
Octet string. A char * buffer should be supplied, followed by a pointer
|
||||
to an integer initialized to the size of the buffer. Upon return, the
|
||||
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 integer is
|
||||
set to the actual size of the octet string.
|
||||
.TP
|
||||
.SM 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. ber_bvfree() can be called to free the dynamically
|
||||
allocated memory.
|
||||
and its length.
|
||||
The caller should free the returned structure using ber_bvfree();
|
||||
.TP
|
||||
.SM b
|
||||
Boolean. A pointer to an integer should be supplied.
|
||||
Boolean. A pointer to a ber_int_t should be supplied.
|
||||
.TP
|
||||
.SM i
|
||||
Integer. A pointer to an integer should be supplied.
|
||||
Integer. A pointer to a ber_int_t should be supplied.
|
||||
.TP
|
||||
.SM B
|
||||
Bitstring. A char ** should be supplied which will point to the
|
||||
dynamically allocated
|
||||
bits, followed by an unsigned long *, which will point to the length
|
||||
bits, followed by an ber_len_t *, which will point to the length
|
||||
(in bits) of the bitstring returned.
|
||||
.TP
|
||||
.SM n
|
||||
|
|
@ -240,8 +207,8 @@ 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. ber_bvecfree() can be called
|
||||
to free the dynamically allocated memory.
|
||||
NULL is returned if the sequence is empty.
|
||||
The caller should free the returned structures using ber_bvecfree();
|
||||
.TP
|
||||
.SM x
|
||||
Skip element. The next element is skipped.
|
||||
|
|
@ -263,7 +230,7 @@ End set. No parameter is required and no action is taken.
|
|||
.LP
|
||||
The 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, -1 on failure.
|
||||
on success, LBER_ERROR (\-1) on failure.
|
||||
.LP
|
||||
The ber_get_stringb() routine is used to read an octet string into a
|
||||
preallocated buffer. The \fIlen\fP parameter should be initialized to
|
||||
|
|
@ -272,12 +239,13 @@ read upon return. The buffer should be big enough to take the octet
|
|||
string value plus a terminating NULL byte.
|
||||
.LP
|
||||
The ber_get_stringa() routine is used to dynamically allocate space into
|
||||
which an octet
|
||||
string is read.
|
||||
which an octet string is read.
|
||||
The caller should free the returned string using ber_memfree();
|
||||
.LP
|
||||
The 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 ber_bvfree();
|
||||
.LP
|
||||
The ber_get_null() routine is used to read a NULL element. It returns
|
||||
the tag of the element it skips over.
|
||||
|
|
@ -289,6 +257,7 @@ The 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
|
||||
unsigned long *, which will point to the length (in bits) of the
|
||||
bitstring returned.
|
||||
The caller should free the returned string using ber_memfree();
|
||||
.LP
|
||||
The 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
|
||||
|
|
@ -322,17 +291,23 @@ the following ASN.1 object:
|
|||
The element can be decoded using ber_scanf() as follows.
|
||||
.LP
|
||||
.nf
|
||||
int scope, ali, size, time, attrsonly;
|
||||
ber_int_t scope, ali, size, time, attrsonly;
|
||||
char *dn, **attrs;
|
||||
ber_tag_t tag;
|
||||
|
||||
if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali,
|
||||
&size, &time, &attrsonly, &attrs ) == -1 )
|
||||
tag = ber_scanf( ber, "{aiiiib{v}}",
|
||||
&dn, &scope, &ali,
|
||||
&size, &time, &attrsonly, &attrs );
|
||||
|
||||
if( tag == LBER_ERROR ) {
|
||||
/* error */
|
||||
else
|
||||
} else {
|
||||
/* success */
|
||||
}
|
||||
.fi
|
||||
.SH ERRORS
|
||||
If an error occurs during decoding, generally these routines return -1.
|
||||
If an error occurs during decoding, generally these routines return
|
||||
LBER_ERROR (\-1).
|
||||
.LP
|
||||
.SH NOTES
|
||||
.LP
|
||||
|
|
@ -342,6 +317,7 @@ 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-types (3)
|
||||
.BR ldap-parse (3)
|
||||
.BR ldap-sync (3)
|
||||
.BR ldap-async (3)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.TH LBER_ENCODE 3 "22 September 1998" "OpenLDAP LDVERSION"
|
||||
.TH LBER_ENCODE 3 "12 May 2000" "OpenLDAP LDVERSION"
|
||||
.\" $OpenLDAP$
|
||||
.\" Copyright 1998-1999 The OpenLDAP Foundation All Rights Reserved.
|
||||
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
||||
|
|
@ -13,121 +13,109 @@ ber_alloc, ber_flush, ber_printf, ber_put_int, ber_put_ostring, ber_put_string,
|
|||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
typedef struct berelement BerElement;
|
||||
BerElement *ber_alloc_t( int options );
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
typedef struct sockbuf Sockbuf;
|
||||
int ber_flush(
|
||||
Sockbuf *sb,
|
||||
BerElement *ber,
|
||||
int freeit);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
BerElement *ber_alloc()
|
||||
int ber_printf(
|
||||
BerElement *ber,
|
||||
const char \(**fmt, ...);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_flush(sb, ber, freeit)
|
||||
Sockbuf *sb;
|
||||
BerElement *ber;
|
||||
int freeit;
|
||||
int ber_put_int(
|
||||
BerElement *ber,
|
||||
ber_int_t num,
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_printf(ber, fmt [, arg... ] )
|
||||
BerElement *ber;
|
||||
char \(**fmt;
|
||||
int ber_put_ostring(
|
||||
BerElement *ber,
|
||||
const char \(**str,
|
||||
ber_len_t long len,
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_int(ber, num, tag)
|
||||
BerElement *ber;
|
||||
long num;
|
||||
char tag;
|
||||
int ber_put_string(
|
||||
BerElement *ber,
|
||||
const char \(**str,
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_ostring(ber, str, len, tag)
|
||||
BerElement *ber;
|
||||
char \(**str;
|
||||
unsigned long len;
|
||||
char tag;
|
||||
int ber_put_null(
|
||||
BerElement *ber;
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_string(ber, str, tag)
|
||||
BerElement *ber;
|
||||
char \(**str;
|
||||
char tag;
|
||||
int ber_put_boolean(
|
||||
BerElement *ber;
|
||||
ber_int_t bool;
|
||||
ber_tag_t tag;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_null(ber, tag)
|
||||
BerElement *ber;
|
||||
char tag;
|
||||
int ber_put_bitstring(
|
||||
BerElement *ber,
|
||||
const char *str,
|
||||
ber_len_t blen,
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_boolean(ber, bool, tag)
|
||||
BerElement *ber;
|
||||
int bool;
|
||||
char tag;
|
||||
int ber_start_seq(
|
||||
BerElement *ber,
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_bitstring(ber, str, blen, tag)
|
||||
BerElement *ber;
|
||||
char *str;
|
||||
int blen;
|
||||
char tag;
|
||||
int ber_start_set(
|
||||
BerElement *ber,
|
||||
ber_tag_t tag);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_start_seq(ber, tag)
|
||||
BerElement *ber;
|
||||
char tag;
|
||||
int ber_put_seq(
|
||||
BerElement *ber);
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_start_set(ber, tag)
|
||||
BerElement *ber;
|
||||
char tag;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_seq(ber)
|
||||
BerElement *ber;
|
||||
.ft
|
||||
.fi
|
||||
.LP
|
||||
.nf
|
||||
.ft B
|
||||
ber_put_set(ber)
|
||||
BerElement *ber;
|
||||
int ber_put_set(
|
||||
BerElement *ber);
|
||||
.SH DESCRIPTION
|
||||
.LP
|
||||
These routines provide a subroutine interface to a simplified
|
||||
|
|
@ -142,16 +130,17 @@ in the descriptions below, it refers to the tag, class, and primitive
|
|||
or constructed bit in the first octet of the encoding. This
|
||||
man page describes the encoding routines in the lber library. See
|
||||
lber-decode(3) for details on the corresponding decoding routines.
|
||||
Consult lber-types(3) for information about types, allocators, and deallocators.
|
||||
.LP
|
||||
Normally, the only routines that need be called by an application
|
||||
are ber_alloc() to allocate a BER element for encoding, ber_printf()
|
||||
are ber_alloc_t() to allocate a BER element for encoding, ber_printf()
|
||||
to do the actual encoding, and ber_flush() to actually write the
|
||||
element. The other routines are provided for those
|
||||
applications that need more control than ber_printf() provides. In
|
||||
general, these routines return the length of the element encoded, or
|
||||
-1 if an error occurred.
|
||||
.LP
|
||||
The ber_alloc() routine is used to allocate a new BER element. The
|
||||
The ber_alloc_t() routine is used to allocate a new BER element. The
|
||||
ber_flush() routine is used to actually write the element to a socket
|
||||
(or file) descriptor, once it has been fully encoded (using ber_printf()
|
||||
and friends). The \fIsb\fP structure contains the descriptor and a
|
||||
|
|
@ -170,11 +159,11 @@ The format string can contain the following characters:
|
|||
.LP
|
||||
.TP 3
|
||||
.SM b
|
||||
Boolean. An integer parameter should be supplied. A boolean element
|
||||
Boolean. An ber_int_t parameter should be supplied. A boolean element
|
||||
is output.
|
||||
.TP
|
||||
.SM i
|
||||
Integer. An integer parameter should be supplied. An integer element
|
||||
Integer. An ber_int_t parameter should be supplied. An integer element
|
||||
is output.
|
||||
.TP
|
||||
.SM B
|
||||
|
|
@ -194,8 +183,8 @@ Octet string. A null-terminated string is supplied. An octet string
|
|||
element is output, not including the trailing NULL octet.
|
||||
.TP
|
||||
.SM t
|
||||
Tag. An int specifying the tag to give the next element is provided.
|
||||
This works across calls.
|
||||
Tag. A ber_tag_t specifying the tag to give the next element
|
||||
is provided. This works across calls.
|
||||
.TP
|
||||
.SM v
|
||||
Several octet strings. A null-terminated array of char *'s is
|
||||
|
|
@ -271,18 +260,25 @@ the following ASN.1 object:
|
|||
can be achieved like so:
|
||||
.LP
|
||||
.nf
|
||||
int scope, ali, size, time, attrsonly;
|
||||
int rc;
|
||||
ber_int_t scope, ali, size, time, attrsonly;
|
||||
char *dn, **attrs;
|
||||
|
||||
/* ... fill in values ... */
|
||||
if ( (ber = ber_alloc()) == NULLBER )
|
||||
/* error */
|
||||
ber = ber_alloc_t( LBER_USE_DER );
|
||||
|
||||
if ( ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
|
||||
size, time, attrsonly, attrs ) == -1 )
|
||||
if ( ber == NULL ) {
|
||||
/* error */
|
||||
}
|
||||
|
||||
rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
|
||||
size, time, attrsonly, attrs );
|
||||
|
||||
if( rc == -1 ) {
|
||||
/* error */
|
||||
else
|
||||
} else {
|
||||
/* success */
|
||||
}
|
||||
.fi
|
||||
.SH ERRORS
|
||||
If an error occurs during encoding, generally these routines return -1.
|
||||
|
|
@ -292,10 +288,11 @@ If an error occurs during encoding, generally these routines return -1.
|
|||
The return values for all of these functions are declared in the
|
||||
<lber.h> header file.
|
||||
.SH SEE ALSO
|
||||
.BR lber-decode (3)
|
||||
.BR lber-types (3)
|
||||
.BR ldap-async (3)
|
||||
.BR ldap-sync (3)
|
||||
.BR ldap-parse (3)
|
||||
.BR lber-decode (3)
|
||||
.LP
|
||||
Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
|
||||
Protocol", OSI-DS-26, April 1992.
|
||||
|
|
|
|||
Loading…
Reference in a new issue