1.\" $NetBSD: todr.9,v 1.16 2010/03/22 18:58:33 joerg 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 6, 2006 31.Dt TODR 9 32.Os 33.Sh NAME 34.Nm todr_attach , 35.Nm todr_gettime , 36.Nm todr_settime , 37.Nm clock_ymdhms_to_secs , 38.Nm clock_secs_to_ymdhms 39.Nd time-of-day clock support 40.Sh SYNOPSIS 41.In dev/clock_subr.h 42.Ft void 43.Fn todr_attach "todr_chip_handle_t" 44.Ft int 45.Fn todr_gettime "todr_chip_handle_t" "struct timeval *" 46.Ft int 47.Fn todr_settime "todr_chip_handle_t" "struct timeval *" 48.Ft void 49.Fn clock_secs_to_ymdhms "int" "struct clock_ymdhms *" 50.Ft time_t 51.Fn clock_ymdhms_to_secs "struct clock_ymdhms *" 52.Sh DESCRIPTION 53The 54.Fn todr_* 55functions provide an interface to read, set and control 56.Ql time-of-day 57devices. 58A driver for a 59.Ql time-of-day 60device registers its 61.Fa todr_chip_handle_t 62with machine-dependent code using the 63.Fn todr_attach 64function. 65Alternatively, a machine-dependent front-end to a 66.Ql time-of-day 67device driver may obtain the 68.Fa todr_chip_handle_t 69directly. 70.Pp 71The 72.Fn todr_gettime 73retrieves the current data and time from the TODR device and returns it 74in the 75.Fa struct timeval 76storage provided by the caller. 77.Fn todr_settime 78sets the date and time in the TODR device represented by 79.Fa todr_chip_handle_t 80according to the 81.Fa struct timeval 82argument. 83.Pp 84The utilities 85.Fn clock_secs_to_ymdhms 86and 87.Fn clock_ymdhms_to_secs 88are provided to convert a time value in seconds to and from a structure 89representing the date and time as a 90.Aq year,month,day,weekday,hour,minute,seconds 91tuple. 92This structure is defined as follows: 93.Bd -literal 94struct clock_ymdhms { 95 u_short dt_year; /* Year */ 96 u_char dt_mon; /* Month (1-12) */ 97 u_char dt_day; /* Day (1-31) */ 98 u_char dt_wday; /* Day of week (0-6) */ 99 u_char dt_hour; /* Hour (0-23) */ 100 u_char dt_min; /* Minute (0-59) */ 101 u_char dt_sec; /* Second (0-59) */ 102}; 103.Ed 104.Pp 105Note: leap years are recognised by these conversion routines. 106.Sh RETURN VALUES 107The 108.Fn todr_* 109functions return 0 if the requested operation was successful; 110otherwise an error code from 111.In sys/errno.h 112shall be returned. 113However, behaviour is undefined if an invalid 114.Fa todr_chip_handle_t 115is passed to any of these functions. 116.Pp 117The 118.Fn clock_ymdhms_to_secs 119function returns \-1 if the time in seconds would be less that zero or too 120large to fit in a 121.Fa time_t . 122The 123.Fn clock_secs_to_ymdhms 124function never fails. 125.Sh SEE ALSO 126.Xr intersil7170 4 , 127.Xr mk48txx 4 , 128.Xr inittodr 9 , 129.Xr resettodr 9 , 130.Xr time_second 9 131