--- /dev/null
+.\" $OpenBSD: ASN1_BIT_STRING_num_asc.3,v 1.1 2021/11/19 16:00:54 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 19 2021 $
+.Dt ASN1_BIT_STRING_NUM_ASC 3
+.Os
+.Sh NAME
+.Nm ASN1_BIT_STRING_num_asc ,
+.Nm ASN1_BIT_STRING_set_asc ,
+.Nm ASN1_BIT_STRING_name_print
+.Nd names for individual bits
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Bd -unfilled
+typedef struct {
+ int bitnum;
+ const char *lname;
+ const char *sname;
+} BIT_STRING_BITNAME;
+.Ed
+.Pp
+.Ft int
+.Fo ASN1_BIT_STRING_num_asc
+.Fa "const char *name"
+.Fa "BIT_STRING_BITNAME *table"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_set_asc
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "const char *name"
+.Fa "int set"
+.Fa "BIT_STRING_BITNAME *table"
+.Fc
+.Ft int
+.Fo ASN1_BIT_STRING_name_print
+.Fa "BIO *bio"
+.Fa "ASN1_BIT_STRING *bitstr"
+.Fa "BIT_STRING_BITNAME *table"
+.Fa "int indent"
+.Fc
+.Sh DESCRIPTION
+These functions provide access to individual bits of an ASN.1 BIT STRING
+based on a
+.Fa table
+assigning names to individual bits.
+The
+.Fa table
+is a variable-sized array.
+Each element contains a long name
+.Fa lname
+and a short name
+.Fa sname
+for the bit with the bit number
+.Fa bitnum .
+The table needs to be terminated with a dummy element containing a
+.Dv NULL
+pointer in the
+.Fa lname
+field.
+.Pp
+.Fn ASN1_BIT_STRING_num_asc
+retrieves the
+.Fa bitnum
+from the first element in the
+.Fa table
+where at least one of the names matches the
+.Fa name
+argument in the sense of
+.Xr strcmp 3 .
+That bit number can then be used for
+.Xr ASN1_BIT_STRING_get_bit 3 .
+.Pp
+.Fn ASN1_BIT_STRING_set_asc
+converts the
+.Fa name
+to a bit number using
+.Fn ASN1_BIT_STRING_num_asc
+and sets or clears that bit in
+.Fa bitstr
+according to the
+.Fa set
+argument, using
+.Xr ASN1_BIT_STRING_set_bit 3 .
+If
+.Fa bitstr
+is a
+.Dv NULL
+pointer, no action occurs.
+.Pp
+.Fn ASN1_BIT_STRING_name_print
+prints a single line of text to the given
+.Fa BIO .
+The line starts with
+.Fa indent
+space characters, contains the long names of the bit contained in the
+.Fa table
+that are set in
+.Fa bitstr ,
+separated by commas, and ends with a newline character.
+If any bits are set in
+.Fa bitstr
+that have no corresponding entries in the
+.Fa table ,
+those bits are silently ignored and nothing is printed for them.
+.Sh RETURN VALUES
+.Fn ASN1_BIT_STRING_num_asc
+returns a non-negative bit number or \-1 if the
+.Fa name
+is not found in the
+.Fa table .
+.Pp
+.Fn ASN1_BIT_STRING_set_asc
+returns 1 on success or 0 if the
+.Fa name
+is not found in the
+.Fa table
+or if memory allocation fails.
+.Pp
+.Fn ASN1_BIT_STRING_name_print
+is intended to return 1 for success or 0 for failure.
+.Sh SEE ALSO
+.Xr ASN1_BIT_STRING_new 3 ,
+.Xr ASN1_BIT_STRING_set 3 ,
+.Xr BIO_new 3 ,
+.Xr strcmp 3
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.5
+and have been available since
+.Ox 2.7 .
+.Sh BUGS
+.Fn ASN1_BIT_STRING_name_print
+ignores all errors and always returns 1,
+even if nothing or only part of the desired output was printed.
-.\" $OpenBSD: ASN1_STRING_new.3,v 1.22 2021/11/15 16:18:36 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_new.3,v 1.23 2021/11/19 16:00:54 schwarze Exp $
.\" OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
.\"
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: November 15 2021 $
+.Dd $Mdocdate: November 19 2021 $
.Dt ASN1_STRING_NEW 3
.Os
.Sh NAME
is returned and an error code can be retrieved with
.Xr ERR_get_error 3 .
.Sh SEE ALSO
+.Xr ASN1_BIT_STRING_num_asc 3 ,
.Xr ASN1_BIT_STRING_set 3 ,
.Xr ASN1_INTEGER_get 3 ,
.Xr ASN1_item_pack 3 ,
projects / openbsd / commitdiff