1.\" $NetBSD: todr.9,v 1.14 2007/02/20 08:26:36 wiz Exp $ 2.\" 3.\" Copyright (c) 2000, 2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 6, 2006 38.Dt TODR 9 39.Os 40.Sh NAME 41.Nm todr_attach , 42.Nm todr_gettime , 43.Nm todr_settime , 44.Nm clock_ymdhms_to_secs , 45.Nm clock_secs_to_ymdhms 46.Nd time-of-day clock support 47.Sh SYNOPSIS 48.In dev/clock_subr.h 49.Ft void 50.Fn todr_attach "todr_chip_handle_t" 51.Ft int 52.Fn todr_gettime "todr_chip_handle_t" "struct timeval *" 53.Ft int 54.Fn todr_settime "todr_chip_handle_t" "struct timeval *" 55.Ft void 56.Fn clock_secs_to_ymdhms "int" "struct clock_ymdhms *" 57.Ft time_t 58.Fn clock_ymdhms_to_secs "struct clock_ymdhms *" 59.Sh DESCRIPTION 60The 61.Fn todr_* 62functions provide an interface to read, set and control 63.Ql time-of-day 64devices. 65A driver for a 66.Ql time-of-day 67device registers its 68.Fa todr_chip_handle_t 69with machine-dependent code using the 70.Fn todr_attach 71function. 72Alternatively, a machine-dependent front-end to a 73.Ql time-of-day 74device driver may obtain the 75.Fa todr_chip_handle_t 76directly. 77.Pp 78The 79.Fn todr_gettime 80retrieves the current data and time from the TODR device and returns it 81in the 82.Fa struct timeval 83storage provided by the caller. 84.Fn todr_settime 85sets the date and time in the TODR device represented by 86.Fa todr_chip_handle_t 87according to the 88.Fa struct timeval 89argument. 90.Pp 91The utilities 92.Fn clock_secs_to_ymdhms 93and 94.Fn clock_ymdhms_to_secs 95are provided to convert a time value in seconds to and from a structure 96representing the date and time as a 97.Aq year,month,day,weekday,hour,minute,seconds 98tuple. 99This structure is defined as follows: 100.Bd -literal 101struct clock_ymdhms { 102 u_short dt_year; /* Year */ 103 u_char dt_mon; /* Month (1-12) */ 104 u_char dt_day; /* Day (1-31) */ 105 u_char dt_wday; /* Day of week (0-6) */ 106 u_char dt_hour; /* Hour (0-23) */ 107 u_char dt_min; /* Minute (0-59) */ 108 u_char dt_sec; /* Second (0-59) */ 109}; 110.Ed 111.Pp 112Note: leap years are recognised by these conversion routines. 113.Sh RETURN VALUES 114The 115.Fn todr_* 116functions return 0 if the requested operation was successful; 117otherwise an error code from 118.Aq Pa sys/errno.h 119shall be returned. 120However, behaviour is undefined if an invalid 121.Fa todr_chip_handle_t 122is passed to any of these functions. 123.Pp 124The 125.Fn clock_ymdhms_to_secs 126function returns \-1 if the time in seconds would be less that zero or too 127large to fit in a 128.Fa time_t . 129The 130.Fn clock_secs_to_ymdhms 131function never fails. 132.Sh SEE ALSO 133.Xr intersil7170 4 , 134.Xr mk48txx 4 , 135.Xr inittodr 9 , 136.Xr resettodr 9 , 137.Xr time_second 9 138