Manual Pages for UNIX Darwin command on man ber_alloc

Manual Pages for UNIX Darwin command on man ber_alloc_t

LBERENCODE(3) LBERENCODE(3)

NAME

beralloct, berflush, berprintf, berputint, berputenum, berputostring, berputstring, berputnull, berputboolean, berputbitstring, berstartseq, berstartset, berputseq,

berputset - LBER simplified Basic Encoding Rules library routines for

encoding LLIIBBRRAARRYY

OpenLDAP LBER (liblber, -llber)

SYNOPSIS

##iinncclluuddee <>

BBeerrEElleemmeenntt **bbeerraalllloocctt((iinntt options));; iinntt bbeerrfflluusshh((SSoocckkbbuuff **sb,, BBeerrEElleemmeenntt **ber,, iinntt freeit));; iinntt bbeerrpprriinnttff((BBeerrEElleemmeenntt **ber,, ccoonnsstt cchhaarr **fmt,, ......));; iinntt bbeerrppuuttiinntt((BBeerrEElleemmeenntt **ber,, bbeerriinntttt num,, bbeerrttaaggtt tag));; iinntt bbeerrppuutteennuumm((BBeerrEElleemmeenntt **ber,, bbeerriinntttt num,, bbeerrttaaggtt tag));; iinntt bbeerrppuuttoossttrriinngg((BBeerrEElleemmeenntt **ber,, ccoonnsstt cchhaarr **str,, bbeerrlleenntt len,, bbeerrttaaggtt tag));; iinntt bbeerrppuuttssttrriinngg((BBeerrEElleemmeenntt **ber,, ccoonnsstt cchhaarr **str,, bbeerrttaaggtt tag));; iinntt bbeerrppuuttnnuullll((BBeerrEElleemmeenntt **ber,, bbeerrttaaggtt tag));; iinntt bbeerrppuuttbboooolleeaann((BBeerrEElleemmeenntt **ber,, bbeerriinntttt bool,, bbeerrttaaggtt tag));; iinntt bbeerrppuuttbbiittssttrriinngg((BBeerrEElleemmeenntt **ber,, ccoonnsstt cchhaarr **str,, bbeerrlleenntt blen,, bbeerrttaaggtt tag));; iinntt bbeerrssttaarrttsseeqq((BBeerrEElleemmeenntt **ber,, bbeerrttaaggtt tag));; iinntt bbeerrssttaarrttsseett((BBeerrEElleemmeenntt **ber,, bbeerrttaaggtt tag));; iinntt bbeerrppuuttsseeqq((BBeerrEElleemmeenntt **ber));; iinntt bbeerrppuuttsseett((BBeerrEElleemmeenntt **ber));;

DESCRIPTION

These routines provide a subroutine interface to a simplified implemen-

tation of the Basic Encoding Rules of ASN.1. The version of BER these

routines support is the one defined for the LDAP protocol. The encod-

ing rules are the same as BER, except that only definite form lengths

are used, and bitstrings and octet strings are always encoded in primi-

tive form. This man page describes the encoding routines in the lber

library. See llbbeerr-ddeeccooddee(3) for details on the corresponding decoding

routines. Consult llbbeerr-ttyyppeess(3) for information about types, alloca-

tors, and deallocators. Normally, the only routines that need to be called by an application are bbeerraalllloocctt() to allocate a BER element for encoding, bbeerrpprriinnttff()

to do the actual encoding, and bbeerrfflluusshh() to actually write the ele-

ment. The other routines are provided for those applications that need more control than bbeerrpprriinnttff() provides. In general, these routines

return the length of the element encoded, or -1 if an error occurred.

The bbeerraalllloocctt() routine is used to allocate a new BER element. It should be called with an argument of LBERUSEDER. The bbeerrfflluusshh() routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using

bbeerrpprriinnttff() and friends). See llbbeerr-ssoocckkbbuuff(3) for more details on the

Sockbuf implementation of the sb parameter. If the freeit parameter is

non-zero, the supplied ber will be freed after its contents have been

flushed. The bbeerrpprriinnttff() routine is used to encode a BER element in much the same way that sspprriinnttff(3) works. One important difference, though, is

that some state information is kept with the ber parameter so that mul-

tiple calls can be made to bbeerrpprriinnttff() to append things to the end of the BER element. BBeerrpprriinnttff() writes to ber, a pointer to a BerElement

such as returned by bbeerraalllloocctt(). It interprets and formats its argu-

ments according to the format string fmt. The format string can con-

tain the following characters: bb Boolean. An berintt parameter should be supplied. A boolean element is output. ee Enumeration. An berintt parameter should be supplied. An enumeration element is output. ii Integer. An berintt parameter should be supplied. An integer element is output. BB Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. nn Null. No parameter is required. A null element is output. oo Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. OO Octet string. A struct berval * is supplied. An octet string element is output.

ss Octet string. A null-terminated string is supplied. An

octet string element is output, not including the trailing NULL octet. tt Tag. A bertagt specifying the tag to give the next element is provided. This works across calls.

vv 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.

VV 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.

WW Several octet strings. An array of struct berval's is sup-

plied. The array is terminated by a struct berval with a NULL bvval. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. {{ Begin sequence. No parameter is required. }} End sequence. No parameter is required. [[ Begin set. No parameter is required. ]] End set. No parameter is required. The bbeerrppuuttiinntt() routine writes the integer element num to the BER element ber. The bbeerrppuutteennuumm() routine writes the enumeration element num to the BER element ber. The bbeerrppuuttbboooolleeaann() routine writes the boolean value given by bool to the BER element. The bbeerrppuuttbbiittssttrriinngg() routine writes blen bits starting at str as a bitstring value to the given BER element. Note that blen is the length in bits of the bitstring. The bbeerrppuuttoossttrriinngg() routine writes len bytes starting at str to the BER element as an octet string.

The bbeerrppuuttssttrriinngg() routine writes the null-terminated string (minus

the terminating ' ') to the BER element as an octet string. The bbeerrppuuttnnuullll() routine writes a NULL element to the BER element.

The bbeerrssttaarrttsseeqq() routine is used to start a sequence in the BER ele-

ment. The bbeerrssttaarrttsseett() routine works similarly. The end of the sequence or set is marked by the nearest matching call to bbeerrppuuttsseeqq() or bbeerrppuuttsseett(), respectively. EEXXAAMMPPLLEESS Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: 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 } can be achieved like so: int rc; berintt scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = beralloct( LBERUSEDER ); if ( ber == NULL ) { /* error */ } rc = berprintf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs );

if( rc == -1 ) {

/* error */ } else { /* success */ } EERRRROORRSS

If an error occurs during encoding, generally these routines return -1.

NNOOTTEESS The return values for all of these functions are declared in the header file.