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

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