Tcl binary Command

last modified October 20, 2026

The Tcl binary command provides operations for creating and manipulating binary data. It's essential for working with binary files, network protocols, and data encoding/decoding.

Basic Definition

The binary command converts between different binary representations and performs binary data operations. It has several subcommands for specific operations.

Syntax: binary format formatString ?arg arg...? creates binary data. binary scan string formatString ?varName varName...? parses binary data and returns the number of values it stored. Other subcommands are binary encode format data and binary decode format data, where the format is base64, hex or uuencode.

Binary Format Example

This example shows how to create binary data from different value types.

binary_format.tcl

set binaryData [binary format "isss" 42 7 15 300]
puts "Binary data length: [string length $binaryData]"

This creates binary data containing a 32-bit integer (42) and three 16-bit shorts (7, 15, 300), all in little-endian byte order. The format string "isss" specifies the types. The result is 4 + 3 × 2 = 10 bytes, which is the length that is printed.

Binary Scan Example

This demonstrates parsing binary data into variables using format specifiers.

binary_scan.tcl

set data "\x2a\x00\x00\x00\x07\x00\x0f\x00\x2c\x01"
binary scan $data "isss" intVal short1 short2 short3
puts "Parsed values: $intVal, $short1, $short2, $short3"

The ten bytes are parsed into one 32-bit integer and three 16-bit shorts, all little-endian. The format string "isss" must match the data layout. The values are stored in the specified variables.

Base64 Encoding

The binary command can encode and decode data in Base64 format.

binary_base64.tcl

set text "Hello, Tcl!"
set encoded [binary encode base64 $text]
set decoded [binary decode base64 $encoded]
puts "Encoded: $encoded"
puts "Decoded: $decoded"

This example encodes a string to Base64 and then decodes it back. The encode and decode subcommands handle the conversion. Base64 is useful for sending binary data through text-only media. The input of binary encode is treated as bytes, so a string with non-ASCII characters should first be converted, for example with encoding convertto utf-8.

Hex Encoding

Hexadecimal encoding represents binary data as ASCII hexadecimal digits.

binary_hex.tcl

set binary "\x48\x65\x6c\x6c\x6f"
set hex [binary encode hex $binary]
set back [binary decode hex $hex]
puts "Hex: $hex"
puts "Original: $back"

The binary data "Hello" is converted to its hexadecimal representation. The encode hex and decode hex subcommands perform the conversion. Hex is useful for debugging binary data.

Binary String Operations

The a format of binary format and binary scan handles fixed-length byte strings.

binary_string.tcl

set str1 "Hello"
set str2 "World"
set combined [binary format "a5a5" $str1 $str2]
binary scan $combined "a5a5" part1 part2
puts "Combined: $part1$part2"

This combines two strings into a binary format and then splits them back. The "a5" specifier stores exactly five bytes, padding a shorter value with null bytes and truncating a longer one. When scanning, "a" keeps the padding, while "A" removes trailing spaces and nulls. This technique is useful for binary protocols with fixed-width fields.

Floating Point Numbers

The binary command can handle floating-point numbers in binary.

binary_float.tcl

set pi 3.14159
set binaryPi [binary format "d" $pi]
binary scan $binaryPi "d" recoveredPi
puts "Original: $pi, Recovered: $recoveredPi"

This stores a double-precision floating-point number in binary and reads it back. The "d" format specifier handles 64-bit floating-point numbers in the native byte order of the machine (use "q" or "Q" for a fixed little- or big-endian order). Because the full double is stored, the value is recovered exactly.

Best Practices

Format Strings: Use correct format specifiers for data types.
Endianness: Choose the byte order explicitly: lowercase s, i, w are little-endian, uppercase S, I, W big-endian.
Error Handling: Check the count returned by binary scan; it is less than expected when the data is too short.
Text: Convert text to bytes with encoding convertto before encoding or writing it.
Documentation: Document binary formats for maintenance.

This tutorial covered the Tcl binary command with practical examples showing its usage for binary data manipulation and conversion.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Tcl Tutorials.

Ebooks