NetBSD/share/man/man9/todr.9

.\" $NetBSD: todr.9,v 1.3 2002/02/13 08:18:52 ross Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 22, 2000
.Dt TODR 9
.Os
.Sh NAME
.Nm todr_gettime
.Nm todr_settime
.Nm todr_getcal
.Nm todr_setcal
.Nm clock_ymdhms_to_secs
.Nm clock_secs_to_ymdhms
.Nd time-of-day clock support
.Sh SYNOPSIS
.Fd #include \*[Lt]dev/clock_subr.h\*[Gt]
.Ft int
.Fn todr_gettime "todr_chip_handle_t" "struct timeval *"
.Ft int
.Fn todr_settime "todr_chip_handle_t" "struct timeval *"
.Ft int
.Fn todr_getcal "todr_chip_handle_t" "int *"
.Ft int
.Fn todr_setcal "todr_chip_handle_t" "int"
.Ft void
.Fn clock_secs_to_ymdhms "int" "struct clock_ymdhms *"
.Ft time_t
.Fn clock_ymdhms_to_secs "struct clock_ymdhms *"
.Sh DESCRIPTION
The
.Fn todr_*
functions provide an interface to read, set and control
.Ql time-of-day
devices. The
.Fa todr_chip_handle_t
should be obtained from a driver for a particular hardware device that
implements this interface. Examples of such drivers currently include
.Xr mk48txx 4
and
.Xr intersil7170 4 .
.Pp
The
.Fn todr_gettime
retrieves the current data and time from the TODR device and returns it
in the
.Fa struct timeval
storage provided by the caller.
.Fn todr_settime
sets the date and time in the TODR device represented by
.Fa todr_chip_handle_t
according to the
.Fa struct timeval
argument.
.Pp
.Fn todr_setcal
specifies a calibration value in PPM units to be programmed in the TODR
device. Positive values shall speed up the TODR clock, negative values
shall slow it down. If the device in not capable of handling calibration,
this function shall return
.Va EOPNOTSUPP .
The measurement and calculations necessary to utilize this method is
expected to be provided by higher-level software modules.
.Fn todr_getcal
returns the current calibration (in PPM units) in effect on the TODR device.
.Pp
The utilities
.Fn clock_secs_to_ymdhms
and
.Fn 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
.Aq year,month,day,weekday,hour,minute,seconds
tuple. This structure is defined as follows:
.Bd -literal
struct clock_ymdhms {
	u_short dt_year;	/* Year */
	u_char dt_mon;		/* Month (1-12) */
	u_char dt_day;		/* Day (0-365) */
	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) */
};
.Ed
.Pp
Note: leap years are recognised by these conversion routines.
.Sh RETURN VALUES
The
.Fn todr_*
functions return 0 if the requested operation was successful;
otherwise an error code from
.Aq Pa sys/errno.h
shall be returned. However, behaviour is undefined if an invalid
.Fa todr_chip_handle_t
is passed to any of these functions.
The
.Fn clock_secs_to_ymdhms
and
.Fn clock_ymdhms_to_secs
functions never fail.
.Sh SEE ALSO
.Xr inittodr 9 ,
.Xr resettodr 9 ,
.Xr time 9