diff options
Diffstat (limited to 'doc/binary.n')
| -rw-r--r-- | doc/binary.n | 138 |
1 files changed, 129 insertions, 9 deletions
diff --git a/doc/binary.n b/doc/binary.n index 95373fb..014704d 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -1,18 +1,23 @@ '\" '\" 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.39 2008/06/29 22:28:24 dkf Exp $ -'\" -.so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME binary \- Insert and extract fields from binary strings .SH SYNOPSIS +.VS 8.6 +\fBbinary decode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR +.br +\fBbinary encode \fIformat\fR ?\fI\-option value ...\fR? \fIdata\fR +.br +.VE 8.6 \fBbinary format \fIformatString \fR?\fIarg arg ...\fR? .br \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR? @@ -20,12 +25,110 @@ binary \- Insert and extract fields from binary strings .SH DESCRIPTION .PP This command provides facilities for manipulating binary data. The -first form, \fBbinary format\fR, creates a binary string from normal +subcommand \fBbinary format\fR creates a binary string from normal Tcl values. For example, given the values 16 and 22, on a 32-bit architecture, it might produce an 8-byte binary string consisting of -two 4-byte integers, one for each of the numbers. The second form of -the command, \fBbinary scan\fR, does the opposite: it extracts data +two 4-byte integers, one for each of the numbers. The subcommand +\fBbinary scan\fR, does the opposite: it extracts data from a binary string and returns it as ordinary Tcl string values. +.VS 8.6 +The \fBbinary encode\fR and \fBbinary decode\fR subcommands convert +binary data to or from string encodings such as base64 (used in MIME +messages for example). +.VE 8.6 +.PP +Note that other operations on binary data, such as taking a subsequence of it, +getting its length, or reinterpreting it as a string in some encoding, are +done by other Tcl commands (respectively \fBstring range\fR, +\fBstring length\fR and \fBencoding convertfrom\fR in the example cases). A +binary string in Tcl is merely one where all the characters it contains are in +the range \eu0000\-\eu00FF. +.SH "BINARY ENCODE AND DECODE" +.VS 8.6 +.PP +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\fR 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 whitespace characters. 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 whitespace characters. 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 superseded by the \fBbase64\fR binary encoding. +.RS +.PP +During encoding, the following options are supported (though changing them may +produce files that other implementations of decoders cannot process): +.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 split every 61 characters, and +this must be in the range 3 to 85 due to limitations in the encoding. +.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 unexpected whitespace +characters. Otherwise it ignores them. +.PP +Note that neither the encoder nor the decoder handle the header and footer of +the uuencode format. +.RE +.VE 8.6 .SH "BINARY FORMAT" .PP The \fBbinary format\fR command generates a binary string whose layout @@ -44,7 +147,7 @@ is a non-negative decimal integer or \fB*\fR, which normally indicates that all of the items in the value are to be used. If the number of arguments does not match the number of fields in the format string that consume arguments, then an error is generated. The flag character -is ignored for for \fBbinary format\fR. +is ignored for \fBbinary format\fR. .PP Here is a small example to clarify the relation between the field specifiers and the arguments: @@ -531,9 +634,10 @@ reverse (low-to-high) order within each byte. For example, .CE will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and \fB502143\fR stored in \fIvar2\fR. -.RE +.PP Note that most code that wishes to parse the hexadecimal digits from multiple bytes in order should use the \fBH\fR format. +.RE .IP \fBc\fR 5 The data is turned into \fIcount\fR 8-bit signed integers and stored in the corresponding variable as a list. If \fIcount\fR is \fB*\fR, @@ -763,6 +867,7 @@ architectures, use their textual representation (as produced by .PP This is a procedure to write a Tcl string to a binary-encoded channel as UTF-8 data preceded by a length word: +.PP .CS proc \fIwriteString\fR {channel string} { set data [encoding convertto utf-8 $string] @@ -773,6 +878,7 @@ proc \fIwriteString\fR {channel string} { .PP This procedure reads a string from a channel that was written by the previously presented \fIwriteString\fR procedure: +.PP .CS proc \fIreadString\fR {channel} { if {![\fBbinary scan\fR [read $channel 4] I length]} { @@ -782,7 +888,21 @@ 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: +.PP +.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) +encoding(n), format(n), scan(n), string(n), tcl_platform(n) .SH KEYWORDS binary, format, scan +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |