summaryrefslogtreecommitdiffstats
path: root/doc/binary.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/binary.n')
-rw-r--r--doc/binary.n96
1 files changed, 94 insertions, 2 deletions
diff --git a/doc/binary.n b/doc/binary.n
index a850205..b3147cb 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -1,10 +1,11 @@
'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
+'\" Copyright (c) 2008 by Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: binary.n,v 1.40 2008/09/10 22:48:41 dkf Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.41 2008/10/07 22:31:42 dkf Exp $
'\"
.so man.macros
.TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -40,7 +41,86 @@ messages for example).
.SH "BINARY ENCODE AND DECODE"
.VS 8.6
.PP
-\fIFIXME!\fR
+When encoding binary data as a readable string, the starting binary data is
+passed to the \fBbinary encode\fR command, together with the name of the
+encoding to use and any encoding-specific options desired. Data which has been
+encoded can be converted back to binary form using \fBbinary decode\fR. The
+following formats and options are supported.
+.TP
+\fBbase64\fR
+.
+The \fBbase64\fB binary encoding is commonly used in mail messages and XML
+documents, and uses mostly upper and lower case letters and digits. It has the
+distinction of being able to be rewrapped arbitrarily without losing
+information.
+.RS
+.PP
+During encoding, the following options are supported:
+.TP
+\fB\-maxlen \fIlength\fR
+.
+Indicates that the output should be split into lines of no more than
+\fIlength\fR characters. By default, lines are not split.
+.TP
+\fB\-wrapchar \fIcharacter\fR
+.
+Indicates that, when lines are split because of the \fB\-maxlen\fR option,
+\fIcharacter\fR should be used to separate lines. By default, this is a
+newline character,
+.QW \en .
+.PP
+During decoding, the following options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters any characters that
+are not strictly part of the encoding itself. Otherwise it ignores them.
+.RE
+.TP
+\fBhex\fR
+.
+The \fBhex\fR binary encoding converts each byte to a pair of hexadecimal
+digits in big-endian form.
+.RS
+.PP
+No options are supported during encoding. During decoding, the following
+options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters any characters that
+are not strictly part of the encoding itself. Otherwise it ignores them.
+.RE
+.TP
+\fBuuencode\fR
+.
+The \fBuuencode\fR binary encoding used to be common for transfer of data
+between Unix systems and on USENET, but is less common these days, having been
+largely superceded by the \fBbase64\fR binary encoding.
+.RS
+.PP
+During encoding, the following options are supported:
+'\" This is wrong! The uuencode format had more complexity than this!
+.TP
+\fB\-maxlen \fIlength\fR
+.
+Indicates that the output should be split into lines of no more than
+\fIlength\fR characters. By default, lines are not split.
+.TP
+\fB\-wrapchar \fIcharacter\fR
+.
+Indicates that, when lines are split because of the \fB\-maxlen\fR option,
+\fIcharacter\fR should be used to separate lines. By default, this is a
+newline character,
+.QW \en .
+.PP
+During decoding, the following options are supported:
+.TP
+\fB\-strict\fR
+.
+Instructs the decoder to throw an error if it encounters any characters that
+are not strictly part of the encoding itself. Otherwise it ignores them.
+.RE
.VE 8.6
.SH "BINARY FORMAT"
.PP
@@ -798,7 +878,19 @@ proc \fIreadString\fR {channel} {
return [encoding convertfrom utf-8 $data]
}
.CE
+.PP
+This converts the contents of a file (named in the variable \fIfilename\fR) to
+base64 and prints them:
+.CS
+set f [open $filename rb]
+set data [read $f]
+close $f
+puts [\fBbinary encode\fR base64 \-maxlen 64 $data]
+.CE
.SH "SEE ALSO"
format(n), scan(n), tclvars(n)
.SH KEYWORDS
binary, format, scan
+'\" Local Variables:
+'\" mode: nroff
+'\" End: