xref: /illumos-gate/usr/src/man/man3head/time.h.3head (revision dea9f5e6)
166492cf0SYuri Pankov.\"
266492cf0SYuri Pankov.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
366492cf0SYuri Pankov.\" permission to reproduce portions of its copyrighted documentation.
466492cf0SYuri Pankov.\" Original documentation from The Open Group can be obtained online at
566492cf0SYuri Pankov.\" http://www.opengroup.org/bookstore/.
666492cf0SYuri Pankov.\"
766492cf0SYuri Pankov.\" The Institute of Electrical and Electronics Engineers and The Open
866492cf0SYuri Pankov.\" Group, have given us permission to reprint portions of their
966492cf0SYuri Pankov.\" documentation.
1066492cf0SYuri Pankov.\"
1166492cf0SYuri Pankov.\" In the following statement, the phrase ``this text'' refers to portions
1266492cf0SYuri Pankov.\" of the system documentation.
1366492cf0SYuri Pankov.\"
1466492cf0SYuri Pankov.\" Portions of this text are reprinted and reproduced in electronic form
1566492cf0SYuri Pankov.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
1666492cf0SYuri Pankov.\" Standard for Information Technology -- Portable Operating System
1766492cf0SYuri Pankov.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
1866492cf0SYuri Pankov.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
1966492cf0SYuri Pankov.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
2066492cf0SYuri Pankov.\" between these versions and the original IEEE and The Open Group
2166492cf0SYuri Pankov.\" Standard, the original IEEE and The Open Group Standard is the referee
2266492cf0SYuri Pankov.\" document.  The original Standard can be obtained online at
2366492cf0SYuri Pankov.\" http://www.opengroup.org/unix/online.html.
2466492cf0SYuri Pankov.\"
2566492cf0SYuri Pankov.\" This notice shall appear on any product containing this material.
2666492cf0SYuri Pankov.\"
2766492cf0SYuri Pankov.\" The contents of this file are subject to the terms of the
2866492cf0SYuri Pankov.\" Common Development and Distribution License (the "License").
2966492cf0SYuri Pankov.\" You may not use this file except in compliance with the License.
3066492cf0SYuri Pankov.\"
3166492cf0SYuri Pankov.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
3266492cf0SYuri Pankov.\" or http://www.opensolaris.org/os/licensing.
3366492cf0SYuri Pankov.\" See the License for the specific language governing permissions
3466492cf0SYuri Pankov.\" and limitations under the License.
3566492cf0SYuri Pankov.\"
3666492cf0SYuri Pankov.\" When distributing Covered Code, include this CDDL HEADER in each
3766492cf0SYuri Pankov.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
3866492cf0SYuri Pankov.\" If applicable, add the following below this CDDL HEADER, with the
3966492cf0SYuri Pankov.\" fields enclosed by brackets "[]" replaced with your own identifying
4066492cf0SYuri Pankov.\" information: Portions Copyright [yyyy] [name of copyright owner]
4166492cf0SYuri Pankov.\"
4266492cf0SYuri Pankov.\"
4366492cf0SYuri Pankov.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
44c10c16deSRichard Lowe.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
45fc2512cfSRobert Mustacchi.\" Copyright 2016 Joyent, Inc.
46*dea9f5e6SRobert Mustacchi.\" Copyright 2021 Oxide Computer Company
4766492cf0SYuri Pankov.\"
48*dea9f5e6SRobert Mustacchi.Dd October 4, 2021
49*dea9f5e6SRobert Mustacchi.Dt TIME.H 3HEAD
50*dea9f5e6SRobert Mustacchi.Os
51*dea9f5e6SRobert Mustacchi.Sh NAME
52*dea9f5e6SRobert Mustacchi.Nm time.h ,
53*dea9f5e6SRobert Mustacchi.Nm time
54*dea9f5e6SRobert Mustacchi.Nd time types
55*dea9f5e6SRobert Mustacchi.Sh SYNOPSIS
56*dea9f5e6SRobert Mustacchi.In time.h
57*dea9f5e6SRobert Mustacchi.Sh DESCRIPTION
58*dea9f5e6SRobert MustacchiThe
59*dea9f5e6SRobert Mustacchi.In time.h
60*dea9f5e6SRobert Mustacchiheader declares the structure
61*dea9f5e6SRobert Mustacchi.Vt tm ,
62*dea9f5e6SRobert Mustacchiwhich includes the following members:
63*dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
64c10c16deSRichard Loweint tm_sec     /* seconds [0,60] */
65c10c16deSRichard Loweint tm_min     /* minutes [0,59] */
66c10c16deSRichard Loweint tm_hour    /* hour [0,23] */
67c10c16deSRichard Loweint tm_mday    /* day of month [1,31] */
68c10c16deSRichard Loweint tm_mon     /* month of year [0,11] */
69c10c16deSRichard Loweint tm_year    /* years since 1900 */
70c10c16deSRichard Loweint tm_wday    /* day of week [0,6] (Sunday =0) */
71c10c16deSRichard Loweint tm_yday    /* day of year [0,365] */
72c10c16deSRichard Loweint tm_isdst   /* daylight savings flag */
73*dea9f5e6SRobert Mustacchi.Ed
74*dea9f5e6SRobert Mustacchi.Pp
75*dea9f5e6SRobert MustacchiThe value of
76*dea9f5e6SRobert Mustacchi.Fa tm_isdst
77*dea9f5e6SRobert Mustacchiis positive if Daylight Saving Time is in effect, 0 if Daylight Saving
78*dea9f5e6SRobert MustacchiTime is not in effect, and negative if the information is not available.
79*dea9f5e6SRobert Mustacchi.Pp
80*dea9f5e6SRobert MustacchiThe
81*dea9f5e6SRobert Mustacchi.In time.h
82*dea9f5e6SRobert Mustacchiheader defines the following symbolic names:
83*dea9f5e6SRobert Mustacchi.Bl -tag -width Ds
84*dea9f5e6SRobert Mustacchi.It Dv CLOCK_MONOTONIC
85*dea9f5e6SRobert MustacchiThe identifier for the system-wide monotonic clock, which is defined as a clock
86*dea9f5e6SRobert Mustacchiwhose value cannot be set with
87*dea9f5e6SRobert Mustacchi.Fn clock_settime
88*dea9f5e6SRobert Mustacchiand that cannot have backward clock jumps.
89*dea9f5e6SRobert MustacchiThe maximum possible clock jump is implementation-defined.
90*dea9f5e6SRobert MustacchiSee
91*dea9f5e6SRobert Mustacchi.Xr clock_settime 3C .
92*dea9f5e6SRobert Mustacchi.It Dv CLOCKS_PER_SEC
93*dea9f5e6SRobert MustacchiA number used to convert the value returned by the
94*dea9f5e6SRobert Mustacchi.Fn clock
95*dea9f5e6SRobert Mustacchifunction into seconds.
96*dea9f5e6SRobert MustacchiSee
97*dea9f5e6SRobert Mustacchi.Xr clock 3C .
98*dea9f5e6SRobert Mustacchi.It Dv CLOCK_PROCESS_CPUTIME_ID
99c10c16deSRichard LoweThe identifier of the CPU-time clock associated with the process making a
100*dea9f5e6SRobert Mustacchi.Fn clock
101*dea9f5e6SRobert Mustacchior
102*dea9f5e6SRobert Mustacchi.Fn timer_*
103*dea9f5e6SRobert Mustacchifunction call.
104*dea9f5e6SRobert MustacchiThis clock includes both user and system CPU-time.
105*dea9f5e6SRobert Mustacchi.It Dv CLOCK_REALTIME
106*dea9f5e6SRobert MustacchiThe identifier of the system-wide realtime clock.
107*dea9f5e6SRobert Mustacchi.It Dv CLOCK_THREAD_CPUTIME_ID
108c10c16deSRichard LoweThe identifier of the CPU-time clock associated with the thread making a
109*dea9f5e6SRobert Mustacchi.Fn clock
110*dea9f5e6SRobert Mustacchior
111*dea9f5e6SRobert Mustacchi.Fn timer_*
112*dea9f5e6SRobert Mustacchifunction call.
113*dea9f5e6SRobert MustacchiThis clock includes both user and system CPU-time.
114*dea9f5e6SRobert Mustacchi.It Dv CLOCK_VIRTUAL
115*dea9f5e6SRobert MustacchiThe identifier of the CPU-time clock associated with the thread making a
116*dea9f5e6SRobert Mustacchi.Fn clock
117*dea9f5e6SRobert Mustacchior
118*dea9f5e6SRobert Mustacchi.Fn timer_*
119*dea9f5e6SRobert Mustacchifunction call.
120*dea9f5e6SRobert MustacchiThis clock only includes user CPU-time.
121*dea9f5e6SRobert Mustacchi.It Dv NULL
122*dea9f5e6SRobert MustacchiNull pointer constant.
123*dea9f5e6SRobert Mustacchi.It Dv TIMER_ABSTIME
124*dea9f5e6SRobert MustacchiFlag indicating time is absolute.
125*dea9f5e6SRobert MustacchiFor functions taking timer objects, this refers to the clock associated
126*dea9f5e6SRobert Mustacchiwith the timer.
127*dea9f5e6SRobert Mustacchi.It Dv TIME_UTC
128*dea9f5e6SRobert MustacchiThe identifier for the system-wide realtime clock with no time zone
129*dea9f5e6SRobert Mustacchitranslation.
130*dea9f5e6SRobert MustacchiUsed in
131*dea9f5e6SRobert Mustacchi.Fn timespec_get .
132*dea9f5e6SRobert Mustacchi.El
133*dea9f5e6SRobert Mustacchi.Pp
134*dea9f5e6SRobert MustacchiThe
135*dea9f5e6SRobert Mustacchi.In time.h
136*dea9f5e6SRobert Mustacchiheader declares the
137*dea9f5e6SRobert Mustacchi.Vt timespec
138*dea9f5e6SRobert Mustacchistructure, which has the following members:
139*dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
140c10c16deSRichard Lowetime_t tv_sec     /* seconds */
141c10c16deSRichard Lowelong   tv_nsec     /* nanoseconds */
142*dea9f5e6SRobert Mustacchi.Ed
143*dea9f5e6SRobert Mustacchi.Pp
144*dea9f5e6SRobert MustacchiThe
145*dea9f5e6SRobert Mustacchi.In time.h
146*dea9f5e6SRobert Mustacchiheader declares the
147*dea9f5e6SRobert Mustacchi.Vt itimerspec
148*dea9f5e6SRobert Mustacchistructure, which has the following members:
149*dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
150c10c16deSRichard Lowestruct timespec it_interval     /* timer period */
151c10c16deSRichard Lowestruct timespec it_value     /* timer expiration */
152*dea9f5e6SRobert Mustacchi.Ed
153*dea9f5e6SRobert Mustacchi.Pp
154*dea9f5e6SRobert MustacchiThe
155*dea9f5e6SRobert Mustacchi.Vt clock_t ,
156*dea9f5e6SRobert Mustacchi.Vt size_t ,
157*dea9f5e6SRobert Mustacchi.Vt time_t ,
158*dea9f5e6SRobert Mustacchi.Vt clockid_t ,
159*dea9f5e6SRobert Mustacchiand
160*dea9f5e6SRobert Mustacchi.Vt timer_t
161*dea9f5e6SRobert Mustacchitypes are defined as described in
162*dea9f5e6SRobert Mustacchi.In sys/types.h .
163*dea9f5e6SRobert MustacchiSee
164*dea9f5e6SRobert Mustacchi.Xr types.h 3HEAD .
165*dea9f5e6SRobert Mustacchi.Pp
166*dea9f5e6SRobert MustacchiAlthough the value of
167*dea9f5e6SRobert Mustacchi.Dv CLOCKS_PER_SEC
168*dea9f5e6SRobert Mustacchiis required to be 1 million on all standard-conforming systems, it can
169*dea9f5e6SRobert Mustacchibe variable on other systems, and it should not be assumed that
170*dea9f5e6SRobert Mustacchi.Dv CLOCKS_PER_SEC
171*dea9f5e6SRobert Mustacchiis a compile-time constant.
172*dea9f5e6SRobert Mustacchi.Pp
173*dea9f5e6SRobert MustacchiThe
174*dea9f5e6SRobert Mustacchi.In time.h
175*dea9f5e6SRobert Mustacchiheader provides a declaration for
176*dea9f5e6SRobert Mustacchi.Dv getdate_err .
177*dea9f5e6SRobert Mustacchi.Pp
178c10c16deSRichard LoweThe following are declared as variables:
179*dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
180c10c16deSRichard Loweextern int daylight;
181c10c16deSRichard Loweextern long timezone;
182c10c16deSRichard Loweextern char *tzname[];
183*dea9f5e6SRobert Mustacchi.Ed
184*dea9f5e6SRobert Mustacchi.Pp
185*dea9f5e6SRobert MustacchiInclusion of the
186*dea9f5e6SRobert Mustacchi.In time.h
187*dea9f5e6SRobert Mustacchiheader can make visible all symbols from the
188*dea9f5e6SRobert Mustacchi.In signal.h
189*dea9f5e6SRobert Mustacchiheader.
190*dea9f5e6SRobert Mustacchi.Sh USAGE
191*dea9f5e6SRobert MustacchiThe range [0,60] for
192*dea9f5e6SRobert Mustacchi.Fa tm_sec
193*dea9f5e6SRobert Mustacchiallows for the occasional leap second.
194*dea9f5e6SRobert Mustacchi.Pp
195*dea9f5e6SRobert Mustacchi.Fa tm_year
196*dea9f5e6SRobert Mustacchiis a signed value; therefore, years before 1900 can be represented.
197*dea9f5e6SRobert Mustacchi.Pp
198*dea9f5e6SRobert MustacchiTo obtain the number of clock ticks per second returned by the
199*dea9f5e6SRobert Mustacchi.Fn times
200*dea9f5e6SRobert Mustacchifunction, applications should call
201*dea9f5e6SRobert Mustacchi.Fn sysconf "_SC_CLK_TCK" .
202*dea9f5e6SRobert MustacchiSee
203*dea9f5e6SRobert Mustacchi.Xr times 2
204*dea9f5e6SRobert Mustacchiand
205*dea9f5e6SRobert Mustacchi.Xr sysconf 3C .
206*dea9f5e6SRobert Mustacchi.Sh INTERFACE STABILITY
207*dea9f5e6SRobert Mustacchi.Sy Committed
208*dea9f5e6SRobert Mustacchi.Sh SEE ALSO
209*dea9f5e6SRobert Mustacchi.Xr time 2 ,
210*dea9f5e6SRobert Mustacchi.Xr utime 2 ,
211*dea9f5e6SRobert Mustacchi.Xr clock 3C ,
212*dea9f5e6SRobert Mustacchi.Xr clock_settime 3C ,
213*dea9f5e6SRobert Mustacchi.Xr ctime 3C ,
214*dea9f5e6SRobert Mustacchi.Xr difftime 3C ,
215*dea9f5e6SRobert Mustacchi.Xr getdate 3C ,
216*dea9f5e6SRobert Mustacchi.Xr mktime 3C ,
217*dea9f5e6SRobert Mustacchi.Xr nanosleep 3C ,
218*dea9f5e6SRobert Mustacchi.Xr strftime 3C ,
219*dea9f5e6SRobert Mustacchi.Xr strptime 3C ,
220*dea9f5e6SRobert Mustacchi.Xr timer_create 3C ,
221*dea9f5e6SRobert Mustacchi.Xr timer_delete 3C ,
222*dea9f5e6SRobert Mustacchi.Xr timer_settime 3C ,
223*dea9f5e6SRobert Mustacchi.Xr timespec_get 3C ,
224*dea9f5e6SRobert Mustacchi.Xr types.h 3HEAD ,
225*dea9f5e6SRobert Mustacchi.Xr attributes 5 ,
226*dea9f5e6SRobert Mustacchi.Xr standards 5