TODR(9)

TODR(9) | Kernel Developer's Manual | TODR(9)

# NAME

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

# SYNOPSIS

`#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

The `todr_*`() functions provide an 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.

The `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.

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:

    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.

# RETURN VALUES

The `todr_*`() functions return 0 if the requested operation was successful; otherwise an error code from `<sys/errno.h>` shall be returned. However, behaviour is undefined if an invalid todr_chip_handle_t is passed to any of these functions.

The `clock_ymdhms_to_secs`() function returns -1 if the time in seconds would be less that zero or too large to fit in a time_t. The `clock_secs_to_ymdhms`() function returns 0 on success or `EINVAL` if the time passed is negative.

# SEE ALSO

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

September 10, 2014 | NetBSD 9.0