131 lines
3.9 KiB
Groff
131 lines
3.9 KiB
Groff
.\" $NetBSD: todr.9,v 1.16 2010/03/22 18:58:33 joerg Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000, 2003 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.
|
|
.\"
|
|
.\" 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 September 6, 2006
|
|
.Dt TODR 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm todr_attach ,
|
|
.Nm todr_gettime ,
|
|
.Nm todr_settime ,
|
|
.Nm clock_ymdhms_to_secs ,
|
|
.Nm clock_secs_to_ymdhms
|
|
.Nd time-of-day clock support
|
|
.Sh SYNOPSIS
|
|
.In dev/clock_subr.h
|
|
.Ft void
|
|
.Fn todr_attach "todr_chip_handle_t"
|
|
.Ft int
|
|
.Fn todr_gettime "todr_chip_handle_t" "struct timeval *"
|
|
.Ft int
|
|
.Fn todr_settime "todr_chip_handle_t" "struct timeval *"
|
|
.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.
|
|
A driver for a
|
|
.Ql time-of-day
|
|
device registers its
|
|
.Fa todr_chip_handle_t
|
|
with machine-dependent code using the
|
|
.Fn todr_attach
|
|
function.
|
|
Alternatively, a machine-dependent front-end to a
|
|
.Ql time-of-day
|
|
device driver may obtain the
|
|
.Fa todr_chip_handle_t
|
|
directly.
|
|
.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
|
|
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 (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) */
|
|
};
|
|
.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
|
|
.In 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.
|
|
.Pp
|
|
The
|
|
.Fn clock_ymdhms_to_secs
|
|
function returns \-1 if the time in seconds would be less that zero or too
|
|
large to fit in a
|
|
.Fa time_t .
|
|
The
|
|
.Fn clock_secs_to_ymdhms
|
|
function never fails.
|
|
.Sh SEE ALSO
|
|
.Xr intersil7170 4 ,
|
|
.Xr mk48txx 4 ,
|
|
.Xr inittodr 9 ,
|
|
.Xr resettodr 9 ,
|
|
.Xr time_second 9
|