Infrastructure: Split the files into subdirectories.

[mLib] / codec / hex.3

diff --git a/codec/hex.3 b/codec/hex.3
new file mode 100644 (file)
index 0000000..b4e58b5
--- /dev/null
+++ b/codec/hex.3
@@ -0,0 +1,91 @@
+.\" -*-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>