From: schwarze Date: Thu, 25 Nov 2021 12:15:37 +0000 (+0000) Subject: Document BIO_method_name(3). X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=6033101ef7a2d70aba53b3a6b3dd84c7a2d8d0d9;p=openbsd Document BIO_method_name(3). While here, also improve the rest of the page: * add missing BIO_TYPE_* constants * describe BIO_TYPE_START * better function argument names * more precision in the descriptions and regarding the RETURN VALUES * lots of wording improvements * improve the coding style below EXAMPLES * delete a BUGS section describing cretaceous behaviour --- diff --git a/lib/libcrypto/man/BIO_find_type.3 b/lib/libcrypto/man/BIO_find_type.3 index 99e93167a54..8882dbf4043 100644 --- a/lib/libcrypto/man/BIO_find_type.3 +++ b/lib/libcrypto/man/BIO_find_type.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: BIO_find_type.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $ -.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 +.\" $OpenBSD: BIO_find_type.3,v 1.10 2021/11/25 12:15:37 schwarze Exp $ +.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 Ingo Schwarze +.\" +.\" 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. +.\" +.\" The original file was written by Dr. Stephen Henson . .\" Copyright (c) 2000, 2013, 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,28 +65,33 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 27 2018 $ +.Dd $Mdocdate: November 25 2021 $ .Dt BIO_FIND_TYPE 3 .Os .Sh NAME .Nm BIO_find_type , .Nm BIO_next , -.Nm BIO_method_type +.Nm BIO_method_type , +.Nm BIO_method_name .Nd BIO chain traversal .Sh SYNOPSIS .In openssl/bio.h .Ft BIO * .Fo BIO_find_type -.Fa "BIO *b" -.Fa "int bio_type" +.Fa "BIO *bio" +.Fa "int type" .Fc .Ft BIO * .Fo BIO_next -.Fa "BIO *b" +.Fa "BIO *bio" .Fc .Ft int .Fo BIO_method_type -.Fa "const BIO *b" +.Fa "const BIO *bio" +.Fc +.Ft const char * +.Fo BIO_method_name +.Fa "const BIO *bio" .Fc .Fd #define BIO_TYPE_NONE 0 .Fd #define BIO_TYPE_MEM (1|0x0400) @@ -90,86 +112,113 @@ .Fd #define BIO_TYPE_NULL_FILTER (17|0x0200) .Fd #define BIO_TYPE_BER (18|0x0200) .Fd #define BIO_TYPE_BIO (19|0x0400) +.Fd #define BIO_TYPE_LINEBUFFER (20|0x0200) +.Fd #define BIO_TYPE_DGRAM (21|0x0400|0x0100) +.Fd #define BIO_TYPE_ASN1 (22|0x0200) +.Fd #define BIO_TYPE_COMP (23|0x0200) .Fd #define BIO_TYPE_DESCRIPTOR 0x0100 .Fd #define BIO_TYPE_FILTER 0x0200 .Fd #define BIO_TYPE_SOURCE_SINK 0x0400 +.Fd #define BIO_TYPE_START 128 .Sh DESCRIPTION -The function .Fn BIO_find_type -searches for a BIO of a given type in a chain, starting at BIO -.Fa b . -If -.Fa bio_type -is a specific type (such as -.Dv BIO_TYPE_MEM ) , -then a search is made for a BIO of that type. -If -.Fa bio_type -is a general type (such as -.Dv BIO_TYPE_SOURCE_SINK ) , -then the next matching BIO of the given general type is searched for. -.Fn BIO_find_type -returns the next matching BIO or -.Dv NULL -if none is found. +searches for a BIO matching the given +.Fa type +in the chain starting at +.Fa bio . +If the least significant byte of the +.Fa type +argument is non-zero, only exact matches of the +.Fa type +are accepted. +Otherwise, a match only requires that any of the bits set in the +.Fa type +argument is also set in the candidate BIO. .Pp -Note: not all the +Not all the .Dv BIO_TYPE_* -types above have corresponding BIO implementations. +types shown above have corresponding BIO implementations. +.Pp +Types with a least significant byte in the range from 0 to +.Dv BIO_TYPE_START , +inclusive, are reserved for BIO types built into the library. +Types with a least significant byte greater than +.Dv BIO_TYPE_START +are available for user-defined BIO types; see +.Xr BIO_get_new_index 3 +for details. .Pp .Fn BIO_next -returns the next BIO in a chain. -It can be used to traverse all BIOs in a chain or used in conjunction with +returns the next BIO in the chain after +.Fa bio . +This function can be used to traverse all BIOs in a chain +or in conjunction with .Fn BIO_find_type to find all BIOs of a certain type. .Pp .Fn BIO_method_type -returns the type of a BIO. +returns the type of the given +.Fa bio . +.Pp +.Fn BIO_method_name +returns an ASCII string representing the type of the +.Fa bio . .Sh RETURN VALUES .Fn BIO_find_type -returns a matching BIO or +returns the next matching BIO or +.Dv NULL +if +.Fa bio +is a .Dv NULL -for no match. +pointer or if no matching BIO is found. .Pp .Fn BIO_next -returns the next BIO in a chain. +returns the next BIO or +.Dv NULL +if +.Fa bio +is a +.Dv NULL +pointer or points to the last BIO in a chain. .Pp .Fn BIO_method_type -returns the type of the BIO -.Fa b . +returns one of the +.Dv BIO_TYPE_* +constants. +.Pp +.Fn BIO_method_name +returns an internal pointer to a string. .Sh EXAMPLES Traverse a chain looking for digest BIOs: .Bd -literal -offset 2n BIO *btmp; -btmp = in_bio; /* in_bio is chain to search through */ -do { +btmp = in_bio; /* in_bio is the chain to search through */ +while (btmp != NULL) { btmp = BIO_find_type(btmp, BIO_TYPE_MD); if (btmp == NULL) break; /* Not found */ - /* btmp is a digest BIO, do something with it ...*/ + + /* btmp is a digest BIO, do something with it ... */ ... btmp = BIO_next(btmp); -} while(btmp); +} .Ed .Sh SEE ALSO +.Xr BIO_meth_new 3 , .Xr BIO_new 3 .Sh HISTORY .Fn BIO_method_type +and +.Fn BIO_method_name first appeared in SSLeay 0.6.0. .Fn BIO_find_type first appeared in SSLeay 0.6.6. -Both functions have been available since +These functions have been available since .Ox 2.4 . .Pp .Fn BIO_next first appeared in OpenSSL 0.9.6 and has been available since .Ox 2.9 . -.Sh BUGS -.Fn BIO_find_type -in OpenSSL 0.9.5a and earlier could not be safely passed a -.Dv NULL -pointer for the -.Fa b -argument.