X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman3%2Flber-types.3;h=fbe566c262f8c6508116bdef7a33bcee23efa069;hb=424d673a6c8e21795f3142cdc29999d7ee4e44ad;hp=1cd28f1ae16ed165d31119747c0872b30c974859;hpb=71d564aee43f0e48eacc318d766cd32e102ddade;p=openldap diff --git a/doc/man/man3/lber-types.3 b/doc/man/man3/lber-types.3 index 1cd28f1ae1..fbe566c262 100644 --- a/doc/man/man3/lber-types.3 +++ b/doc/man/man3/lber-types.3 @@ -1,15 +1,17 @@ -.TH LBER_TYPES 3 "29 August 2001" "OpenLDAP LDVERSION" +.TH LBER_TYPES 3 "RELEASEDATE" "OpenLDAP LDVERSION" .\" $OpenLDAP$ -.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved. +.\" Copyright 1998-2004 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME -ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t \- LBER types +ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, +struct berval, BerValue, BerVarray, BerElement, +ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, +ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_free +\- LBER types and allocation functions +.SH LIBRARY +OpenLDAP LBER (liblber, -llber) .SH SYNOPSIS -.nf -.ft B -#include -.ft -.fi +.B #include .LP .nf .ft B @@ -22,14 +24,37 @@ typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; -} BerValue; +} BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi +.LP +.BI "void ber_bvfree(struct berval *" bv ");" +.LP +.BI "void ber_bvecfree(struct berval **" bvec ");" +.LP +.BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" +.LP +.BI "void ber_bvarray_free(struct berval *" bvarray ");" +.LP +.BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" +.LP +.BI "struct berval *ber_bvdup(const struct berval *" bv ");" +.LP +.BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" +.LP +.BI "struct berval *ber_bvstr(const char *" str ");" +.LP +.BI "struct berval *ber_bvstrdup(const char *" str ");" +.LP +.BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" +.LP +.BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP -The are basic types defined for use with the Lightweight BER library. +The following are the basic types and structures defined for use +with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to @@ -39,7 +64,7 @@ is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t -is a unsigned integer of at least 32 bits used to represent a length. +is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t @@ -47,34 +72,99 @@ is the signed variant to .BR ber_len_t . .LP .B ber_tag_t -is a unsigned integer of at least 32 bits used to represent a +is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP -The actual definitions of the integal impl_TYPE_t types are platform +The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , -is used to holds an arbitrary sequence of octets. +is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val -is not necessarly terminated by a NULL (zero) octet. +is not necessarly terminated by a NUL (zero) octet. +.BR ber_bvfree () +frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP +is NULL, the routine does nothing. +.LP +.BR ber_bvecfree () +frees an array of BerValues (and the array), pointed to by \fIbvec\fP, +returned from this API. If \fIbvec\fP is NULL, the routine does nothing. +.BR ber_bvecadd () +appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array +is allocated as needed. The end of the array is marked by a NULL pointer. +.LP +.BR ber_bvarray_free () +frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, +returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. +.BR ber_bvarray_add () +appends the contents of the BerValue pointed to by \fIbv\fP to the +\fIbvarray\fP array. Space for the new element is allocated as needed. +The end of the array is marked by a BerValue with a NULL bv_val field. +.LP +.BR ber_bvdup () +returns a copy of a BerValue. The routine returns NULL upon error +(e.g. out of memory). The caller should use +.BR ber_bvfree () +to deallocate the resulting BerValue. +.BR ber_dupbv () +copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a +new BerValue will be allocated to hold the copy. The routine returns NULL +upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is +NULL the caller should use +.BR ber_bvfree () +to deallocate the resulting BerValue, otherwise +.BR ber_memfree () +should be used to deallocate the \fIdst->bv_val\fP. (The +.BR ber_bvdup () +function is internally implemented as ber_dupbv(NULL, bv). +.BR ber_bvdup () +is provided only for compatibility with an expired draft of the LDAP C API; +.BR ber_dupbv () +is the preferred interface.) +.LP +.BR ber_bvstr () +returns a BerValue containing the string pointed to by \fIstr\fP. +.BR ber_bvstrdup () +returns a BerValue containing a copy of the string pointed to by \fIstr\fP. +.BR ber_str2bv () +returns a BerValue containing the string pointed to by \fIstr\fP, whose +length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, +the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the +number of bytes to copy will be determined by +.BR strlen (3), +otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result +will be stored in the given BerValue, otherwise a new BerValue will be +allocated to store the result. NOTE: Both +.BR ber_bvstr () +and +.BR ber_bvstrdup () +are implemented as macros using +.BR ber_str2bv () +in this version of the library. .LP .B BerElement -is an opaque structure used to hold state information for LBER encoding -and decoding routines. +is an opaque structure used to maintain state information used in +encoding and decoding. BerElement structures are created using +.BR ber_alloc_t (3) +and +.BR ber_init (3). +.BR ber_free () +frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine +does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO -.BR lber-encode (3) -.BR lber-decode (3) +.BR lber-encode (3), +.BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS -.B OpenLDAP +.B OpenLDAP 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.