Tcl flush Command

last modified October 20, 2026

The Tcl flush command forces output buffers to be written to their files or devices. It's essential for controlling when output appears, especially in interactive applications or when monitoring output in real-time.

Basic Definition

The flush command writes any buffered output for the specified file channel. By default, Tcl buffers output for efficiency, which can delay when output actually appears.

Syntax: flush channelId. The command takes a single argument - the channel identifier of the file or device to flush. It returns an empty string.

Basic Flush Usage

This example demonstrates the simplest use of flush to ensure immediate output.

basic_flush.tcl

puts -nonewline "Enter your name: "
flush stdout
gets stdin name
puts "Hello, $name!"

Here, flush stdout ensures the prompt appears before gets waits for input. A prompt without a newline stays in the buffer of a line-buffered terminal, and when stdout is a pipe or a file it is fully buffered, so without flush the prompt might not appear until after the input. Here, standard input is empty, so gets returns at once and the greeting has an empty name.

Flushing File Output

The flush command is also useful when writing to files to hand the buffered data to the operating system.

file_flush.tcl

set file [open "output.txt" w]
puts $file "First line"
flush $file
puts $file "Second line"
close $file

This writes to a file and flushes after the first line. The flush passes the first line to the operating system, so another process reading the file sees it before the file is closed, which is useful for log files. It does not force the data onto the physical disk; the operating system may still cache it. The close command flushes the remaining data automatically.

Flushing in a Loop

When writing output in a loop, flushing can provide real-time feedback.

loop_flush.tcl

for {set i 1} {$i <= 5} {incr i} {
    puts -nonewline "Progress: $i/5\r"
    flush stdout
    after 1000
}
puts "\nDone!"

This shows a progress counter that updates every second. The text has no newline, so a line-buffered terminal would hold it back; the flush ensures each update appears immediately and the carriage return \r overwrites the previous one.

Flushing a Pipe

The flush command only affects output. For a bidirectional channel it flushes the output side.

io_flush.tcl

set pipe [open "|cat" r+]
puts $pipe "input data"
flush $pipe
set output [gets $pipe]
puts "Received: $output"
close $pipe

This example opens a pipe to cat for reading and writing. The data is buffered by Tcl until we call flush, so the flush is what lets cat receive the input and echo it back; without it the gets call would wait forever. This is typical when communicating with an interactive program.

Flushing with Non-blocking Channels

On a non-blocking channel flush never waits; data that cannot be sent at once stays queued and the event loop sends it in the background.

nonblocking_flush.tcl

set sock [socket -async localhost 12345]
fconfigure $sock -blocking 0 -buffering line
puts $sock "Hello server"
flush $sock
fileevent $sock readable [list handleResponse $sock]

This configures a non-blocking socket with line buffering and sends a line. With line buffering each newline already flushes the output, so the explicit flush is redundant here; it is needed with the default full buffering. Nothing listens on port 12345, so this example fails with a "socket is not connected" error; the handleResponse procedure is also not defined here.

Flushing Standard Error

The flush command can be used with any output channel, including stderr.

stderr_flush.tcl

puts stderr "Error: Invalid input detected"
flush stderr
# Critical error handling continues...

Standard error is unbuffered by default, so the message appears immediately and this flush is harmless but not needed. It only matters if the buffering of stderr was changed with fconfigure.

Best Practices

Interactive prompts: Flush stdout after prompts that do not end in a newline.
Critical output: Flush log files after important messages so other processes can see them.
File operations: There is no need to flush before close; closing flushes automatically.
Network operations: Flush after sending complete messages.
Performance: Avoid excessive flushing in performance-critical code.

This tutorial covered the Tcl flush command with practical examples showing its usage in different scenarios.

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