.\" $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.