share/man/man9/todr.9

   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 .\"
  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
  53 The
  54 .Fn todr_*
  55 functions provide an interface to read, set and control
  56 .Ql time-of-day
  57 devices.
  58 A driver for a
  59 .Ql time-of-day
  60 device registers its
  61 .Fa todr_chip_handle_t
  62 with machine-dependent code using the
  63 .Fn todr_attach
  64 function.
  65 Alternatively, a machine-dependent front-end to a
  66 .Ql time-of-day
  67 device driver may obtain the
  68 .Fa todr_chip_handle_t
  69 directly.
  70 .Pp
  71 The
  72 .Fn todr_gettime
  73 retrieves the current data and time from the TODR device and returns it
  74 in the
  75 .Fa struct timeval
  76 storage provided by the caller.
  77 .Fn todr_settime
  78 sets the date and time in the TODR device represented by
  79 .Fa todr_chip_handle_t
  80 according to the
  81 .Fa struct timeval
  82 argument.
  83 .Pp
  84 The utilities
  85 .Fn clock_secs_to_ymdhms
  86 and
  87 .Fn clock_ymdhms_to_secs
  88 are provided to convert a time value in seconds to and from a structure
  89 representing the date and time as a
  90 .Aq year,month,day,weekday,hour,minute,seconds
  91 tuple.
  92 This structure is defined as follows:
  93 .Bd -literal
  94 struct 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
 105 Note: leap years are recognised by these conversion routines.
 106 .Sh RETURN VALUES
 107 The
 108 .Fn todr_*
 109 functions return 0 if the requested operation was successful;
 110 otherwise an error code from
 111 .Aq Pa sys/errno.h
 112 shall be returned.
 113 However, behaviour is undefined if an invalid
 114 .Fa todr_chip_handle_t
 115 is passed to any of these functions.
 116 .Pp
 117 The
 118 .Fn clock_ymdhms_to_secs
 119 function returns \-1 if the time in seconds would be less that zero or too
 120 large to fit in a
 121 .Fa time_t .
 122 The
 123 .Fn clock_secs_to_ymdhms
 124 function 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