From e9d0b98a10f2dd8692392dfa28f4dc2f9369eea7 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Sat, 13 May 2000 23:08:25 +0000 Subject: [PATCH] Update lber-encode/decode man pages Add ber_get_enum() for symmetry --- doc/man/man3/lber-decode.3 | 66 ++++++++++++++++++++++++-------- doc/man/man3/lber-decode.3.links | 1 + doc/man/man3/lber-encode.3 | 38 +++++++++++++++--- doc/man/man3/lber-encode.3.links | 3 +- doc/man/man3/ldap.3 | 4 +- include/lber.h | 5 +++ libraries/liblber/decode.c | 8 ++++ libraries/liblber/nt_err.c | 2 +- 8 files changed, 100 insertions(+), 27 deletions(-) diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3 index bf2d4525fb..70b260f2a3 100644 --- a/doc/man/man3/lber-decode.3 +++ b/doc/man/man3/lber-decode.3 @@ -3,7 +3,7 @@ .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME -ber_get_next, ber_skiptag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_stringb, ber_get_stringa, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- LBER simplified Basic Encoding Rules library routines for decoding +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_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- LBER simplified Basic Encoding Rules library routines for decoding .SH SYNOPSIS .nf .ft B @@ -46,7 +46,15 @@ ber_tag_t ber_scanf( .LP .nf .ft B -ber_tag_t ber_get_int(ber, num) +ber_tag_t ber_get_int( + BerElement \(**ber, + ber_int_t \(**num); +.ft +.fi +.LP +.nf +.ft B +ber_tag_t ber_get_enum( BerElement \(**ber, ber_int_t \(**num); .ft @@ -166,7 +174,7 @@ 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(); +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 @@ -178,11 +186,19 @@ set to the actual size of the octet string. 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 ber_bvfree(); +The caller should free the returned structure using ber_bvfree(). +.TP +.SM o +Octet string. A struct ber_val * should be supplied, which upon return +points containing the dynamically allocated octet string and its length. +The caller should free the returned octet string using ber_memfree(). .TP .SM b Boolean. A pointer to a ber_int_t should be supplied. .TP +.SM e +Enumeration. A pointer to a ber_int_t should be supplied. +.TP .SM i Integer. A pointer to a ber_int_t should be supplied. .TP @@ -200,6 +216,8 @@ it is recognized. 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 +ber_memvfree(). .TP .SM V Sequence of octet strings with lengths. @@ -208,7 +226,16 @@ 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 ber_bvecfree(); +The caller should free the returned structures using ber_bvecfree(). +.TP +.SM l +Length of the next element. A pointer to a ber_len_t should be supplied. +.TP +.SM t +Tag of the next element. A pointer to a ber_tag_t should be supplied. +.TP +.SM T +Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .SM x Skip element. The next element is skipped. @@ -240,24 +267,26 @@ 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. -The caller should free the returned string using ber_memfree(); +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(); +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. .LP -The ber_get_boolean() routine is used to read a boolean value. It is called -the same way that ber_get_int() is called. +The ber_get_boolean() routine is used to read a boolean value. +It is called the same way that ber_get_int() is called. +.LP +The ber_get_enum() routine is used to read a enumeration value. +It is called the same way that ber_get_int() is called. .LP 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(); +ber_len_t *, 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 @@ -291,12 +320,12 @@ the following ASN.1 object: The element can be decoded using ber_scanf() as follows. .LP .nf - ber_int_t scope, ali, size, time, attrsonly; + ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; - tag = ber_scanf( ber, "{aiiiib{v}}", - &dn, &scope, &ali, + tag = ber_scanf( ber, "{aeeiib{v}}", + &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { @@ -304,6 +333,9 @@ The element can be decoded using ber_scanf() as follows. } else { /* success */ } + + ber_memfree( dn ); + ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return @@ -322,8 +354,8 @@ which must be freed by the caller using supplied deallocation routines. .BR ldap-sync (3) .BR ldap-async (3) .LP -Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access -Protocol", OSI-DS-26, April 1992. +Yeong, W., Howes, T., and Hardcastle-Kille, S., +"Lightweight Directory Access Protocol", OSI-DS-26, April 1992. .LP Information Processing - Open Systems Interconnection - Model and Notation - Service Definition - Specification of Basic Encoding Rules for Abstract diff --git a/doc/man/man3/lber-decode.3.links b/doc/man/man3/lber-decode.3.links index 8d43e71e66..3ec93287f9 100644 --- a/doc/man/man3/lber-decode.3.links +++ b/doc/man/man3/lber-decode.3.links @@ -6,6 +6,7 @@ ber_get_int.3 ber_get_stringa.3 ber_get_stringb.3 ber_get_null.3 +ber_get_enum.3 ber_get_boolean.3 ber_get_bitstring.3 ber_first_element.3 diff --git a/doc/man/man3/lber-encode.3 b/doc/man/man3/lber-encode.3 index f2fab9b612..9d5fbb980d 100644 --- a/doc/man/man3/lber-encode.3 +++ b/doc/man/man3/lber-encode.3 @@ -3,7 +3,7 @@ .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME -ber_alloc, ber_flush, ber_printf, ber_put_int, 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_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 SYNOPSIS .nf .ft B @@ -45,6 +45,15 @@ int ber_put_int( .LP .nf .ft B +int ber_put_enum( + BerElement *ber, + ber_int_t num, + ber_tag_t tag); +.ft +.fi +.LP +.nf +.ft B int ber_put_ostring( BerElement *ber, const char \(**str, @@ -140,7 +149,8 @@ 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_t() routine is used to allocate a new BER element. The +The ber_alloc_t() routine is used to allocate a new BER element. It +should be called with an argument of LBER_USE_DER. 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 @@ -162,6 +172,10 @@ The format string can contain the following characters: Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP +.SM e +Enumeration. An ber_int_t parameter should be supplied. An +enumeration element is output. +.TP .SM i Integer. An ber_int_t parameter should be supplied. An integer element is output. @@ -178,6 +192,10 @@ Null. No parameter is required. A null element is output. Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP +.SM O +Octet string. A struct berval * is supplied. +An octet string element is output. +.TP .SM s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. @@ -191,6 +209,11 @@ Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP +.SM V +Several octet strings. A null-terminated array of struct berval *'s +is supplied. Note that a construct like '{V}' is required to get +an actual SEQUENCE OF octet strings. +.TP .SM { Begin sequence. No parameter is required. .TP @@ -207,6 +230,9 @@ End set. No parameter is required. The ber_put_int() routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP +The ber_put_enum() routine writes the enumberation element +\fInum\fP to the BER element \fIber\fP. +.LP The ber_put_boolean() routine writes the boolean value given by \fIbool\fP to the BER element. .LP @@ -263,13 +289,15 @@ can be achieved like so: int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; + BerElement *ber; /* ... fill in values ... */ + ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ - } + } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); @@ -294,8 +322,8 @@ The return values for all of these functions are declared in the .BR ldap-sync (3) .BR ldap-parse (3) .LP -Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access -Protocol", OSI-DS-26, April 1992. +Yeong, W., Howes, T., and Hardcastle-Kille, S., +"Lightweight Directory Access Protocol", OSI-DS-26, April 1992. .LP Information Processing - Open Systems Interconnection - Model and Notation - Service Definition - Specification of Basic Encoding Rules for Abstract diff --git a/doc/man/man3/lber-encode.3.links b/doc/man/man3/lber-encode.3.links index e1fef9a764..54cd0e9669 100644 --- a/doc/man/man3/lber-encode.3.links +++ b/doc/man/man3/lber-encode.3.links @@ -1,10 +1,11 @@ -ber_alloc.3 +ber_alloc_t.3 ber_flush.3 ber_printf.3 ber_put_int.3 ber_put_ostring.3 ber_put_string.3 ber_put_null.3 +ber_put_enum.3 ber_start_set.3 ber_put_seq.3 ber_put_set.3 diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 index a501251abc..ca7ee33627 100644 --- a/doc/man/man3/ldap.3 +++ b/doc/man/man3/ldap.3 @@ -1,4 +1,4 @@ -.TH LDAP 3 "10 November 1998" "OpenLDAP LDVERSION" +.TH LDAP 3 "13 May 2000" "OpenLDAP LDVERSION" .\" $OpenLDAP$ .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. @@ -16,8 +16,6 @@ The Lightweight Directory Access Protocol provides TCP/IP access to the X.500 Directory or to a stand-alone LDAP server. The OpenLDAP LDAP package includes a stand-alone server in .BR slapd (8), -an LDAP to X.500 gateway in -.BR ldapd (8), various LDAP clients, and an LDAP client library used to provide programmatic access to the LDAP protocol. This man page gives an overview of the LDAP library routines. diff --git a/include/lber.h b/include/lber.h index 8315bacb9d..515b45b19b 100644 --- a/include/lber.h +++ b/include/lber.h @@ -200,6 +200,11 @@ ber_get_int LDAP_P(( BerElement *ber, ber_int_t *num )); +LIBLBER_F( ber_tag_t ) +ber_get_enum LDAP_P(( + BerElement *ber, + ber_int_t *num )); + LIBLBER_F( ber_tag_t ) ber_get_stringb LDAP_P(( BerElement *ber, diff --git a/libraries/liblber/decode.c b/libraries/liblber/decode.c index e6f5387261..a97e7bd602 100644 --- a/libraries/liblber/decode.c +++ b/libraries/liblber/decode.c @@ -228,6 +228,14 @@ ber_get_int( return( tag ); } +ber_tag_t +ber_get_enum( + BerElement *ber, + ber_int_t *num ) +{ + ber_get_int( ber, num ); +} + ber_tag_t ber_get_stringb( BerElement *ber, diff --git a/libraries/liblber/nt_err.c b/libraries/liblber/nt_err.c index d5280ac4d2..45de02c8be 100644 --- a/libraries/liblber/nt_err.c +++ b/libraries/liblber/nt_err.c @@ -1,6 +1,6 @@ /* $OpenLDAP$ */ /* - * Copyright 1998-1999 The OpenLDAP Foundation, All Rights Reserved. + * Copyright 1998-2000 The OpenLDAP Foundation, All Rights Reserved. * COPYING RESTRICTIONS APPLY, see COPYRIGHT file */ #include "portable.h" -- 2.39.5