1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
13.\"
14.Dd December 29, 2021
15.Dt TIMESPEC 3HEAD
16.Os
17.Sh NAME
18.Nm timespec ,
19.Nm timeval ,
20.Nm TIMESPEC_TO_TIMEVAL ,
21.Nm TIMEVAL_TO_TIMESPEC
22.Nd time structures and conversion
23.Sh SYNOPSIS
24.In sys/time.h
25.Ft void
26.Fo TIMESPEC_TO_TIMEVAL
27.Fa "struct timeval *tv"
28.Fa "const struct timespec *ts"
29.Fc
30.Ft void
31.Fo TIMEVAL_TO_TIMESPEC
32.Fa "const struct timeval *tv"
33.Fa "struct timespec *ts"
34.Fc
35.Sh DESCRIPTION
36The
37.Vt timeval
38and
39.Vt timespec
40structures are declared in the
41.In time.h
42and
43.In sys/time.h
44headers respectively:
45.Bd -literal -offset indent
46typedef struct timespec {
47	time_t		tv_sec;		/* seconds */
48	long		tv_nsec;	/* and nanoseconds */
49} timespec_t;
50
51struct timeval {
52	time_t		tv_sec;		/* seconds */
53	suseconds_t	tv_usec;	/* and microseconds */
54};
55.Ed
56.Pp
57In both cases, the
58.Fa tv_sec
59member represents elapsed time in whole seconds.
60The
61.Fa tv_nsec
62and
63.Fa tv_usec
64members represent the rest of the elapsed time in nanoseconds and
65microseconds respectively, depending on the structure.
66.Pp
67The
68.Dv TIMEVAL_TO_TIMESPEC
69macro can be used to convert a
70.Vt struct timeval
71structure to a
72.Vt struct timespec
73structure, while the
74.Dv TIMESPEC_TO_TIMEVAL
75macro works in the opposite direction.
76.Pp
77When converting from a
78.Vt struct timespec
79to a
80.Vt struct timeval
81structure, the
82.Fa tv_nsec
83member is truncated, losing precision.
84When converting from a
85.Vt struct timeval
86to a
87.Vt struct timespec
88structure, the
89.Fa tv_usec
90member is multiplied by 1000 to reach the precision of the target
91structure.
92The
93.Fa tv_sec
94member is always preserved, no matter which conversion is performed.
95.Pp
96Note that the
97.Dv TIMEVAL_TO_TIMESPEC
98and
99.Dv TIMESPEC_TO_TIMEVAL
100macros are non-standard but are commonly found on UNIX and UNIX-like systems.
101.Sh INTERFACE STABILITY
102.Sy Committed
103.Sh MT-LEVEL
104.Sy MT-Safe
105.Sh SEE ALSO
106.Xr time.h 3HEAD
107