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