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