September 6, 2006 TODR 9

### NAME

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

### SYNOPSIS

```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 *`)
```void` clock_secs_to_ymdhms(```int``, 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 {
            u_short 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 never fails.

### SEE ALSO

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