From 1cceca327779c12190a7df5c8ae558643360117a Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 10 Jul 2021 15:56:18 +0000 Subject: [PATCH] new manual page BIO_dump(3) --- lib/libcrypto/man/BIO_dump.3 | 144 +++++++++++++++++++++++++++++++++++ lib/libcrypto/man/BIO_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- 3 files changed, 149 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/BIO_dump.3 diff --git a/lib/libcrypto/man/BIO_dump.3 b/lib/libcrypto/man/BIO_dump.3 new file mode 100644 index 00000000000..88ae7d571de --- /dev/null +++ b/lib/libcrypto/man/BIO_dump.3 @@ -0,0 +1,144 @@ +.\" $OpenBSD: BIO_dump.3,v 1.1 2021/07/10 15:56:18 schwarze Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: July 10 2021 $ +.Dt BIO_DUMP 3 +.Os +.Sh NAME +.Nm BIO_dump , +.Nm BIO_dump_indent , +.Nm BIO_dump_fp , +.Nm BIO_dump_indent_fp +.Nd hexadecimal printout of arbitrary byte arrays +.Sh SYNOPSIS +.In openssl/bio.h +.Ft int +.Fo BIO_dump +.Fa "BIO *b" +.Fa "const char *s" +.Fa "int len" +.Fc +.Ft int +.Fo BIO_dump_indent +.Fa "BIO *b" +.Fa "const char *s" +.Fa "int len" +.Fa "int indent" +.Fc +.Ft int +.Fo BIO_dump_fp +.Fa "FILE *fp" +.Fa "const char *s" +.Fa "int len" +.Fc +.Ft int +.Fo BIO_dump_indent_fp +.Fa "FILE *fp" +.Fa "const char *s" +.Fa "int len" +.Fa "int indent" +.Fc +.Sh DESCRIPTION +.Fn BIO_dump +prints +.Fa len +bytes starting at +.Fa s +to +.Fa bio +in hexadecimal format. +.Pp +The first column of output contains the index, in the byte array starting at +.Fa s , +of the first byte shown on the respective output line, expressed as a +four-digit hexadecimal number starting at 0000, followed by a dash. +After the dash, sixteen bytes of data are printed as two-digit +hexadecimal numbers, respecting the order in which they appear in +the array +.Fa s . +Another dash is printed after the eighth column. +.Pp +To the right of the hexadecimal representation of the bytes, +the same bytes are printed again, this time as ASCII characters. +Non-printable ASCII characters are replaced with dots. +.Pp +Trailing space characters and NUL bytes are omitted from the main table. +If there are any, an additional line is printed, constisting of the +.Fa len +argument as a four-digit hexadecimal number, a dash, and the fixed string +.Qq . +.Pp +.Fn BIO_dump_indent +is similar except that +.Fa indent +space characters are prepended to each output line. +If +.Fa indent +is 7 or more, the number of data columns is reduced such that the +total width of the output does not exceed 79 characters per line. +.Pp +.Fn BIO_dump_fp +and +.Fn BIO_dump_indent_fp +are similar except that +.Xr fwrite 3 +is used instead of +.Xr BIO_write 3 . +.Sh RETURN VALUES +These functions return the sum of the return values of all calls to +.Xr BIO_write 3 +or +.Xr fwrite 3 +that were made. +This is useless because it may add a positive number, the total amount +of bytes written by successful calls to +.Xr BIO_write 3 , +to an incommensurable negative number, usually the number of calls to +.Xr BIO_write 3 +that failed. +All that can be said is that a negative return value indicates that +at least part of the printing failed, and a positive return value +indicates that at least some of the printing succeeded, but one +cannot tell whether success or failure were partial or complete. +Furthermore, a zero return value does not necessarily mean that +nothing was printed; it can also occur if a part of the printing +succeeded and another part failed. +.Sh SEE ALSO +.Xr hexdump 1 , +.Xr BIO_new 3 , +.Xr BIO_write 3 +.Sh HISTORY +.Fn BIO_dump +first appeared in SSLeay 0.6.5 and has been available since +.Ox 2.4 . +.Pp +.Fn BIO_dump_indent +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn BIO_dump_fp +and +.Fn BIO_dump_indent_fp +first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . +.Sh BUGS +If some parts of the printing operations succeed +and some other parts fail, +.Fn BIO_dump +may silently yield incomplete results +such that the caller cannot detect the partial failure. +Besides, the function may have written more bytes than the return +value indicates. diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3 index a2bc40d3681..e7c08c99f1a 100644 --- a/lib/libcrypto/man/BIO_new.3 +++ b/lib/libcrypto/man/BIO_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BIO_new.3,v 1.20 2021/03/12 07:05:35 jmc Exp $ +.\" $OpenBSD: BIO_new.3,v 1.21 2021/07/10 15:56:18 schwarze Exp $ .\" full merge up to: .\" OpenSSL man3/BIO_new.pod fb46be03 Feb 26 11:51:31 2016 +0000 .\" OpenSSL man7/bio.pod 631c37be Dec 12 16:56:50 2017 +0100 @@ -52,7 +52,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 12 2021 $ +.Dd $Mdocdate: July 10 2021 $ .Dt BIO_NEW 3 .Os .Sh NAME @@ -229,6 +229,7 @@ Create a memory BIO: .Dl BIO *mem = BIO_new(BIO_s_mem()); .Sh SEE ALSO .Xr BIO_ctrl 3 , +.Xr BIO_dump 3 , .Xr BIO_f_base64 3 , .Xr BIO_f_buffer 3 , .Xr BIO_f_cipher 3 , diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index bf76a1ce745..46a7d3beb23 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.175 2021/07/09 12:07:27 schwarze Exp $ +# $OpenBSD: Makefile,v 1.176 2021/07/10 15:56:18 schwarze Exp $ .include @@ -22,6 +22,7 @@ MAN= \ BASIC_CONSTRAINTS_new.3 \ BF_set_key.3 \ BIO_ctrl.3 \ + BIO_dump.3 \ BIO_f_base64.3 \ BIO_f_buffer.3 \ BIO_f_cipher.3 \ -- 2.20.1