Tcl clock Command

last modified October 20, 2026

The Tcl clock command provides comprehensive time and date handling capabilities. It can convert between different time formats, perform date arithmetic, and format time values. The command is essential for any time- related operations in Tcl.

Basic Definition

The clock command operates on seconds since the Unix epoch (Jan 1, 1970). It can convert between human-readable formats and machine time. The command supports various subcommands for different operations.

Common subcommands include clock seconds, clock format, and clock scan. These handle getting current time, formatting time values, and parsing time strings respectively.

Getting Current Time

The simplest use of clock is to get the current time in seconds. This demonstrates the basic time retrieval functionality.

clock_seconds.tcl

set current_time [clock seconds]
puts "Current time in seconds since epoch: $current_time"

This code gets the current time as seconds since the Unix epoch. The value represents the number of seconds since January 1, 1970 (UTC). This is the fundamental time representation in Tcl.

Formatting Time Values

The clock format subcommand converts seconds to human-readable strings. It supports customizable formatting using conversion specifiers.

clock_format.tcl

set now [clock seconds]
set formatted [clock format $now -format "%Y-%m-%d %H:%M:%S"]
puts "Formatted time: $formatted"

This example shows how to format the current time into a standard date-time string. The format string uses %Y for year, %m for month, %d for day, etc. This is useful for displaying timestamps to users.

Parsing Time Strings

The clock scan subcommand converts human-readable time strings into seconds. With -format it parses exactly the given pattern; without it, Tcl guesses the format of a free-form date.

clock_scan.tcl

set time_str "2025-04-15 14:30:00"
set seconds [clock scan $time_str -format "%Y-%m-%d %H:%M:%S"]
puts "Time in seconds: $seconds"

This code parses a formatted date-time string back into seconds. The format specifier must match the input string format. The string has no time zone, so it is interpreted in the local time zone and the number differs between machines; add -timezone :UTC (or -gmt 1) for a fixed result. This is useful for processing user input or log files.

Date Arithmetic

The clock add subcommand performs date arithmetic by adding or subtracting time intervals. It handles month and year boundaries correctly.

clock_add.tcl

set now [clock seconds]
set future [clock add $now 2 weeks]
puts "Now: [clock format $now]"
puts "Two weeks later: [clock format $future]"

This example adds two weeks to the current time. The command automatically adjusts for month transitions. Valid units include years, months, weeks, days, hours, minutes, and seconds. Adding weeks, days or months keeps the local wall-clock time, so the output keeps 19:49:48 even though the time zone changes from CEST to CET in between; adding 336 hours would shift it by an hour.

Time Zone Handling

The clock command can work with different time zones. The -timezone option specifies which time zone to use.

clock_timezone.tcl

set now [clock seconds]
set ny_time [clock format $now -timezone "America/New_York"]
set london_time [clock format $now -timezone "Europe/London"]
puts "New York: $ny_time"
puts "London: $london_time"

This code displays the current time in two different time zones. The time zone names follow the Olson (IANA) database format. Without -format, clock format uses the pattern "%a %b %d %H:%M:%S %Z %Y", which is why the zone abbreviation appears. This is useful for applications that need to display times in multiple locations.

Comparing Times

Times can be compared directly when represented as seconds. This allows for easy determination of which event occurred first.

clock_compare.tcl

set time1 [clock scan "2025-01-01"]
set time2 [clock scan "2025-06-01"]
if {$time1 < $time2} {
    puts "January comes before June"
}

This example compares two dates by converting them to seconds first. The comparison operators work directly on these numeric values. Without -format the dates are parsed in the local time zone at midnight. This technique is useful for sorting or filtering events by time.

Best Practices

Consistency: Use UTC for storage and convert for display.
Formatting: Prefer ISO 8601 format (%Y-%m-%d) for storage.
Time zones: Always specify time zones for user-facing times.
Leap seconds: Be aware Tcl doesn't handle leap seconds.
Parsing: Give clock scan an explicit -format, because free-form parsing guesses.

This tutorial covered the Tcl clock command with practical examples showing its usage for time handling and manipulation.

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