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 2016 Joyent, Inc. 13.\" Copyright 2025 Oxide Computer Company 14.\" 15.Dd "January 12, 2025" 16.Dt TIMESPEC_GET 3C 17.Os 18.Sh NAME 19.Nm timespec_get , 20.Nm timespec_getres 21.Nd get time information 22.Sh SYNOPSIS 23.In time.h 24.Ft int 25.Fo timespec_get 26.Fa "struct timespec *ts" 27.Fa "int base" 28.Fc 29.Ft int 30.Fo timespec_getres 31.Fa "struct timespec *ts" 32.Fa "int base" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn timespec_get 37function provides access to nanosecond resolution time. 38The 39.Fn timespec_getres 40function provides access to the underlying clock's resolution. 41The meaning and source of time is defined by the 42.Fa base 43argument. 44The following values are defined for 45.Fa base : 46.Bl -tag -width Ds 47.It Dv TIME_UTC 48Obtain the current time of day from the realtime clock on the system. 49It represents the amount of time in second and nanoseconds since the Epoch. 50This is logically equivalent to calling 51.Xr clock_gettime 3C 52with 53.Dv CLOCK_REALTIME . 54.It Dv TIME_MONOTONIC 55The system's monotonic clock is a non-adjustable, high-resolution clock. 56The returned value is not subject to adjustments from time of day drift 57nor can it be set. 58This clock is generally only useful for measuring elapsed time relative 59to a prior reading. 60This is logically equivalent to using the 61.Dv CLOCK_HIGHRES 62and 63.Dv CLOCK_MONOTONIC 64clocks or calling 65.Xr gethrtime 3C . 66.It Dv TIME_THREAD_ACTIVE 67This clock measures the elapsed system and user CPU-time of the current 68thread. 69The amount of time it has spent executing code is measured in seconds 70and nanoseconds. 71The 72.Fa pr_utime 73member of the 74.Vt lwpsinfo_t 75or 76.Vt prusage_t 77structures discussed in 78.Xr proc 5 79are alternative ways to see the user component. 80The system component is a combination of both the system and trap time 81that the thread has experienced. 82In the 83.Vt lwpsinfo_t 84this is covered solely by the 85.Fa pr_stime 86member. 87For the 88.Vt prusage_t 89these are separated out into the 90.Fa pr_stime 91and 92.Fa pr_ttime 93members respectively. 94.Pp 95This is logically equivalent to using the 96.Dv CLOCK_THREAD_CPUTIME_ID 97clock . 98This clock is optional and may not be present on other platforms. 99.It Dv TIME_THREAD_ACTIVE_USR 100This clock is similar to the 101.Dv TIME_THREAD_ACTIVE 102clock, except it only counts user time that has elapsed. 103This is logically equivalent to using the 104.Dv CLOCK_VIRTUAL 105clock or calling 106.Xr gethrvtime 3C . 107This clock is an extension and may not be available on other platforms. 108.It Dv TIME_ACTIVE 109This clock measures the elapsed system and user CPU-time of the current 110process, including all of its threads. 111None of the process's children are counted in this measure, whether 112running or terminated. 113The value read here will be the same as combining the corresponding 114.Xr proc 5 115.Vt psinfo_t 116structure's 117.Fa pr_stime 118and 119.Fa pr_utime 120members. 121This clock is optional and may not be present on other platforms. 122.El 123.Pp 124For the definition of the 125.Vt timespec 126structure, see 127.Xr time.h 3HEAD . 128.Sh RETURN VALUES 129Upon successful completion, the 130.Fn timespec_get 131and 132.Fn timespec_getres 133functions return the passed in value of 134.Fa base . 135Otherwise, 136.Sy 0 137is returned to represent an error. 138.Sh ERRORS 139Unlike other functions, the 140.Fn timespec_get 141and 142.Fn timespec_getres 143functions are not defined to set 144.Vt errno . 145However, the 146.Fn timespec_get 147and 148.Fn timespec_getres 149functions will fail if: 150.Bl -bullet -offset indent 151.It 152The value of 153.Fa base 154does not refer to a known time specification. 155.It 156There was an error obtaining the time for 157.Fa base . 158.El 159.Sh INTERFACE STABILITY 160.Sy Standard 161.Sh MT-LEVEL 162.Sy MT-Safe 163.Sh SEE ALSO 164.Xr clock_getres 3C , 165.Xr clock_gettime 3C , 166.Xr gethrtime 3C , 167.Xr gethrvtime 3C , 168.Xr time.h 3HEAD , 169.Xr attributes 7 170