Tcl Source Code

'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
'\"
'\" 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.1.2.3 1999/04/09 19:11:26 surles Exp $
'\" 
.so man.macros
.TH binary n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
binary \- Insert and extract fields from binary strings

\fIcount\fR is omitted, then one digit will be formatted.  If the
number of digits formatted does not end at a byte boundary, the
remaining bits of the last byte will be zeros.  For example,
.RS
.CS
\fBbinary format h3h* AB def\fR
.CE
will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR.
.RE
.IP \fBH\fR 5
This form is the same as \fBh\fR except that the digits are stored in
high-to-low order within each byte.  For example,
.RS
.CS
\fBbinary format H3H* ab DEF\fR
.CE
will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR.
.RE
.IP \fBc\fR 5
Stores one or more 8-bit integer values in the output string.  If no
\fIcount\fR is specified, then \fIarg\fR must consist of an integer
value; otherwise \fIarg\fR must consist of a list containing at least
\fIcount\fR integer elements.  The low-order 8 bits of each integer
are stored as a one-byte value at the cursor position.  If \fIcount\fR
is \fB*\fR, then all of the integers in the list are formatted.  If
the number of elements in the list is fewer than \fIcount\fR, then an
error is generated.  If the number of elements in the list is greater
than \fIcount\fR, then the extra elements are ignored.  For example,
.RS
.CS
\fBbinary format c3cc* {3 -3 128 1} 260 {2 5}\fR
.CE
will return a string equivalent to
\fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas
.CS
\fBbinary format c {2 5}\fR
.CE
will generate an error.
.RE
.IP \fBs\fR 5
This form is the same as \fBc\fR except that it stores one or more

the cursor position with the least significant byte stored first.  For
example,
.RS
.CS
\fBbinary format i3 {3 -3 65536 1}\fR
.CE
will return a string equivalent to 
\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR
.RE
.IP \fBI\fR 5
This form is the same as \fBi\fR except that it stores one or more one
or more 32-bit integers in big-endian byte order in the output string.
For example,
.RS
.CS
\fBbinary format I3 {3 -3 65536 1}\fR
.CE
will return a string equivalent to 
\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR
.RE
.IP \fBf\fR 5
This form is the same as \fBc\fR except that it stores one or more one
or more single-precision floating in the machine's native
representation in the output string.  This representation is not
portable across architectures, so it should not be used to communicate
floating point numbers across the network.  The size of a floating

stored in \fBvar1\fR and \fBvar2\fR left unmodified.
.RE
.IP \fBA\fR 5
This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
the scanned value before it is stored in the variable.  For example,
.RS
.CS
\fBbinary scan "abc efghi  \\000" A* var1\fR
.CE
will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR.
.RE
.IP \fBb\fR 5
The data is turned into a string of \fIcount\fR binary digits in
low-to-high order represented as a sequence of ``1'' and ``0''
characters.  The data bytes are scanned in first to last order with
the bits being taken in low-to-high order within each byte.  Any extra
bits in the last byte are ignored.  If \fIcount\fR is \fB*\fR, then
all of the remaining bits in \fBstring\fR will be scanned.  If
\fIcount\fR is omitted, then one bit will be scanned.  For example,
.RS
.CS
\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR
.CE
will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and
\fB1110000110100000\fR stored in \fBvar2\fR.
.RE
.IP \fBB\fR 5
This form is the same as \fBb\fR, except the bits are taken in
high-to-low order within each byte.  For example,
.RS
.CS
\fBbinary scan \\x70\\x87\\x05 B5B* var1 var2\fR
.CE
will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and
\fB1000011100000101\fR stored in \fBvar2\fR.
.RE
.IP \fBh\fR 5
The data is turned into a string of \fIcount\fR hexadecimal digits in
low-to-high order represented as a sequence of characters in the set

\fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR
.CE
will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and
\fB50\fR stored in \fBvar2\fR.
.RE
.IP \fBH\fR 5
This form is the same as \fBh\fR, except the digits are taken in
high-to-low order within each byte.  For example,
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR
.CE
will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and
\fB05\fR stored in \fBvar2\fR.
.RE