diff options
Diffstat (limited to 'static/netbsd/man3/timeval.3')
| -rw-r--r-- | static/netbsd/man3/timeval.3 | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/static/netbsd/man3/timeval.3 b/static/netbsd/man3/timeval.3 new file mode 100644 index 00000000..4817faf9 --- /dev/null +++ b/static/netbsd/man3/timeval.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: timeval.3,v 1.12 2011/04/12 08:39:26 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 April 12, 2011 +.Dt TIMEVAL 3 +.Os +.Sh NAME +.Nm timeval , +.Nm timespec , +.Nm itimerval , +.Nm itimerspec , +.Nm bintime +.Nd time structures +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn TIMEVAL_TO_TIMESPEC "struct timeval *tv" "struct timespec *ts" +.Ft void +.Fn TIMESPEC_TO_TIMEVAL "struct timeval *tv" "struct timespec *ts" +.Sh DESCRIPTION +The +.In sys/time.h +header, included by +.In time.h , +defines various structures related to time and timers. +.Bl -enum -offset 1n +.It +The following structure is used by +.Xr gettimeofday 2 , +among others: +.Bd -literal -offset indent +struct timeval { + time_t tv_sec; + suseconds_t tv_usec; +}; +.Ed +.Pp +The +.Va tv_sec +member represents the elapsed time, in whole seconds. +The +.Va tv_usec +member captures rest of the elapsed time, +represented as the number of microseconds. +.It +The following structure is used by +.Xr nanosleep 2 , +among others: +.Bd -literal -offset indent +struct timespec { + time_t tv_sec; + long tv_nsec; +}; +.Ed +.Pp +The +.Va tv_sec +member is again the elapsed time in whole seconds. +The +.Va tv_nsec +member represents the rest of the elapsed time in nanoseconds. +.Pp +A microsecond is equal to one millionth of a second, +1000 nanoseconds, or 1/1000 milliseconds. +To ease the conversions, the macros +.Fn TIMEVAL_TO_TIMESPEC +and +.Fn TIMESPEC_TO_TIMEVAL +can be used to convert between +.Em struct timeval +and +.Em struct timespec . +.It +The following structure is used by +.Xr setitimer 2 , +among others: +.Bd -literal -offset indent +struct itimerval { + struct timeval it_interval; + struct timeval it_value; +}; +.Ed +.It +The following structure is used by +.Xr timer_settime 2 , +among others: +.Bd -literal -offset indent +struct itimerspec { + struct timespec it_interval; + struct timespec it_value; +}; +.Ed +.Pp +Both +.Em struct itimerval +and +.Em struct itimerspec +are used to specify when a timer expires. +Generally, +.Va it_interval +specifies the period between successive timer expirations. +A value zero implies that the alarm will fire only once. +If +.Va it_value +is non-zero, it indicates the time left to the next timer expiration. +A value zero implies that the timer is disabled. +.It +The following structure is used by +.Xr bintime 9 , +among others: +.Bd -literal -offset indent +struct bintime { + time_t sec; + uint64_t frac; +}; +.Ed +.Pp +The +.Va sec +member specifies the time in seconds and +.Va frac +represents a 64-bit fraction of seconds. +The +.Va struct bintime +is meant to be used in the kernel only. +It is further described in +.Xr timecounter 9 . +.El +.Sh EXAMPLES +It can be stressed that the traditional +.Tn UNIX +.Va timeval +and +.Va timespec +structures represent elapsed time, measured by the system clock +(see +.Xr hz 9 ) . +The following sketch implements a function suitable +for use in a context where the +.Va timespec +structure is required for a conditional timeout: +.Bd -literal -offset indent +static void +example(struct timespec *spec, time_t minutes) +{ + struct timeval elapsed; + + (void)gettimeofday(&elapsed, NULL); + + _DIAGASSERT(spec != NULL); + TIMEVAL_TO_TIMESPEC(&elapsed, spec); + + /* Add the offset for timeout in minutes. */ + spec->tv_sec = spec->tv_sec + minutes * 60; +} +.Ed +.Pp +A better alternative would use the more precise +.Xr clock_gettime 2 . +.Sh SEE ALSO +.Xr timeradd 3 , +.Xr tm 3 , +.Xr bintime_add 9 |