[mLib] / man / base64.3

.\" -*-nroff-*-
.TH base64 3mLib "20 June 1999" mLib
.SH NAME
base64 \- conversion to and from base64 encoding
.SH SYNOPSIS
.nf
.B "#include <mLib/base64.h>

.BI "void base64_encode(base64_ctx *" ctx ,
.BI "                   const void *" p ", size_t " sz ,
.BI "                   dstr *" d );
.BI "void base64_decode(base64_ctx *" ctx ,
.BI "                   const void *" p ", size_t " sz ,
.BI "                   dstr *" d );
.BI "void base64_init(base64_ctx *" ctx );
.fi
.SH DESCRIPTION
The
.B base64
functions perform base64 encoding and decoding of arbitrary binary
strings.  The base64 encoding is defined by RFC2045.
.PP
Before encoding or decoding a string, a
.I context
(of type
.BR base64_ctx )
must be initialized, by passing it to
.BR base64_init .
The context contains data which must be retained between calls to encode
or decode substrings.  The
.B base64_init
function sets up initial values for the data, and sets up defaults for
the output formatting settings (see below).
.PP
Encoding of a string is performed by the
.B base64_encode
function.  It is passed a pointer to a context block
.IR ctx ,
the input substring to encode passed by address
.I p
and length
.IR sz ,
and a pointer to a dynamic string
.I d
in which to write its output (see
.BR dstr (3mLib)
for details on dynamic strings).  Once all the input data has been
passed through
.B base64_encode
it is necessary to flush the final few bytes of output.  This is
achieved by passing
.B base64_encode
a null pointer as its source argument.  It is an error to attempt to
continue encoding after flushing output.
.PP
The output of the
.B base64_encode
function is formatted into lines using values from the context
structure.  The
.B indent
member is a pointer to a null-terminated string which is used to
separate the output lines.  The default indent string contains only a
newline character.  The
.B maxline
member gives the maxmimum length of line that
.B base64_encode
is allowed to produce.  If this is not a multiple of 4, it is rounded
up to the next highest multiple of four before use.  A value of zero
instructs
.B base64_encode
not to perform line splitting: the output will be a single (possibly
very long) output line.  The default maximum line length is 72
characters.  You may set these parameters by direct assignment to the
context structure once it has been initialized.
.PP
Decoding is performed similarly by the
.B base64_decode
function.  The comments above about flushing output apply equally to
decoding.
.PP
Decoding ignores all whitespace characters in the encoded string.  It
also ignores
.RB ` = '
characters in the string and works out the final block length
automatically based on the input size.
.SH "SEE ALSO"
.BR dstr (3mLib).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>
Commit	Line	Data
b6b9d458	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>