From e3b5f32e06231210d65b0a53599151551954db7e Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Sat, 29 Nov 2003 11:59:01 +0000 Subject: [PATCH] Document hex encoding. Organization: Straylight/Edgeware From: mdw --- man/hex.3 | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 man/hex.3 diff --git a/man/hex.3 b/man/hex.3 new file mode 100644 index 0000000..b2cee51 --- /dev/null +++ b/man/hex.3 @@ -0,0 +1,90 @@ +.\" -*-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 " + +.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 base64 (3), +.BR dstr (3), +.BR mLib (3). +.SH AUTHOR +Mark Wooding, -- [mdw]