chiark - git - mdw - mLib/blob - codec/base64.3

   1 .\" -*-nroff-*-
   2 .TH base64 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 base64, base32, hex \- obsolete binary encoding functions
   5 .\" @base64_encode
   6 .\" @base64_decode
   7 .\" @base64_init
   8 .\" @base32_encode
   9 .\" @base32_decode
  10 .\" @base32_init
  11 .\" @hex_encode
  12 .\" @hex_decode
  13 .\" @hex_init
  14 .SH SYNOPSIS
  15 .nf
  16 .B "#include <mLib/base64.h>"
  17 .B "#include <mLib/base32.h>"
  18 .B "#include <mLib/hex.h>"
  19
  20 .B "typedef struct {"
  21 .B "\h'4n'char *indent;"
  22 .B "\h'4n'unsigned maxline;"
  23 .B "\h'4n'..."
  24 .B "} base64_ctx;"
  25
  26 .BI "void base64_encode(base64_ctx *" ctx ,
  27 .BI "                   const void *" p ", size_t " sz ,
  28 .BI "                   dstr *" d );
  29 .BI "void base64_decode(base64_ctx *" ctx ,
  30 .BI "                   const void *" p ", size_t " sz ,
  31 .BI "                   dstr *" d );
  32 .BI "void base64_init(base64_ctx *" ctx );
  33
  34 .B "typedef struct {"
  35 .B "\h'4n'char *indent;"
  36 .B "\h'4n'unsigned maxline;"
  37 .B "\h'4n'..."
  38 .B "} base32_ctx;"
  39
  40 .BI "void base32_encode(base32_ctx *" ctx ,
  41 .BI "                   const void *" p ", size_t " sz ,
  42 .BI "                   dstr *" d );
  43 .BI "void base32_decode(base32_ctx *" ctx ,
  44 .BI "                   const void *" p ", size_t " sz ,
  45 .BI "                   dstr *" d );
  46 .BI "void base32_init(base32_ctx *" ctx );
  47
  48 .B "typedef struct {"
  49 .B "\h'4n'char *indent;"
  50 .B "\h'4n'unsigned maxline;"
  51 .B "\h'4n'..."
  52 .B "} hex_ctx;"
  53
  54 .BI "void hex_encode(hex_ctx *" ctx ,
  55 .BI "                const void *" p ", size_t " sz ,
  56 .BI "                dstr *" d );
  57 .BI "void hex_decode(hex_ctx *" ctx ,
  58 .BI "                const void *" p ", size_t " sz ,
  59 .BI "                dstr *" d );
  60 .BI "void hex_init(hex_ctx *" ctx );
  61 .fi
  62 .SH DESCRIPTION
  63 The
  64 .BR base64 ,
  65 .BR base32 ,
  66 and
  67 .B hex
  68 functions perform encoding and decoding of arbitrary binary strings, as
  69 defined by RFC4648, but without error reporting.  These functions are
  70 obsolete, and new applications should use the
  71 .BR codec (3)
  72 interface, which provides more encoding and decoding options, and proper
  73 error detection.
  74 .PP
  75 The interfaces to these sets of functions is very similar: in
  76 the following description,
  77 .I prefix
  78 stands for one of
  79 .BR base64 ,
  80 .BR base32 ,
  81 or
  82 .BR hex .
  83 .PP
  84 Before encoding or decoding a string, a
  85 .I context
  86 (of type
  87 .IB prefix _ctx \fR)
  88 must be initialized, by passing it to
  89 .IB prefix _init \fR.
  90 The context contains data which must be retained between calls to encode
  91 or decode substrings.  The
  92 .IB prefix _init
  93 function sets up initial values for the data, and sets up defaults for
  94 the output formatting settings (see below).
  95 .PP
  96 Encoding of a string is performed by the
  97 .IB prefix _encode
  98 function.  It is passed a pointer to a context block
  99 .IR ctx ,
 100 the input substring to encode passed by address
 101 .I p
 102 and length
 103 .IR sz ,
 104 and a pointer to a dynamic string
 105 .I d
 106 in which to write its output (see
 107 .BR dstr (3)
 108 for details on dynamic strings).  Once all the input data has been
 109 passed through
 110 .IB prefix _encode
 111 it is necessary to flush the final few bytes of output.  This is
 112 achieved by passing
 113 .I prefix _encode
 114 a null pointer as its source argument.  It is an error to attempt to
 115 continue encoding after flushing output.
 116 .PP
 117 The output of the
 118 .IB prefix _encode
 119 function is formatted into lines using values from the context
 120 structure.  The
 121 .B indent
 122 member is a pointer to a null-terminated string which is used to
 123 separate the output lines.  The default indent string contains only a
 124 newline character.  The
 125 .B maxline
 126 member gives the maximum length of line that
 127 .IB prefix _encode
 128 is allowed to produce.  If this is not a multiple of 4, it is rounded
 129 up to the next highest multiple of four before use.  A value of zero
 130 instructs
 131 .IB prefix _encode
 132 not to perform line splitting: the output will be a single (possibly
 133 very long) output line.  The default maximum line length is 72
 134 characters.  You may set these parameters by direct assignment to the
 135 context structure once it has been initialized.
 136 .PP
 137 Decoding is performed similarly by the
 138 .IB prefix _decode
 139 function.  The comments above about flushing output apply equally to
 140 decoding.
 141 .PP
 142 Decoding ignores all errors.  In particular, whitespace is ignored, and
 143 in the case of Base64 and Base32 encodings, it also ignores
 144 .RB ` = '
 145 characters in the string.
 146 .SH "SEE ALSO"
 147 .BR codec (3),
 148 .BR dstr (3),
 149 .BR mLib (3).
 150 .SH AUTHOR
 151 Mark Wooding, <mdw@distorted.org.uk>