Browse Source

add various missing information

and remove the lie that these functions would set errno;
tweaks and OK jmc@; OK rob@ on the previous version
OPENBSD_6_6
schwarze 5 years ago
parent
commit
f6ecccdd17
1 changed files with 75 additions and 29 deletions
  1. +75
    -29
      src/lib/libutil/ber_get_string.3

+ 75
- 29
src/lib/libutil/ber_get_string.3 View File

@ -1,4 +1,4 @@
.\" $OpenBSD: ber_get_string.3,v 1.3 2019/05/16 17:39:21 rob Exp $
.\" $OpenBSD: ber_get_string.3,v 1.4 2019/05/17 14:40:59 schwarze Exp $
.\"
.\" Copyright (c) 2007, 2012 Reyk Floeter <reyk@openbsd.org>
.\"
@ -14,7 +14,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: May 16 2019 $
.Dd $Mdocdate: May 17 2019 $
.Dt BER_GET_STRING 3
.Os
.Sh NAME
@ -59,42 +59,88 @@
.Ft "int"
.Fn "ber_scanf_elements" "struct ber_element *root" "char *format" "..."
.Sh DESCRIPTION
The
.Fn ber_get_*
Functions which take two arguments save the value contained in the
.Fa root
element into the storage location pointed to by the second argument.
Additionally,
.Fn ber_get_nstring
and
.Fn ber_get_bitstring
save the number of bytes contained in the string into
.Pf * Fa size .
.Pp
.Fn ber_scanf_elements
functions may be used to save
retrieves the values from zero or more elements starting at
.Fa root .
For each byte in
.Fa fmt ,
arguments of the types given in the following table are consumed
and passed to the function listed, processing one
.Vt ber_element
values into local variables.
per byte.
The following bytes are valid:
.Bl -column -offset indent bytes ber_get_enumerated() "1: struct ber_element **"
.It Sy byte Ta Sy function Ta Sy arguments
.It B Ta Fn ber_get_bitstring Ta 2: Vt void ** , size_t *
.It b Ta Fn ber_get_boolean Ta 1: Vt int *
.It d Ta Fn ber_get_integer Ta 1: Vt int *
.It E Ta Fn ber_get_enumerated Ta 1: Vt long long *
.It e Ta see below Ta 1: Vt struct ber_element **
.It i Ta Fn ber_get_integer Ta 1: Vt long long *
.It o Ta Fn ber_get_oid Ta 1: Vt struct ber_oid *
.It p Ta Fn ber_getpos Ta 1: Vt off_t *
.It S Ta see below Ta 0
.It s Ta Fn ber_get_string Ta 1: Vt char **
.It t Ta see below Ta 2: Vt int * , unsigned int *
.It x Ta Fn ber_get_nstring Ta 2: Vt void **, size_t *
.It \&( or { Ta see below Ta 0
.It \&) or } Ta see below Ta 0
.It \&. Ta Fn ber_get_eoc Ta 0
.It 0 Ta Fn ber_get_null Ta 0
.El
.Pp
.Fn ber_getpos
may be used to obtain the
.Vt ber_element
offset
.Fa be_offs .
.Sh RETURN VALUES
Upon successful completion,
.Fn ber_get_null ,
.Fn ber_get_eoc ,
.Fn ber_get_integer ,
.Fn ber_get_enumerated ,
.Fn ber_get_boolean ,
.Fn ber_get_string ,
.Fn ber_get_nstring ,
.Fn ber_get_ostring ,
.Fn ber_get_bitstring ,
.Fn ber_get_oid ,
.Fn ber_string2oid
For
.Sq e ,
.Sq p ,
.Sq S ,
and
.Fn ber_scanf_elements
return 0.
Otherwise \-1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sq t ,
the type of the element is not checked.
For
.Sq e ,
a pointer to the element is stored in the corresponding pointer variable.
For
.Sq S ,
the element is skipped without extracting any information from it.
For
.Sq t ,
the class and type of the element are stored in the two corresponding
variables, but if the element contains a value, that value is ignored.
.Pp
For an opening parenthesis or brace, it is checked that the element
is a sequence or a set, and parsing continues with its children.
For a closing parenthesis or brace, parsing of the current sequence
or set is ended and parsing continues with the element following
the sequence or set.
.Sh RETURN VALUES
.Fn ber_getpos
returns the value of
.Vt be_offs .
.Pp
.Fn ber_scanf_elements
returns 0 for success or \-1 when encountering elements that do not
agree with the expectations of
.Fa fmt
or when
.Fa fmt
is syntactically invalid.
Even when
.Fn ber_scanf_elements
fails, some of the arguments may already have been filled in.
.Pp
The other functions return 0 if
.Va root
is of the requested type or \-1 otherwise.
.Sh SEE ALSO
.Xr ber_add_string 3 ,
.Xr ber_oid_cmp 3 ,


Loading…
Cancel
Save