SYSTEMD.TIME(7)

๐Ÿ“ฆ
version 262.1 ยท 15 versions
, in arch rolling

โœจ systemd.time โœจ โ€” like, the whole vibe of time and dates in systemd.time(7)

okay bestie, sit down, grab a boba ๐Ÿง‹, because we're about to talk about time. and dates. and durations. and yes, it's systemd.time, the manual page that explains how the systemd girlies read and write clock stuff.

๐Ÿ’– NAME ๐Ÿ’–

systemd.time โ€” Time and date specifications. that's the whole assignment, periodt.

๐ŸŒธ DESCRIPTION ๐ŸŒธ

so in systemd, there are three little besties you need to know about: timestamps, time spans, and calendar events. they're all displayed and can be specified using closely related syntaxes โ€” like, they're cousins, not twins, iykyk.

๐Ÿฆ‹ DISPLAYING TIME SPANS ๐Ÿฆ‹

okay so a time span is a duration โ€” like, "how long does this thing last", not "what time does it start". when systemd shows you one, it gives you a space-separated series of time values, each one wearing a little time-unit accessory. example time:

2h 30min

and the way you read that? you add up all the values. so 2h 30min = 150 minutes. no cap. ๐Ÿ’…

also, the display is locale-independent โ€” meaning it doesn't care what language your system speaks, it only ever uses English names for the time units. the formatting ate and left no crumbs.

๐ŸŽ€ PARSING TIME SPANS ๐ŸŽ€

when systemd is reading a time span, it accepts the exact same syntax. and honestly? the spaces between the parts are optional โ€” she's flexible like that. ๐Ÿ™ˆ

these are the time units she understands, bestie, memorize them:

  • usec, us, ฮผs
  • msec, ms
  • seconds, second, sec, s
  • minutes, minute, min, m
  • hours, hour, hr, h
  • days, day, d
  • weeks, week, w
  • months, month, M โ€” and this one is defined as 30.44 days
  • years, year, y โ€” and this one is defined as 365.25 days
โš ๏ธ heads up: if you don't specify a unit, it generally assumes seconds โ€” but there are some exceptions, and those are marked as such wherever they show up. also, in a few cases "ns" and "nsec" are accepted too, but only where the granularity of the time span actually allows it.

parsing is generally locale-independent, so non-English unit names? not accepted. sorry to the multilingual girlies ๐Ÿ˜ญ.

here are some valid time span examples, look how cute they are:

2 h
2hours
48hr
1y 12month
55s500ms
300ms20s 5day

you can use the timespan command of systemd-analyze(1) to normalise a textual time span for testing and validation purposes. she's your girl for double-checking. ๐Ÿซถ

okay so here's a lil lore drop that lowkey matters: internally, systemd usually runs on microsecond time granularity, but the default time unit in user-configurable time spans is usually seconds (see above bestie, I told you). this disparity becomes visible when you compare the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus properties โ€” which, btw, are exactly what systemctl(1)'s show command displays. the high-level ones are typically suffixed with ...Sec to signal the default unit of seconds, and the low-level ones are typically suffixed with ...USec to signal the underlying low-level time unit โ€” even though both of them encapsulate the very same settings. iconic mess, honestly. ๐Ÿ’€

๐ŸŒˆ DISPLAYING TIMESTAMPS ๐ŸŒˆ

a timestamp is different from a time span โ€” it's a specific, unique point in time. main character energy, one exact moment. โœจ

when displaying, systemd formats it in the local timezone like this:

Fri 2012-11-23 23:02:15 CET

the weekday gets printed in the abbreviated English language form. and the whole formatting situation is locale-independent. no translations, no negotiations.

in some cases timestamps are shown in the UTC timezone instead of the local timezone โ€” and you can tell because it says so via the "UTC" timezone specifier in the output. ๐Ÿ‘‘

in some cases timestamps are shown with microsecond granularity. when that happens, the sub-second remainder is separated from the seconds component by a full stop.

๐Ÿ’œ PARSING TIMESTAMPS ๐Ÿ’œ

when systemd parses a timestamp, she accepts a similar syntax, but with more leeway:

  • some fields can be omitted
  • the space between the date and the time can be replaced with a "T" โ€” ร  la the RFC 3339<sup>[1]</sup> profile of ISO 8601

so in CET, all four of these are literally identical:

  • "Fri 2012-11-23 23:02:15 CET"
  • "Fri 2012-11-23T23:02:15"
  • "2012-11-23T23:02:15 CET"
  • "2012-11-23 23:02:15"

the timezone defaults to the current timezone if you don't specify it explicitly. you can give it after a space, like above, and in that case it can be:

  • "UTC"
  • an entry in the installed IANA timezone database โ€” e.g. "CET", "Asia/Tokyo" โ€” and you can get the complete list with timedatectl list-timezones (see timedatectl(1))
  • "ยฑ05", "ยฑ0530", "ยฑ05:30", "Z"

it can also be affixed directly to the timestamp โ€” and when you do that, it must match one of the formats defined in the RFC 3339<sup>[1]</sup> profile of ISO 8601: "ยฑ05:30" or "Z". so these two are also identical to all the ones above:

  • "2012-11-23T23:02:15+01:00"
  • "2012-11-23 22:02:15Z"

a timestamp can also start with a field containing a weekday, and that weekday can be abbreviated ("Wed") or non-abbreviated ("Wednesday") in English โ€” and case does not matter, regardless of locale. BUT. ๐Ÿšจ if a weekday is specified and it doesn't match the date, the timestamp gets rejected. she does not tolerate liars.

here's the defaults tea:

  • if the date is omitted, it defaults to today
  • if the time is omitted, it defaults to 00:00:00
  • fractional seconds can be specified down to 1ยตs precision
  • the seconds field can also be omitted, defaulting to 0

and now, the special tokens โ€” because sometimes you don't wanna type a whole date, you just wanna vibe:

  • "now" โ†’ the current time (or the time of the invocation of the command that is currently executed)
  • "today" โ†’ 00:00:00 of the current day
  • "yesterday" โ†’ 00:00:00 of the day before
  • "tomorrow" โ†’ 00:00:00 of the next day

relative times are accepted too, bestie:

  • a time span (see above) prefixed with "+" โ†’ evaluated to the current time plus the specified time span
  • a time span prefixed with "-" โ†’ evaluated to the current time minus the specified time span
  • instead of prefixing with "+" or "-", you can also suffix the time span with a space and the word "left" or "ago"

and finally โ€” an integer prefixed with "@" is evaluated relative to the UNIX epoch, which is 1970-01-01 00:00:00 UTC.

now here's the glow-up table of valid timestamps and their normalized forms. context for these: assume the current time was 2012-11-23 18:15:22 and the timezone was UTC+8 โ€” for example TZ=:Asia/Shanghai:

      Fri 2012-11-23 11:12:13 โ†’ Fri 2012-11-23 11:12:13
          2012-11-23 11:12:13 โ†’ Fri 2012-11-23 11:12:13
      2012-11-23 11:12:13 UTC โ†’ Fri 2012-11-23 19:12:13
         2012-11-23T11:12:13Z โ†’ Fri 2012-11-23 19:12:13
       2012-11-23T11:12+02:00 โ†’ Fri 2012-11-23 17:12:00
                   2012-11-23 โ†’ Fri 2012-11-23 00:00:00
                     12-11-23 โ†’ Fri 2012-11-23 00:00:00
                     11:12:13 โ†’ Fri 2012-11-23 11:12:13
                        11:12 โ†’ Fri 2012-11-23 11:12:00
                          now โ†’ Fri 2012-11-23 18:15:22
                        today โ†’ Fri 2012-11-23 00:00:00
                    today UTC โ†’ Fri 2012-11-23 16:00:00
                    yesterday โ†’ Fri 2012-11-22 00:00:00
                     tomorrow โ†’ Fri 2012-11-24 00:00:00
    tomorrow Pacific/Auckland โ†’ Thu 2012-11-23 19:00:00
                     +3h30min โ†’ Fri 2012-11-23 21:45:22
                          -5s โ†’ Fri 2012-11-23 18:15:17
                    11min ago โ†’ Fri 2012-11-23 18:04:22
                  @1395716396 โ†’ Tue 2014-03-25 03:59:56
๐Ÿ˜ญ note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable locally, because the timezone component is not understood โ€” unless it happens to be "UTC". that's the one exception, she's the universal translator.

timestamps may also be specified with microsecond granularity. the sub-second remainder is expected to be separated by a full stop from the seconds component. example:

2014-03-25 03:59:56.654563

in some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of โ€” or in addition to โ€” an absolute timestamp as described above. a relative timestamp is formatted like this:

2 months 5 days ago

and psa bestie: a relative timestamp is also accepted wherever a timestamp is expected (see above). so don't be surprised when she reads it back to you. ๐Ÿ”ฅ

use the timestamp command of systemd-analyze(1) to validate and normalize timestamps for testing purposes. she's the vibe-check authority. โœ…

๐Ÿ—“๏ธ CALENDAR EVENTS ๐Ÿ—“๏ธ

okay so calendar events are the glow-up version of absolute timestamps โ€” they let you point at one or more moments in time all in a single expression. Like, they're a superset of the absolute timestamps we already covered. ๐Ÿ’–

Thu,Fri 2012-*-1,5 11:12:13

so that lil baddie right there means 11:12:13 of the first or fifth day of any month in the year 2012 โ€” but only if that day happens to be a Thursday or Friday. iconic, honestly.

The weekday spec is optional, no pressure. If you do include it, it's one or more English weekday names โ€” either the abbreviated form (Wed) or the full non-abbreviated form (Wednesday), and case does not matter bestie, live your truth โ€” separated by commas. Two weekdays separated by .. means a range of continuous weekdays. And , and .. may be combined freely. go off. ๐ŸŽ€

In the date and time specs, any component can be a *, and that just means any value will match. Or, each component can be a comma-separated list of values. Values may be suffixed with / and a repetition value โ€” which means the value itself and the value plus all multiples of the repetition value get matched. Two values separated by .. give you a range of values, and ranges may also be followed with / and a repetition value, in which case the expression matches all times starting with the start value, continuing with all multiples of the repetition value relative to the start value, and ending at the end value at the latest. periodt. ๐Ÿ’…

A date spec may also use ~ to say the last day in a month. For example, *-02~03 means "the third last day in February," and Mon *-05~07/1 means "the last Monday in May." slay.

The seconds component may contain decimal fractions โ€” both in the value and in the repetition. All fractions get rounded to 6 decimal places, no cap.

Either the time spec or the date spec may be omitted, and in that case 00:00:00 and *-*-* are implied, respectively. If the seconds component isn't specified, :00 is assumed. easy. โœจ

Timezone can be specified as the literal string "UTC", or the local timezone (similar to the supported syntax of timestamps, see above), or the timezone in the IANA timezone database format (also see above). ๐ŸŒ

โœจ the shorthand shorthands โœจ

These special expressions are little shortcuts for longer normalized forms โ€” so you don't have to type the whole thing out, bestie:

        minutely โ†’ *-*-* *:*:00
          hourly โ†’ *-*-* *:00:00
           daily โ†’ *-*-* 00:00:00
         monthly โ†’ *-*-01 00:00:00
          weekly โ†’ Mon *-*-* 00:00:00
          yearly โ†’ *-01-01 00:00:00
       quarterly โ†’ *-01,04,07,10-01 00:00:00
    semiannually โ†’ *-01,07-01 00:00:00

๐ŸŒธ examples of valid timestamps & their normalized form ๐ŸŒธ

okay this is the part that actually makes it click. watch the glow-up happen in real time:

      Sat,Thu,Mon..Wed,Sat..Sun โ†’ Mon..Thu,Sat,Sun *-*-* 00:00:00
          Mon,Sun 12-*-* 2,1:23 โ†’ Mon,Sun 2012-*-* 01,02:23:00
                        Wed *-1 โ†’ Wed *-*-01 00:00:00
               Wed..Wed,Wed *-1 โ†’ Wed *-*-01 00:00:00
                     Wed, 17:48 โ†’ Wed *-*-* 17:48:00
    Wed..Sat,Tue 12-10-15 1:2:3 โ†’ Tue..Sat 2012-10-15 01:02:03
                    *-*-7 0:0:0 โ†’ *-*-07 00:00:00
                          10-15 โ†’ *-10-15 00:00:00
            monday *-12-* 17:00 โ†’ Mon *-12-* 17:00:00
      Mon,Fri *-*-3,1,2 *:30:45 โ†’ Mon,Fri *-*-01,02,03 *:30:45
           12,14,13,12:20,10,30 โ†’ *-*-* 12,13,14:10,20,30:00
                12..14:10,20,30 โ†’ *-*-* 12..14:10,20,30:00
      mon,fri *-1/2-1,3 *:30:45 โ†’ Mon,Fri *-01/2-01,03 *:30:45
                 03-05 08:05:40 โ†’ *-03-05 08:05:40
                       08:05:40 โ†’ *-*-* 08:05:40
                          05:40 โ†’ *-*-* 05:40:00
         Sat,Sun 12-05 08:05:40 โ†’ Sat,Sun *-12-05 08:05:40
               Sat,Sun 08:05:40 โ†’ Sat,Sun *-*-* 08:05:40
               2003-03-05 05:40 โ†’ 2003-03-05 05:40:00
     05:40:23.4200004/3.1700005 โ†’ *-*-* 05:40:23.420000/3.170001
                 2003-02..04-05 โ†’ 2003-02..04-05 00:00:00
           2003-03-05 05:40 UTC โ†’ 2003-03-05 05:40:00 UTC
                     2003-03-05 โ†’ 2003-03-05 00:00:00
                          03-05 โ†’ *-03-05 00:00:00
                         hourly โ†’ *-*-* *:00:00
                          daily โ†’ *-*-* 00:00:00
                      daily UTC โ†’ *-*-* 00:00:00 UTC
                        monthly โ†’ *-*-01 00:00:00
                         weekly โ†’ Mon *-*-* 00:00:00
        weekly Pacific/Auckland โ†’ Mon *-*-* 00:00:00 Pacific/Auckland
                         yearly โ†’ *-01-01 00:00:00
                       annually โ†’ *-01-01 00:00:00
                          *:2/3 โ†’ *-*-* *:02/3:00

like, look at *:2/3 turning into *-*-* *:02/3:00?? the way that normalization ATE ๐Ÿ˜ญ๐Ÿ’–

Calendar events are what timer units use, so if you wanna know more, go read systemd.timer(5). ๐Ÿ‘‘

And bestie โ€” if you wanna validate and normalize your calendar time specs for testing, or you want the tool to calculate when a specified calendar event would occur next, use the calendar command of systemd-analyze(1). it's giving "test before you ship". ๐Ÿงš

๐Ÿ”— SEE ALSO ๐Ÿ”—

๐Ÿ“ NOTES ๐Ÿ“

  1. RFC 3339 https://tools.ietf.org/html/rfc3339

aaaand that's the whole page, bestie!! ๐Ÿซถ this was systemd 262.1 for SYSTEMD.TIME(7), and you absolutely ate this read. go schedule something iconic. ๐Ÿ’…โœจ๐Ÿ’–

๐Ÿ“ฆ where this page comes from
  • arch rolling: systemd 262.1-1 ยท LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
  • ๐Ÿ’– girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms