chiark / gitweb /
Import buf from Catacomb; split out the dstr bits, and throw away the mp and
[mLib] / 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 base34 (3),
87 .BR base64 (3),
88 .BR dstr (3),
89 .BR mLib (3).
90 .SH AUTHOR
91 Mark Wooding, <mdw@distorted.org.uk>