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

   1 .\" -*-nroff-*-
   2 .TH base64 3mLib "20 June 1999" mLib
   3 .SH NAME
   4 base64 \- conversion to and from base64 encoding
   5 .SH SYNOPSIS
   6 .nf
   7 .B "#include <mLib/base64.h>
   8
   9 .BI "void base64_encode(base64_ctx *" ctx ,
  10 .BI "                   const void *" p ", size_t " sz ,
  11 .BI "                   dstr *" d );
  12 .BI "void base64_decode(base64_ctx *" ctx ,
  13 .BI "                   const void *" p ", size_t " sz ,
  14 .BI "                   dstr *" d );
  15 .BI "void base64_init(base64_ctx *" ctx );
  16 .fi
  17 .SH DESCRIPTION
  18 The
  19 .B base64
  20 functions perform base64 encoding and decoding of arbitrary binary
  21 strings.  The base64 encoding is defined by RFC2045.
  22 .PP
  23 Before encoding or decoding a string, a
  24 .I context
  25 (of type
  26 .BR base64_ctx )
  27 must be initialized, by passing it to
  28 .BR base64_init .
  29 The context contains data which must be retained between calls to encode
  30 or decode substrings.  The
  31 .B base64_init
  32 function sets up initial values for the data, and sets up defaults for
  33 the output formatting settings (see below).
  34 .PP
  35 Encoding of a string is performed by the
  36 .B base64_encode
  37 function.  It is passed a pointer to a context block
  38 .IR ctx ,
  39 the input substring to encode passed by address
  40 .I p
  41 and length
  42 .IR sz ,
  43 and a pointer to a dynamic string
  44 .I d
  45 in which to write its output (see
  46 .BR dstr (3mLib)
  47 for details on dynamic strings).  Once all the input data has been
  48 passed through
  49 .B base64_encode
  50 it is necessary to flush the final few bytes of output.  This is
  51 achieved by passing
  52 .B base64_encode
  53 a null pointer as its source argument.  It is an error to attempt to
  54 continue encoding after flushing output.
  55 .PP
  56 The output of the
  57 .B base64_encode
  58 function is formatted into lines using values from the context
  59 structure.  The
  60 .B indent
  61 member is a pointer to a null-terminated string which is used to
  62 separate the output lines.  The default indent string contains only a
  63 newline character.  The
  64 .B maxline
  65 member gives the maxmimum length of line that
  66 .B base64_encode
  67 is allowed to produce.  If this is not a multiple of 4, it is rounded
  68 up to the next highest multiple of four before use.  A value of zero
  69 instructs
  70 .B base64_encode
  71 not to perform line splitting: the output will be a single (possibly
  72 very long) output line.  The default maximum line length is 72
  73 characters.  You may set these parameters by direct assignment to the
  74 context structure once it has been initialized.
  75 .PP
  76 Decoding is performed similarly by the
  77 .B base64_decode
  78 function.  The comments above about flushing output apply equally to
  79 decoding.
  80 .PP
  81 Decoding ignores all whitespace characters in the encoded string.  It
  82 also ignores
  83 .RB ` = '
  84 characters in the string and works out the final block length
  85 automatically based on the input size.
  86 .SH "SEE ALSO"
  87 .BR dstr (3mLib).
  88 .SH AUTHOR
  89 Mark Wooding, <mdw@nsict.org>