1.\" $NetBSD: timeval.3,v 1.12 2011/04/12 08:39:26 jruoho Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jukka Ruohonen. 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 April 12, 2011 31.Dt TIMEVAL 3 32.Os 33.Sh NAME 34.Nm timeval , 35.Nm timespec , 36.Nm itimerval , 37.Nm itimerspec , 38.Nm bintime 39.Nd time structures 40.Sh SYNOPSIS 41.In sys/time.h 42.Ft void 43.Fn TIMEVAL_TO_TIMESPEC "struct timeval *tv" "struct timespec *ts" 44.Ft void 45.Fn TIMESPEC_TO_TIMEVAL "struct timeval *tv" "struct timespec *ts" 46.Sh DESCRIPTION 47The 48.In sys/time.h 49header, included by 50.In time.h , 51defines various structures related to time and timers. 52.Bl -enum -offset 1n 53.It 54The following structure is used by 55.Xr gettimeofday 2 , 56among others: 57.Bd -literal -offset indent 58struct timeval { 59 time_t tv_sec; 60 suseconds_t tv_usec; 61}; 62.Ed 63.Pp 64The 65.Va tv_sec 66member represents the elapsed time, in whole seconds. 67The 68.Va tv_usec 69member captures rest of the elapsed time, 70represented as the number of microseconds. 71.It 72The following structure is used by 73.Xr nanosleep 2 , 74among others: 75.Bd -literal -offset indent 76struct timespec { 77 time_t tv_sec; 78 long tv_nsec; 79}; 80.Ed 81.Pp 82The 83.Va tv_sec 84member is again the elapsed time in whole seconds. 85The 86.Va tv_nsec 87member represents the rest of the elapsed time in nanoseconds. 88.Pp 89A microsecond is equal to one millionth of a second, 901000 nanoseconds, or 1/1000 milliseconds. 91To ease the conversions, the macros 92.Fn TIMEVAL_TO_TIMESPEC 93and 94.Fn TIMESPEC_TO_TIMEVAL 95can be used to convert between 96.Em struct timeval 97and 98.Em struct timespec . 99.It 100The following structure is used by 101.Xr setitimer 2 , 102among others: 103.Bd -literal -offset indent 104struct itimerval { 105 struct timeval it_interval; 106 struct timeval it_value; 107}; 108.Ed 109.It 110The following structure is used by 111.Xr timer_settime 2 , 112among others: 113.Bd -literal -offset indent 114struct itimerspec { 115 struct timespec it_interval; 116 struct timespec it_value; 117}; 118.Ed 119.Pp 120Both 121.Em struct itimerval 122and 123.Em struct itimerspec 124are used to specify when a timer expires. 125Generally, 126.Va it_interval 127specifies the period between successive timer expirations. 128A value zero implies that the alarm will fire only once. 129If 130.Va it_value 131is non-zero, it indicates the time left to the next timer expiration. 132A value zero implies that the timer is disabled. 133.It 134The following structure is used by 135.Xr bintime 9 , 136among others: 137.Bd -literal -offset indent 138struct bintime { 139 time_t sec; 140 uint64_t frac; 141}; 142.Ed 143.Pp 144The 145.Va sec 146member specifies the time in seconds and 147.Va frac 148represents a 64-bit fraction of seconds. 149The 150.Va struct bintime 151is meant to be used in the kernel only. 152It is further described in 153.Xr timecounter 9 . 154.El 155.Sh EXAMPLES 156It can be stressed that the traditional 157.Tn UNIX 158.Va timeval 159and 160.Va timespec 161structures represent elapsed time, measured by the system clock 162(see 163.Xr hz 9 ) . 164The following sketch implements a function suitable 165for use in a context where the 166.Va timespec 167structure is required for a conditional timeout: 168.Bd -literal -offset indent 169static void 170example(struct timespec *spec, time_t minutes) 171{ 172 struct timeval elapsed; 173 174 (void)gettimeofday(&elapsed, NULL); 175 176 _DIAGASSERT(spec != NULL); 177 TIMEVAL_TO_TIMESPEC(&elapsed, spec); 178 179 /* Add the offset for timeout in minutes. */ 180 spec->tv_sec = spec->tv_sec + minutes * 60; 181} 182.Ed 183.Pp 184A better alternative would use the more precise 185.Xr clock_gettime 2 . 186.Sh SEE ALSO 187.Xr timeradd 3 , 188.Xr tm 3 , 189.Xr bintime_add 9 190