Trf: The binio command
Author: Andreas Kupries,,,

# Trf commands: binio

[ Misc commands | Sitemap ]

The `binio` command has three sub commands:

binio copy inChannel outChannel ?count?
  Copies from inChannel to outChannel, up to the number of bytes indicated by the optional count argument or up to end of file on inChannel. inChannel must have been opened for reading and outChannel must have been opened for writing. This operation returns the number of bytes copied, or -1 on error.
binio pack outChannel format ?data1 data2 ...?
  Packs binary data onto outChannel, a channel that must have been opened for writing. The format argument determines how the optional data1 through datan arguments are interpreted. This operation returns the number of data items successfully packed on outChannel or -1 if an error occurred. If an error occurred, it is possible that some output has already occurred. The various specifications that can appear in the format string are explained below. This operation reorders the bytes of each datum to match the order expected on outChannel if its byte order is different from that of the architecture on which the Tcl command is being executed.
binio unpack inChannel format ?var1 var2 ...?
  Unpacks binary data from inChannel into the named variables. The inChannel argument must denote a channel opened for reading. The format argument determines how the data obtained from the channel is translated into string representation and stored in the var1 through varn variables. If any of the variables are not initialized then the command creates them as local variables. This operation returns the number of data items successfully unpacked from inChannel or -1 if an error occurred. If -1 is returned, it is possible that some input may already have occurred. The various format specifications that can appear in the format string are explained below. This operation reorders the bytes of each datum to match the byte order expected on the architecture on which the command is executed if it is different from the byte order that is in effect on inChannel.

And now the table of the format specifiers available to `binio`. It includes a comparison to `binary format` of tcl 8.0 too.

Format | Meaning | Meaning in 8.0
a | -- | string, '\0'-padded
A | -- | string, space-padded
b | -- | binary digits, low-2-high
B | -- | binary digits, high-2-low
c | signed int, 8 bit (char) | see left
C | unsigned int, 8 bit | --
d | signed int, 32 bit | floating number, 64 bit
D | signed int, 16 bit | --
f | floating number, 32 bit | see left
F | floating number, 64 bit | --
h | -- | hex digits, low-2-high
H | -- | hex digits, high-2-low
i | -- | signed int, 32 bit, little endian
I | -- | signed int, 32 bit, big-endian
l | signed int, 64 bit | --
L | unsigned int, 64 bit | --
o | signed int, 32 bit, octal | --
O | signed int, 16 bit, octal | --
s | string, '\0'-terminated | signed int, 16 bit, little-endian
S | -- | signed int, 16 bit, big-endian
u | unsigned int, 32 bit | --
U | unsigned int, 32 bit | --
x | signed int, 32 bit, hex | '\0'
X | signed int, 16 bit, hex | Set cursor relative
@ | -- | Set cursor absolute

There is a more subtle difference too. In contrast to `binio`, which uses the channel byteorder to determine the endianness of the written data `binary format` requires an explicit specification. In general `binary format` is much nearer to the perl equivalent ((un)pack), despite the names.

Last update at Mon Aug 20 22:52:27 PDT 2001