zdump(8)

🌸 zdump(8) 🌸

✨ NAME ✨

okay so the manual name is zdump, and it's a timezone dumper 🕰️💖

💅 SYNOPSIS 💅

zdump [ option ... ] [ timezone ... ]

🧚 DESCRIPTION 🧚

okay bestie, the zdump program prints the current time in every timezone you name on the command line. literally that's it, it's giving clarity ✨

🎀 OPTIONS 🎀

• --version — slide in and get the version info, then it peaces out 👋
• --help — get a quick usage message and it dips 🙈
• -i — get a description of the time intervals 🦋. for each timezone on the command line, you get an interval-format description of that zone. check INTERVAL FORMAT below for the tea ☕
• -v — the verbose version of the time intervals 🔍. for each timezone you list, it prints the times at the two extreme time values, plus the times (if they exist) at and just past the edges of the years that localtime(3) and gmtime(3) can actually represent. it also prints the times both one second before and exactly at each time discontinuity it finds. every line gets isdst=D tacked on, where D is positive, zero, or negative depending on whether that moment is daylight saving time, standard time, or an unknown time type. every line also gets gmtoff=N if the local time is known to be N seconds east of Greenwich 🌍
• -V — basically -v, but it skips the extreme time and year stuff 🙅‍♀️. this makes the output way easier to compare with other implementations that represent time differently 🫶
• -c [loyear,]hiyear — cut off the interval output at the year(s) you give 📅. cutoff times use the proleptic Gregorian calendar with year 0, and Universal Time (UT) that ignores leap seconds. the cutoffs happen at the start of each year, where the lower bound is inclusive and the upper bound is exclusive 💜. for example, -c 1970,2070 picks transitions on or after 1970-01-01 00:00:00 UTC and before 2070-01-01 00:00:00 UTC. the default cutoff is -500,2500 ✨
• -t [lotime,]hitime — same vibe as -c, but you cut off by time instead of year ⏰. the times are given in decimal seconds since 1970-01-01 00:00:00 Coordinated Universal Time (UTC). the timezone decides whether the count includes leap seconds. just like with -c, the lower bound is inclusive and the upper bound is exclusive 🌈

🦋 INTERVAL FORMAT 🦋

okay so the interval format is a compact text representation that's meant to be readable by both humans and machines 🤖💖. it starts with an empty line, then a line TZ=string, where string is a double-quoted string naming the timezone 🌏. next comes a second line, - - interval, which describes the time interval before the first transition (if there is one) 🕰️. after that you get zero or more lines in the form date time interval, one for each transition time and the interval that follows it. fields are separated by single tabs 🫧

dates are in yyyy-mm-dd format, and times are in 24-hour hh:mm:ss format where hh<24. times are in local time immediately after the transition ⏳

a time interval description has three parts: a UT offset in signed ±hhmmss format, a time zone abbreviation, and an isdst flag. if the abbreviation is the same as the UT offset, it gets left out. other abbreviations are double-quoted strings, unless they're made of one or more alphabetic characters 💅. the isdst flag is left out for standard time. otherwise it's a decimal integer: unsigned and positive (usually 1) for daylight saving time, and negative for unknown 🌙

in times, and in UT offsets whose absolute value is under 100 hours, the seconds get dropped if they're zero, and the minutes get dropped too if they're also zero ✂️. positive UT offsets are east of Greenwich 🌍. the UT offset -00 is a UT placeholder for areas where the real offset isn't specified. by convention, this shows up when the UT offset is zero and the time zone abbreviation starts with - or is zzz 🫠

inside double-quoted strings, escape sequences stand in for unusual characters 💫. the escapes are \s for space, and \", \\, \f, \n, \r, \t, and \v, which all mean what they mean in the C programming language 🎀. for example, the double-quoted string "CET\s\"\\" stands for the character sequence CET "\ 🍓

here's an example of the output, with the leading empty line left out. (it's shown with tab stops set far enough apart so the tabbed columns line up 📏)

  TZ="Pacific/Honolulu"
  -           -         -103126  LMT
  1896-01-13  12:01:26  -1030    HST
  1933-04-30  03        -0930    HDT  1
  1933-05-21  11        -1030    HST
  1942-02-09  03        -0930    HWT  1
  1945-08-14  13:30     -0930    HPT  1
  1945-09-30  01        -1030    HST
  1947-06-08  02:30     -10      HST

so here, local time starts 10 hours, 31 minutes and 26 seconds west of UT, and it's a standard time abbreviated LMT 😭. right after the first transition, the date is 1896-01-13 and the time is 12:01:26, and the interval that follows is 10.5 hours west of UT, a standard time abbreviated HST 🌴. right after the second transition, the date is 1933-04-30 and the time is 03:00:00, and the next interval is 9.5 hours west of UT, abbreviated HDT, and it's daylight saving time ☀️. right after the last transition, the date is 1947-06-08 and the time is 02:30:00, and the interval that follows is 10 hours west of UT, a standard time abbreviated HST 💖

here are some excerpts from another example:

  TZ="Europe/Astrakhan"
  -           -         +031212  LMT
  1924-04-30  23:47:48  +03
  1930-06-21  01        +04
  1981-04-01  01        +05           1
  1981-09-30  23        +04
  ...
  2014-10-26  01        +03
  2016-03-27  03        +04

this timezone is east of UT, so its UT offsets are positive 🌅. a lot of its abbreviations are also left out, because they just repeat the UT offset text 🫶

🙈 LIMITATIONS 🙈

⚠️ time discontinuities are found by sampling the results from localtime(3) every twelve hours. this works in all real-world cases, but you can build artificial time zones where it fails ⚠️

in the -v and -V output, "UT" means the value returned by gmtime(3). that uses UTC for modern timestamps, and some other UT flavor for timestamps from before UTC was introduced 🕰️. right now, the output doesn't try to say "UTC" for newer timestamps and "UT" for older ones 🤷‍♀️. part of the reason is that the exact date UTC got introduced is kind of a mess 🫠

🔗 SEE ALSO 🔗

tzfile(5), zic(8) 💜

---

bestie, that's the whole page 🥹💖 it's from the Time Zone Database and it's all about zdump(8) ✨👑