[mLib] / man / hex.3

.\" -*-nroff-*-
.TH hex 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
base64 \- conversion to and from base64 encoding
.\" @hex_encode
.\" @hex_decode
.\" @hex_init
.SH SYNOPSIS
.nf
.B "#include <mLib/hex.h>"

.BI "void hex_encode(hex_ctx *" ctx ,
.BI "                const void *" p ", size_t " sz ,
.BI "                dstr *" d );
.BI "void hex_decode(hex_ctx *" ctx ,
.BI "                const void *" p ", size_t " sz ,
.BI "                dstr *" d );
.BI "void hex_init(hex_ctx *" ctx );
.fi
.SH DESCRIPTION
The
.B hex
functions perform hex encoding and decoding of arbitrary binary
strings.
.PP
Before encoding or decoding a string, a
.I context
(of type
.BR hex_ctx )
must be initialized, by passing it to
.BR hex_init .
The context contains data which must be retained between calls to encode
or decode substrings.  The
.B hex_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 hex_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 (3)
for details on dynamic strings).  Once all the input data has been
passed through
.B hex_encode
it is necessary to flush the final few bytes of output.  This is
achieved by passing
.B hex_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 hex_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 maximum length of line that
.B hex_encode
is allowed to produce.  If this is not a multiple of 2, it is rounded
up to the next highest multiple of two before use.  A value of zero
instructs
.B hex_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 hex_decode
function.  The comments above about flushing output apply equally to
decoding.
.PP
Decoding ignores all whitespace characters in the encoded string.
.SH "SEE ALSO"
.BR base34 (3),
.BR base64 (3),
.BR dstr (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
e3b5f32e	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"
1c4fa429	86	.BR base34 (3),
e3b5f32e	87	.BR base64 (3),
	88	.BR dstr (3),
	89	.BR mLib (3).
	90	.SH AUTHOR
9b5ac6ff	91	Mark Wooding, <mdw@distorted.org.uk>