twc - Tiny world clock in C! 🛠️

Fast, CLI world clock that displays time zone information using tz database to read valid tz entries.

It works similar to zdump(8), but it lets you format the output more precisely:

$ twc -h -f tools/samples/tz-small.conf
America/New York     2024-12-10  16:39:43  -0500
America/Los Angeles  2024-12-10  13:39:43  -0800
UTC                  2024-12-10  21:39:43  +0000
Europe/London        2024-12-10  21:39:43  +0000
Europe/Paris         2024-12-10  22:39:43  +0100
Asia/Tokyo           2024-12-11  06:39:43  +0900
Australia/Sydney     2024-12-11  08:39:43  +1100

Highlights

• 🚀 Fast - 5X times faster than date.¹ Only ≈ 8 ms for one entry, and ≈ 177 ms for ≈ 600 entries.
• 🔒 Robust - tested to work with all tz database entries, version 2024b.
• 📦 Self-contained - zero dependencies, ISO C17, lightweight (175 lines, 3235 bytes).

Getting Started

Prerequisites

If you are building twc, you'll need:

• A C compiler that supports C99 or later.
• A system with a working asprintf implementation.
• If asprintf is not present, you can use Neved4/asprintf.

Installing

If you have Homebrew installed, just run:

brew install Neved4/homebrew-tap/twc

Building

Clone the repository:

git clone https://github.com/Neved4/twc

Build the sources:

make twc

Alternatively, if you have zig installed:

zig cc twc.c -o twc

Usage

These are the options available:

twc [-h] [-f path] [-s format] [-t timezone] ...

Options:
  -f path
      Read config from path (default "$HOME/.config/twc/tz.conf")
  -h
      Print in human-readable format
  -s format
      Set desired time format (e.g. "%Y-%m-%d")
  -t timezone
      specific timezone (e.g. "Asia/Tokyo")

Examples:
  Print Tokyo date in a human-readable format with YY-MM-DD format:

    $ twc -h -s %Y-%m-%d -t Asia/Tokyo
    2024-01-02

  Print date in Los Angeles using an environment variable for the timezone:

    $ TZ=America/Los_Angeles twc
    2024-01-02T15:04:05-0800

Environment:
  TZ
    Timezone to use when displaying dates.
  XDG_CONFIG_HOME
    When defined, it will be used to store the tz.conf file.

Files:
  ~/.config/twc/tz.conf
    Stores tz database entries to be displayed.

See also:
    time(3), strftime(3), environ(7)

Docker

To compile the binary inside a Docker image, run:

docker build .

Compatibility

Runs on Linux, macOS and *BSD systems on x86_64 and arm64, and compiles with zig, clang, gcc, tcc and any other compiler that supports C17 or later.

Also builds on any C99 compiler on systems that supports and have asprintf().

Standards

twc is compatible with POSIX.1-2024² as well as C23³, and it outputs ISO 8601⁴ format.

See Also

Various zdump implementations:

• glibc - zdump.c
• apple - zdump.c
• FreeBSD - zdump.c
• OpenBSD - zdump.c
• Boruch Baum - zdump3

Acknowledgments

Special thanks to everybody who helped me with pointers and memory allocation, @navi, @enigmatico and @K4rakara for their code reviews, and thx to @lexiwitch, for getting me started.

License

twc is licensed under the terms of the MIT License.

See the LICENSE file for details.

Footnotes

1. cfr. date command takes ≈ 931 ms when iterating over ≈ 600 entries. Measured with hyperfine. ↩

2. IEEE Std 1003.1-2024: Standard for Information Technology — Portable Operating System Interface (POSIX®),
   ISO/IEC DIS 9945. URL: https://pubs.opengroup.org/onlinepubs/9799919799/ ↩

3. ISO/IEC 9899: Standard for Information Technology — Programming languages — C, ISO/IEC 9899:2023.
   URL: https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3096.pdf ↩

4. ISO 8601: Date and time — Representations for information interchange, ISO 8601-1:2019.
   URL: https://www.iso.org/obp/ui/#iso:std:iso:8601:-2:ed-1:v1:en ↩