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