1.\"	$NetBSD: timespec_get.3,v 1.9 2025/04/22 14:25:50 uwe Exp $
2.\"
3.\" Copyright (c) 2016, 2025 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Kamil Rytarowski.
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 22, 2025
31.Dt TIMESPEC_GET 3
32.Os
33.
34.Sh NAME
35.Nm timespec_get ,
36.Nm timespec_getres
37.Nd get current calendar time
38.
39.Sh LIBRARY
40.Lb libc
41.
42.Sh SYNOPSIS
43.
44.In time.h
45.
46.Ft int
47.Fn timespec_get "struct timespec *ts" "int base"
48.
49.Ft int
50.Fn timespec_getres "struct timespec *ts" "int base"
51.
52.Sh DESCRIPTION
53The
54.Fn timespec_get
55function sets the interval pointed to by
56.Fa ts
57to hold the current calendar time based on the specified time base in
58.Fa base .
59It is the
60.Tn ISO C
61equivalent to the
62.Tn POSIX
63function
64.Xr clock_gettime 2 .
65.Pp
66The base
67.Dv TIME_UTC
68returns the time since the epoch.
69This time is expressed in seconds and nanoseconds since midnight (0 hour), January 1, 1970.
70In
71.Nx ,
72this corresponds to
73.Dv CLOCK_REALTIME .
74.Pp
75The base
76.Dv TIME_MONOTONIC
77returns the seconds and nanoseconds since an implementation-defined reference
78point in such a way that a second call will never return a value less than the
79first.
80In
81.Nx ,
82this corresponds to
83.Dv CLOCK_MONOTONIC .
84.Pp
85The resolution of each timer can be queried using
86.Fn timespec_getres .
87Each successive call to this function will return the same value for a
88specific clock.
89It is the
90.Tn ISO C
91equivalent to the
92.Tn POSIX
93function
94.Xr clock_getres 2 .
95.Sh RETURN VALUES
96These functions return the passed non-zero value of
97.Fa base
98if successful, otherwise 0 on failure.
99.Sh SEE ALSO
100.Xr clock_gettime 2 ,
101.Xr gettimeofday 2 ,
102.Xr time 3
103.Sh STANDARDS
104The
105.Fn timespec_get
106function with a
107.Fa base
108of
109.Dv TIME_UTC
110conforms to
111.St -isoC-2011 .
112The
113.Fa base
114of
115.Dv TIME_MONOTONIC
116is specified in
117.St -isoC-2023 .
118.Pp
119The
120.Fn timespec_getres
121function conforms to
122.St -isoC-2023 .
123.Sh HISTORY
124The
125.Fn timespec_get
126function first appeared in
127.Nx 8.0 .
128.Pp
129The
130.Fn timespec_getres
131function first appeared in
132.Nx 11.0 .
133.Sh AUTHORS
134.An Kamil Rytarowski Aq Mt kamil@NetBSD.org
135.An Nia Alarie Aq Mt nia@NetBSD.org
136