mdw@git.distorted.org.uk Git - mLib/blob - codec/base64.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for old-fashioned binary encoding and decoding
   4 .\"
   5 .\" (c) 1999, 2001, 2004, 2005, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH base64 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @base64_encode
  33 .\" @base64_decode
  34 .\" @base64_init
  35 .\" @base32_encode
  36 .\" @base32_decode
  37 .\" @base32_init
  38 .\" @hex_encode
  39 .\" @hex_decode
  40 .\" @hex_init
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .SH NAME
  44 base64, base32, hex \- obsolete binary encoding functions
  45 .
  46 .\"--------------------------------------------------------------------------
  47 .SH SYNOPSIS
  48 .
  49 .nf
  50 .B "#include <mLib/base64.h>"
  51 .B "#include <mLib/base32.h>"
  52 .B "#include <mLib/hex.h>"
  53 .PP
  54 .ta 2n
  55 .B "typedef struct {"
  56 .B "    char *indent;"
  57 .B "    unsigned maxline;"
  58 .B "    ..."
  59 .B "} base64_ctx;"
  60 .PP
  61 .ta \w'\fBvoid base64_encode('u
  62 .BI "void base64_encode(base64_ctx *" ctx ,
  63 .BI "   const void *" p ", size_t " sz ,
  64 .BI "   dstr *" d );
  65 .BI "void base64_decode(base64_ctx *" ctx ,
  66 .BI "   const void *" p ", size_t " sz ,
  67 .BI "   dstr *" d );
  68 .BI "void base64_init(base64_ctx *" ctx );
  69 .PP
  70 .ta 2n
  71 .B "typedef struct {"
  72 .B "    char *indent;"
  73 .B "    unsigned maxline;"
  74 .B "    ..."
  75 .B "} base32_ctx;"
  76 .PP
  77 .ta \w'\fBvoid base32_encode('u
  78 .BI "void base32_encode(base32_ctx *" ctx ,
  79 .BI "   const void *" p ", size_t " sz ,
  80 .BI "   dstr *" d );
  81 .BI "void base32_decode(base32_ctx *" ctx ,
  82 .BI "   const void *" p ", size_t " sz ,
  83 .BI "   dstr *" d );
  84 .BI "void base32_init(base32_ctx *" ctx );
  85 .PP
  86 .ta 2n
  87 .B "typedef struct {"
  88 .B "    char *indent;"
  89 .B "    unsigned maxline;"
  90 .B "    ..."
  91 .B "} hex_ctx;"
  92 .PP
  93 .ta \w'\fBvoid hex_encode('u
  94 .BI "void hex_encode(hex_ctx *" ctx ,
  95 .BI "   const void *" p ", size_t " sz ,
  96 .BI "   dstr *" d );
  97 .BI "void hex_decode(hex_ctx *" ctx ,
  98 .BI "   const void *" p ", size_t " sz ,
  99 .BI "   dstr *" d );
 100 .BI "void hex_init(hex_ctx *" ctx );
 101 .fi
 102 .
 103 .\"--------------------------------------------------------------------------
 104 .SH DESCRIPTION
 105 .
 106 The
 107 .BR base64 ,
 108 .BR base32 ,
 109 and
 110 .B hex
 111 functions perform encoding and decoding of arbitrary binary strings, as
 112 defined by RFC4648, but without error reporting.  These functions are
 113 obsolete, and new applications should use the
 114 .BR codec (3)
 115 interface, which provides more encoding and decoding options, and proper
 116 error detection.
 117 .PP
 118 The interfaces to these sets of functions is very similar: in
 119 the following description,
 120 .I prefix
 121 stands for one of
 122 .BR base64 ,
 123 .BR base32 ,
 124 or
 125 .BR hex .
 126 .PP
 127 Before encoding or decoding a string, a
 128 .I context
 129 (of type
 130 .IB prefix _ctx \fR)
 131 must be initialized, by passing it to
 132 .IB prefix _init \fR.
 133 The context contains data which must be retained between calls to encode
 134 or decode substrings.  The
 135 .IB prefix _init
 136 function sets up initial values for the data, and sets up defaults for
 137 the output formatting settings (see below).
 138 .PP
 139 Encoding of a string is performed by the
 140 .IB prefix _encode
 141 function.  It is passed a pointer to a context block
 142 .IR ctx ,
 143 the input substring to encode passed by address
 144 .I p
 145 and length
 146 .IR sz ,
 147 and a pointer to a dynamic string
 148 .I d
 149 in which to write its output (see
 150 .BR dstr (3)
 151 for details on dynamic strings).  Once all the input data has been
 152 passed through
 153 .IB prefix _encode
 154 it is necessary to flush the final few bytes of output.  This is
 155 achieved by passing
 156 .I prefix _encode
 157 a null pointer as its source argument.  It is an error to attempt to
 158 continue encoding after flushing output.
 159 .PP
 160 The output of the
 161 .IB prefix _encode
 162 function is formatted into lines using values from the context
 163 structure.  The
 164 .B indent
 165 member is a pointer to a null-terminated string which is used to
 166 separate the output lines.  The default indent string contains only a
 167 newline character.  The
 168 .B maxline
 169 member gives the maximum length of line that
 170 .IB prefix _encode
 171 is allowed to produce.  If this is not a multiple of 4, it is rounded
 172 up to the next highest multiple of four before use.  A value of zero
 173 instructs
 174 .IB prefix _encode
 175 not to perform line splitting: the output will be a single (possibly
 176 very long) output line.  The default maximum line length is 72
 177 characters.  You may set these parameters by direct assignment to the
 178 context structure once it has been initialized.
 179 .PP
 180 Decoding is performed similarly by the
 181 .IB prefix _decode
 182 function.  The comments above about flushing output apply equally to
 183 decoding.
 184 .PP
 185 Decoding ignores all errors.  In particular, whitespace is ignored, and
 186 in the case of Base64 and Base32 encodings, it also ignores
 187 .RB ` = '
 188 characters in the string.
 189 .
 190 .\"--------------------------------------------------------------------------
 191 .SH "SEE ALSO"
 192 .
 193 .BR codec (3),
 194 .BR dstr (3),
 195 .BR mLib (3).
 196 .
 197 .\"--------------------------------------------------------------------------
 198 .SH AUTHOR
 199 .
 200 Mark Wooding, <mdw@distorted.org.uk>
 201 .
 202 .\"----- That's all, folks --------------------------------------------------