ber_get_next man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

ber_decode(3LDAP)	    LDAP Library Functions	     ber_decode(3LDAP)

NAME
       ber_decode,  ber_alloc_t,  ber_free,  ber_bvdup, ber_init, ber_flatten,
       ber_get_next,  ber_skip_tag,  ber_peek_tag,   ber_scanf,	  ber_get_int,
       ber_get_stringa,	  ber_get_stringal,   ber_get_stringb,	 ber_get_null,
       ber_get_boolean,	 ber_get_bitstring,  ber_first_element,	 ber_next_ele‐
       ment,  ber_bvfree, ber_bvecfree - Basic Encoding Rules library decoding
       functions

SYNOPSIS
       cc[ flag... ] file... -lldap[ library... ]

       #include <lber.h>

       BerElement *ber_alloc_t(int options);

       struct berval *ber_bvdup(struct berval *bv);

       void ber_free(BerElement *ber, int freebuf);

       BerElement *ber_init(struct berval *bv);

       int ber_flatten(BerElement *ber, struct berval **bvPtr);

       ber_get_next(Sockbuf *sb, unsigned long *len, char *bv_val);

       ber_skip_tag(BerElement **ber, unsigned long **len);

       ber_peek_tag(BerElement **ber, unsigned long **len);

       ber_get_int(BerElement **ber, long **num);

       ber_get_stringb(BerElement **ber, char **buf, unsigned long **len);

       ber_get_stringa(BerElement **ber, char ***buf);

       ber_get_stringal(BerElement **ber, struct berval ***bv);

       ber_get_null(BerElement **ber);

       ber_get_boolean(BerElement **ber, int **bool);

       ber_get_bitstringa(BerElement  **ber,  char   ***buf,   unsigned	  long
       **blen);

       ber_first_element(BerElement   **ber,   unsigned	  long	 **len,	  char
       ***cookie);

       ber_next_element(BerElement **ber, unsigned long **len, char **cookie);

       ber_scanf(BerElement **ber, char **fmt [, arg...]);

       ber_bvfree(struct berval **bv );

       ber_bvecfree(struct berval ***bvec);

DESCRIPTION
       These functions provide a subfunction interface to a simplified	imple‐
       mentation  of  the  Basic  Encoding Rules of ASN.1.  The version of BER
       these functions support is the one defined for the LDAP protocol.   The
       encoding	 rules	are  the  same as BER, except that  only definite form
       lengths are used, and bitstrings and octet strings are  always  encoded
       in  primitive  form.   In  addition,  these  lightweight	 BER functions
       restrict tags and class to fit in a single octet (this means the actual
       tag  must  be less than 31).  When a "tag" is specified in the descrip‐
       tions 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 functions in the lber  library.	  See	ber_encode(3LDAP)  for
       details on the corresponding encoding functions.

       Normally,  the only functions that need be called by an application are
       ber_get_next() to get the next BER element and  ber_scanf() to  do  the
       actual  decoding.   In  some cases,  ber_peek_tag() may also need to be
       called in normal usage.	The other functions  are  provided  for	 those
       applications  that  need	 more  control than  ber_scanf() provides.  In
       general, these functions return the tag of the element decoded,	or  −1
       if an error occurred.

       The   ber_get_next() function is used to read the next BER element from
       the given Sockbuf, sb.  A Sockbuf consists of the  descriptor  (usually
       socket,	but  a file descriptor works just as well) from which to read,
       and a BerElement structure used to maintain a  buffer.	On  the	 first
       call,  the  sb_ber  struct should be zeroed.  It strips off and returns
       the leading tag byte, strips off and returns the length of  the	entire
       element	in  len, and sets up ber for subsequent calls to  ber_scanf(),
       and all to decode the element.

       The  ber_scanf() function is used to decode a BER element in  much  the
       same  way  that	 scanf(3C)  works.   It reads from ber, a pointer to a
       BerElement such as returned by  ber_get_next(),	interprets  the	 bytes
       according to the format string fmt, and stores the results in its addi‐
       tional arguments.  The format string contains conversion specifications
       which  are  used	 to direct the interpretation of the BER element.  The
       format string can contain the following characters.

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

       -s	       Octet string.  A char * buffer should be supplied, fol‐
		       lowed  by  a  pointer  to an integer 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.

       -O	       Octet string.  A struct ber_val ** should be  supplied,
		       which  upon  return points to a memory allocated struct
		       berval containing the  octet  string  and  its  length.
		       ber_bvfree()  can  be called to free the allocated mem‐
		       ory.

       -b	       Boolean.	 A pointer to an integer should be supplied.

       -i	       Integer.	 A pointer to an integer should be supplied.

       -B	       Bitstring.  A char ** should  be	 supplied  which  will
		       point  to  the	memory	allocated bits, followed by an
		       unsigned long *, which will point  to  the  length  (in
		       bits) of the bitstring returned.

       -n	       Null.  No parameter is required.	 The element is simply
		       skipped if it is recognized.

       -v	       Sequence of octet strings.  A char *** should  be  sup‐
		       plied,  which  upon return points to a memory allocated
		       null-terminated array of char *'s containing the	 octet
		       strings.	  NULL is returned if the sequence is empty.

       -V	       Sequence of octet strings with lengths. A struct berval
		       *** should be supplied, which upon return points	 to  a
		       memory	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 allocated mem‐
		       ory.

       -x	       Skip element.  The next element is skipped.

       -{	       Begin sequence.	No parameter is required.  The initial
		       sequence tag and length are skipped.

       -}	       End sequence.  No parameter is required and  no	action
		       is taken.

       -[	       Begin  set.  No parameter is required.  The initial set
		       tag and length are skipped.

       -]	       End set.	 No parameter is required  and	no  action  is
		       taken.

       The   ber_get_int()  function tries to interpret the next element as an
       integer, returning the result in num.  The tag of whatever it finds  is
       returned on success,  -1 on failure.

       The   ber_get_stringb() function is used to read an octet string into a
       preallocated buffer.  The len parameter should be  initialized  to  the
       size  of	 the  buffer,  and will contain the length of the octet string
       read upon return.  The buffer should be big enough to  take  the	 octet
       string value plus a terminating	NULL byte.

       The   ber_get_stringa()	function is used to allocate memory space into
       which an octet string is read.

       The  ber_get_stringal() function is used to allocate memory space  into
       which  an  octet	 string	 and  its  length are read.  It takes a struct
       berval **, and returns the result in this parameter.

       The  ber_get_null() function is used  to	 read  a   NULL	 element.   It
       returns the tag of the element it skips over.

       The  ber_get_boolean() function is used to read a boolean value.	 It is
       called the same way that ber_get_int() is called.

       The  ber_get_bitstringa() function is used to read a  bitstring	value.
       It  takes a char ** which will hold the allocated memory bits, followed
       by an unsigned long *, which will point to the length (in bits) of  the
       bitstring returned.

       The   ber_first_element() function is used to return the tag and length
       of the first element in a set or sequence.  It also returns in cookie a
       magic  cookie  parameter	 that  should be passed to subsequent calls to
       ber_next_element(), which returns similar information.

       ber_alloc_t() constructs and returns  BerElement. A  null  pointer   is
       returned on error.  The options field contains a bitwise-or of  options
       which are to be used when generating the encoding of this   BerElement.
       One option is defined and must always be supplied:

       #define LBER_USE_DER 0x01

       When this option is present, lengths will always be encoded in the min‐
       imum number of octets.  Note that this option does not cause values  of
       sets  and  sequences  to	 be rearranged in tag and byte order, so these
       functions are not suitable for generating  DER  output  as  defined  in
       X.509 and X.680

       The   ber_init  function	 constructs  a	 BerElement  and returns a new
       BerElement containing a copy of the data in the bv argument.   ber_init
       returns the null pointer on error.

       ber_free()  frees  a   BerElement  which is returned from the API calls
       ber_alloc_t() or	 ber_init(). Each  BerElement must  be	freed  by  the
       caller.	 The  second  argument	 freebuf  should always be set to 1 to
       ensure that the internal buffer used by the BER functions is  freed  as
       well as the  BerElement container itself.

       ber_bvdup()  returns  a	copy  of  a   berval. The  bv_val field in the
       returned	 berval points to a different area of memory  as  the	bv_val
       field  in  the  argument berval. The null pointer is returned on	 error
       (that is, is out of memory).

       The  ber_flatten routine allocates a struct  berval  whose contents are
       BER encoding taken from the  ber argument. The  bvPtr pointer points to
       the returned  berval, which must be  freed  using   ber_bvfree().  This
       routine returns	0 on success and  −1 on error.

EXAMPLES
       Example	1: Assume the variable ber contains a lightweight BER 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	 (3N)
		 },
		 sizelimit	 INTEGER (0 .. 65535),
		 timelimit	 INTEGER (0 .. 65535),
		 attrsOnly	 BOOLEAN,
		 attributes	 SEQUENCE OF AttributeType
	     }

       Example 2: The element can be decoded using  ber_scanf() as follows.

	     int    scope, ali, size, time, attrsonly;
	     char   *dn, **attrs;
	     if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali,
		 &size, &time, &attrsonly, &attrs ) == -1 )
		     /* error */
	     else
		     /* success */

ERRORS
       If an error occurs during decoding, generally  these  functions	return
       −1.

NOTES
       The  return  values  for	 all  of  these	 functions are declared in the
       <lber.h> header file.  Some functions may allocate memory which must be
       freed by the calling application.

ATTRIBUTES
       See attributes(5) for a description of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       │Availability		     │SUNWcsl (32-bit)		   │
       │			     │SUNWcslx (64-bit)		   │
       │Interface Stability	     │Evolving			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       ber_encode(3LDAP)

       Yeong,  W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory
       Access Protocol", OSI-DS-26, April 1992.

       Information Processing - Open Systems Interconnection - Model and Nota‐
       tion  -	Service Definition - Specification of Basic Encoding Rules for
       Abstract Syntax Notation One, International Organization for  Standard‐
       ization, International Standard 8825.

SunOS 5.10			  27 Jan 2002		     ber_decode(3LDAP)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net