mirror of
https://git.openldap.org/openldap/openldap.git
synced 2025-02-17 14:00:30 +08:00
Update lber-encode/decode man pages
Add ber_get_enum() for symmetry
This commit is contained in:
Kurt Zeilenga
parent
4bc786f34b
commit
e9d0b98a10
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user