rtcwake

Show whether an alarm is set or not

$ sudo rtcwake [[-m|--mode]] show [[-v|--verbose]]

$ sudo rtcwake [[-m|--mode]] mem [[-s|--seconds]] [10]

$ sudo rtcwake [[-m|--mode]] disk --date +[15]min

$ sudo rtcwake [[-m|--mode]] freeze --date [YYYYMMDDhhmm]

$ sudo rtcwake [[-m|--mode]] disable

$ sudo rtcwake [[-m|--mode]] on --date [hh:ss]

rtcwake [options] [-d device] [-m mode] { -s seconds | -t time_t | -A } [ -l | -u ]

-A, --show-alarm
    Displays the current RTC alarm time and then exits. This option cannot be combined with setting an alarm time.

-d device, --device=device
    Specifies the RTC device to use, for example, rtc0 or rtc1. The default is usually rtc0.

-m mode, --mode=mode
    Defines the system power state rtcwake should transition to after setting the alarm. Valid modes include:
no: Do not suspend, just set the alarm.
mem: Suspend to RAM (ACPI S3 state).
disk: Suspend to disk (ACPI S4 state, hibernate).
off: Power off the system (ACPI S5 state). Requires proper BIOS and hardware support.
disable: Disables any pending RTC alarm.
show: Displays the current RTC alarm time (similar to -A).

-s seconds, --seconds=seconds
    Sets the RTC alarm to trigger after the specified seconds from the current time. This option is mutually exclusive with -t and -A.

-t time_t, --time=time_t
    Sets the RTC alarm to trigger at the specified time_t, which is the number of seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC). This option is mutually exclusive with -s and -A.

-l, --local
    Interprets the specified time (with -t or -s) as being in the local timezone. By default, rtcwake attempts to determine whether the RTC is set to local time or UTC.

-u, --utc
    Interprets the specified time (with -t or -s) as being in UTC. By default, rtcwake attempts to determine whether the RTC is set to local time or UTC.

-n, --dry-run
    Performs a dry run: it shows what would happen without actually setting the alarm or suspending the system.

-v, --verbose
    Enables verbose output, providing more information about the command's execution.

-h, --help
    Displays a help message and exits.

-V, --version
    Displays version information and exits.

The rtcwake command is a utility designed to interact with the system's Real-Time Clock (RTC) and its alarm functionality. Its primary purpose is to set a hardware alarm that can cause the system to wake up from a suspended state (like suspend-to-RAM or suspend-to-disk) or, if supported by the hardware and BIOS, to power on from a powered-off state. This is particularly useful for scheduling unattended system operations, such as nightly backups or system maintenance, without needing the system to remain fully powered on.

rtcwake can set an alarm for a specific number of seconds from now or for an absolute time (seconds since epoch). It also provides options to query the current RTC alarm time or to disable an existing alarm. The command handles the different system power states (sleep modes) like S3 (suspend-to-RAM), S4 (suspend-to-disk/hibernate), and S5 (power off). Proper functionality, especially for power-off wake-up, heavily relies on the underlying hardware and BIOS support. Running rtcwake typically requires root privileges as it interacts directly with kernel hardware interfaces.

Using rtcwake requires root privileges (CAP_SYS_ADMIN capability).
The success of suspend/hibernate/power-off modes (-m mem, -m disk, -m off) depends heavily on the underlying hardware, BIOS/UEFI firmware, and kernel support for ACPI power management.
Incorrect configuration of the system clock (e.g., whether the RTC is set to UTC or local time via /etc/adjtime) can lead to alarms triggering at unexpected times.
Some RTC hardware might not support all alarm features or may have limitations on alarm resolution.

For rtcwake to function correctly with absolute times (using -t), it's crucial that the system accurately knows whether the hardware RTC is set to UTC or local time. Linux typically determines this from the UTC entry in the /etc/adjtime file. If this file is missing or incorrect, or if the RTC's time zone setting is ambiguous, rtcwake might interpret the alarm time incorrectly. The -l (local) and -u (UTC) options provide explicit control over this interpretation, overriding the system's default behavior.

rtcwake is a long-standing utility included in the util-linux package, which provides a set of essential system utilities for Linux. Its origins trace back to the early days of Linux power management, offering a direct way to schedule system wake-ups via the hardware RTC. While modern systems often use higher-level power management frameworks like systemd's built-in suspend/hibernate capabilities, rtcwake remains a fundamental tool for direct RTC interaction, particularly useful for scripting and embedded systems. Over time, options like -m off were added to support powering off the system and waking it up, and certain older options like -a (auto) have been deprecated.

hwclock(8), adjtimex(8), systemctl(1), pm-suspend(8)