.\" -*-nroff-*- .\" .\" Manual for old-fashioned binary encoding and decoding .\" .\" (c) 1999, 2001, 2004, 2005, 2009, 2023, 2024 Straylight/Edgeware .\" . .\"----- Licensing notice --------------------------------------------------- .\" .\" This file is part of the mLib utilities library. .\" .\" mLib is free software: you can redistribute it and/or modify it under .\" the terms of the GNU Library General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or (at .\" your option) any later version. .\" .\" mLib is distributed in the hope that it will be useful, but WITHOUT .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public .\" License for more details. .\" .\" You should have received a copy of the GNU Library General Public .\" License along with mLib. If not, write to the Free Software .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, .\" USA. . .\"-------------------------------------------------------------------------- .so ../defs.man \" @@@PRE@@@ . .\"-------------------------------------------------------------------------- .TH base64 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library" .\" @base64_encode .\" @base64_decode .\" @base64_init .\" @base32_encode .\" @base32_decode .\" @base32_init .\" @hex_encode .\" @hex_decode .\" @hex_init . .\"-------------------------------------------------------------------------- .SH NAME base64, base32, hex \- obsolete binary encoding functions . .\"-------------------------------------------------------------------------- .SH SYNOPSIS . .nf .B "#include " .B "#include " .B "#include " .PP .ta 2n .B "typedef struct {" .B " char *indent;" .B " unsigned maxline;" .B " ..." .B "} base64_ctx;" .PP .ta \w'\fBvoid base64_encode('u .BI "void base64_encode(base64_ctx *" ctx , .BI " const void *" p ", size_t " sz , .BI " dstr *" d ); .BI "void base64_decode(base64_ctx *" ctx , .BI " const void *" p ", size_t " sz , .BI " dstr *" d ); .BI "void base64_init(base64_ctx *" ctx ); .PP .ta 2n .B "typedef struct {" .B " char *indent;" .B " unsigned maxline;" .B " ..." .B "} base32_ctx;" .PP .ta \w'\fBvoid base32_encode('u .BI "void base32_encode(base32_ctx *" ctx , .BI " const void *" p ", size_t " sz , .BI " dstr *" d ); .BI "void base32_decode(base32_ctx *" ctx , .BI " const void *" p ", size_t " sz , .BI " dstr *" d ); .BI "void base32_init(base32_ctx *" ctx ); .PP .ta 2n .B "typedef struct {" .B " char *indent;" .B " unsigned maxline;" .B " ..." .B "} hex_ctx;" .PP .ta \w'\fBvoid hex_encode('u .BI "void hex_encode(hex_ctx *" ctx , .BI " const void *" p ", size_t " sz , .BI " dstr *" d ); .BI "void hex_decode(hex_ctx *" ctx , .BI " const void *" p ", size_t " sz , .BI " dstr *" d ); .BI "void hex_init(hex_ctx *" ctx ); .fi . .\"-------------------------------------------------------------------------- .SH DESCRIPTION . The .BR base64 , .BR base32 , and .B hex functions perform encoding and decoding of arbitrary binary strings, as defined by RFC4648, but without error reporting. These functions are obsolete, and new applications should use the .BR codec (3) interface, which provides more encoding and decoding options, and proper error detection. .PP The interfaces to these sets of functions is very similar: in the following description, .I prefix stands for one of .BR base64 , .BR base32 , or .BR hex . .PP Before encoding or decoding a string, a .I context (of type .IB prefix _ctx \fR) must be initialized, by passing it to .IB prefix _init \fR. The context contains data which must be retained between calls to encode or decode substrings. The .IB prefix _init function sets up initial values for the data, and sets up defaults for the output formatting settings (see below). .PP Encoding of a string is performed by the .IB prefix _encode function. It is passed a pointer to a context block .IR ctx , the input substring to encode passed by address .I p and length .IR sz , and a pointer to a dynamic string .I d in which to write its output (see .BR dstr (3) for details on dynamic strings). Once all the input data has been passed through .IB prefix _encode it is necessary to flush the final few bytes of output. This is achieved by passing .I prefix _encode a null pointer as its source argument. It is an error to attempt to continue encoding after flushing output. .PP The output of the .IB prefix _encode function is formatted into lines using values from the context structure. The .B indent member is a pointer to a null-terminated string which is used to separate the output lines. The default indent string contains only a newline character. The .B maxline member gives the maximum length of line that .IB prefix _encode is allowed to produce. If this is not a multiple of 4, it is rounded up to the next highest multiple of four before use. A value of zero instructs .IB prefix _encode not to perform line splitting: the output will be a single (possibly very long) output line. The default maximum line length is 72 characters. You may set these parameters by direct assignment to the context structure once it has been initialized. .PP Decoding is performed similarly by the .IB prefix _decode function. The comments above about flushing output apply equally to decoding. .PP Decoding ignores all errors. In particular, whitespace is ignored, and in the case of Base64 and Base32 encodings, it also ignores .RB ` = ' characters in the string. . .\"-------------------------------------------------------------------------- .SH "SEE ALSO" . .BR codec (3), .BR dstr (3), .BR mLib (3). . .\"-------------------------------------------------------------------------- .SH AUTHOR . Mark Wooding, . .\"----- That's all, folks --------------------------------------------------