TODR(9)

💖 TODR(9) 💖

okay bestie, welcome to the Kernel Developer's Manual page for TODR(9) — we're talking time-of-day clock support, and it's lowkey giving main character energy 🕰️✨.

🌸 NAME 🌸

• todr_attach, todr_gettime, todr_settime, clock_ymdhms_to_secs, clock_secs_to_ymdhms — time-of-day clock support 💅

✨ SYNOPSIS ✨

here's the exact incantation, no cap:

       #include <dev/clock_subr.h>

       void
       todr_attach(todr_chip_handle_t);

       int
       todr_gettime(todr_chip_handle_t, struct timeval *);

       int
       todr_settime(todr_chip_handle_t, struct timeval *);

       int
       clock_secs_to_ymdhms(time_t, struct clock_ymdhms *);

       time_t
       clock_ymdhms_to_secs(struct clock_ymdhms *);

💫 DESCRIPTION 💫

so the todr_*() functions are your interface to read, set and control ‘time-of-day’ devices. A driver for a ‘time-of-day’ device registers its todr_chip_handle_t with machine-dependent code using the todr_attach() function. Alternatively, a machine-dependent front-end to a ‘time-of-day’ device driver may obtain the todr_chip_handle_t directly. periodt. 🫶

todr_gettime() retrieves the current data and time from the TODR device and returns it in the struct timeval storage provided by the caller. todr_settime() sets the date and time in the TODR device represented by todr_chip_handle_t according to the struct timeval argument. slay. 💅

The utilities clock_secs_to_ymdhms() and clock_ymdhms_to_secs() are provided to convert a time value in seconds to and from a structure representing the date and time as a ⟨year,month,day,weekday,hour,minute,seconds⟩ tuple. This structure is defined as follows, bestie:

       struct clock_ymdhms {
               uint64_t dt_year;       /* Year */
               u_char dt_mon;          /* Month (1-12) */
               u_char dt_day;          /* Day (1-31) */
               u_char dt_wday;         /* Day of week (0-6) */
               u_char dt_hour;         /* Hour (0-23) */
               u_char dt_min;          /* Minute (0-59) */
               u_char dt_sec;          /* Second (0-59) */
       };

Note: leap years are recognised by these conversion routines. literally iconic behavior 🗓️💖

🎀 RETURN VALUES 🎀

• todr_*() — return 0 if the requested operation was successful; otherwise an error code from <sys/errno.h> shall be returned. zero is the vibe check, anything else means check your errno 😭
• clock_ymdhms_to_secs() — returns -1 if the time in seconds would be less that zero or too large to fit in a time_t.
• clock_secs_to_ymdhms() — returns 0 on success or EINVAL if the time passed is negative.

⚠️ However, behaviour is undefined if an invalid todr_chip_handle_t is passed to any of these functions. no cap, do not do this 💀

🦋 SEE ALSO 🦋

go read these next, bestie — I'm obsessed:

• intersil7170(4)
• mk48txx(4)
• inittodr(9)
• resettodr(9)
• time_second(9)

---

xoxo, Debian — September 10, 2014 — TODR(9) out 💅🫶✨