xref: /illumos-gate/usr/src/man/man3head/time.h.3head (revision bbf21555)
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.
46dea9f5e6SRobert Mustacchi.\" Copyright 2021 Oxide Computer Company
4766492cf0SYuri Pankov.\"
48dea9f5e6SRobert Mustacchi.Dd October 4, 2021
49dea9f5e6SRobert Mustacchi.Dt TIME.H 3HEAD
50dea9f5e6SRobert Mustacchi.Os
51dea9f5e6SRobert Mustacchi.Sh NAME
52dea9f5e6SRobert Mustacchi.Nm time.h ,
53dea9f5e6SRobert Mustacchi.Nm time
54dea9f5e6SRobert Mustacchi.Nd time types
55dea9f5e6SRobert Mustacchi.Sh SYNOPSIS
56dea9f5e6SRobert Mustacchi.In time.h
57dea9f5e6SRobert Mustacchi.Sh DESCRIPTION
58dea9f5e6SRobert MustacchiThe
59dea9f5e6SRobert Mustacchi.In time.h
60dea9f5e6SRobert Mustacchiheader declares the structure
61dea9f5e6SRobert Mustacchi.Vt tm ,
62dea9f5e6SRobert Mustacchiwhich includes the following members:
63dea9f5e6SRobert 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 */
73dea9f5e6SRobert Mustacchi.Ed
74dea9f5e6SRobert Mustacchi.Pp
75dea9f5e6SRobert MustacchiThe value of
76dea9f5e6SRobert Mustacchi.Fa tm_isdst
77dea9f5e6SRobert Mustacchiis positive if Daylight Saving Time is in effect, 0 if Daylight Saving
78dea9f5e6SRobert MustacchiTime is not in effect, and negative if the information is not available.
79dea9f5e6SRobert Mustacchi.Pp
80dea9f5e6SRobert MustacchiThe
81dea9f5e6SRobert Mustacchi.In time.h
82dea9f5e6SRobert Mustacchiheader defines the following symbolic names:
83dea9f5e6SRobert Mustacchi.Bl -tag -width Ds
84dea9f5e6SRobert Mustacchi.It Dv CLOCK_MONOTONIC
85dea9f5e6SRobert MustacchiThe identifier for the system-wide monotonic clock, which is defined as a clock
86dea9f5e6SRobert Mustacchiwhose value cannot be set with
87dea9f5e6SRobert Mustacchi.Fn clock_settime
88dea9f5e6SRobert Mustacchiand that cannot have backward clock jumps.
89dea9f5e6SRobert MustacchiThe maximum possible clock jump is implementation-defined.
90dea9f5e6SRobert MustacchiSee
91dea9f5e6SRobert Mustacchi.Xr clock_settime 3C .
92dea9f5e6SRobert Mustacchi.It Dv CLOCKS_PER_SEC
93dea9f5e6SRobert MustacchiA number used to convert the value returned by the
94dea9f5e6SRobert Mustacchi.Fn clock
95dea9f5e6SRobert Mustacchifunction into seconds.
96dea9f5e6SRobert MustacchiSee
97dea9f5e6SRobert Mustacchi.Xr clock 3C .
98dea9f5e6SRobert Mustacchi.It Dv CLOCK_PROCESS_CPUTIME_ID
99c10c16deSRichard LoweThe identifier of the CPU-time clock associated with the process making a
100dea9f5e6SRobert Mustacchi.Fn clock
101dea9f5e6SRobert Mustacchior
102dea9f5e6SRobert Mustacchi.Fn timer_*
103dea9f5e6SRobert Mustacchifunction call.
104dea9f5e6SRobert MustacchiThis clock includes both user and system CPU-time.
105dea9f5e6SRobert Mustacchi.It Dv CLOCK_REALTIME
106dea9f5e6SRobert MustacchiThe identifier of the system-wide realtime clock.
107dea9f5e6SRobert Mustacchi.It Dv CLOCK_THREAD_CPUTIME_ID
108c10c16deSRichard LoweThe identifier of the CPU-time clock associated with the thread making a
109dea9f5e6SRobert Mustacchi.Fn clock
110dea9f5e6SRobert Mustacchior
111dea9f5e6SRobert Mustacchi.Fn timer_*
112dea9f5e6SRobert Mustacchifunction call.
113dea9f5e6SRobert MustacchiThis clock includes both user and system CPU-time.
114dea9f5e6SRobert Mustacchi.It Dv CLOCK_VIRTUAL
115dea9f5e6SRobert MustacchiThe identifier of the CPU-time clock associated with the thread making a
116dea9f5e6SRobert Mustacchi.Fn clock
117dea9f5e6SRobert Mustacchior
118dea9f5e6SRobert Mustacchi.Fn timer_*
119dea9f5e6SRobert Mustacchifunction call.
120dea9f5e6SRobert MustacchiThis clock only includes user CPU-time.
121dea9f5e6SRobert Mustacchi.It Dv NULL
122dea9f5e6SRobert MustacchiNull pointer constant.
123dea9f5e6SRobert Mustacchi.It Dv TIMER_ABSTIME
124dea9f5e6SRobert MustacchiFlag indicating time is absolute.
125dea9f5e6SRobert MustacchiFor functions taking timer objects, this refers to the clock associated
126dea9f5e6SRobert Mustacchiwith the timer.
127dea9f5e6SRobert Mustacchi.It Dv TIME_UTC
128dea9f5e6SRobert MustacchiThe identifier for the system-wide realtime clock with no time zone
129dea9f5e6SRobert Mustacchitranslation.
130dea9f5e6SRobert MustacchiUsed in
131dea9f5e6SRobert Mustacchi.Fn timespec_get .
132dea9f5e6SRobert Mustacchi.El
133dea9f5e6SRobert Mustacchi.Pp
134dea9f5e6SRobert MustacchiThe
135dea9f5e6SRobert Mustacchi.In time.h
136dea9f5e6SRobert Mustacchiheader declares the
137dea9f5e6SRobert Mustacchi.Vt timespec
138dea9f5e6SRobert Mustacchistructure, which has the following members:
139dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
140c10c16deSRichard Lowetime_t tv_sec     /* seconds */
141c10c16deSRichard Lowelong   tv_nsec     /* nanoseconds */
142dea9f5e6SRobert Mustacchi.Ed
143dea9f5e6SRobert Mustacchi.Pp
144dea9f5e6SRobert MustacchiThe
145dea9f5e6SRobert Mustacchi.In time.h
146dea9f5e6SRobert Mustacchiheader declares the
147dea9f5e6SRobert Mustacchi.Vt itimerspec
148dea9f5e6SRobert Mustacchistructure, which has the following members:
149dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
150c10c16deSRichard Lowestruct timespec it_interval     /* timer period */
151c10c16deSRichard Lowestruct timespec it_value     /* timer expiration */
152dea9f5e6SRobert Mustacchi.Ed
153dea9f5e6SRobert Mustacchi.Pp
154dea9f5e6SRobert MustacchiThe
155dea9f5e6SRobert Mustacchi.Vt clock_t ,
156dea9f5e6SRobert Mustacchi.Vt size_t ,
157dea9f5e6SRobert Mustacchi.Vt time_t ,
158dea9f5e6SRobert Mustacchi.Vt clockid_t ,
159dea9f5e6SRobert Mustacchiand
160dea9f5e6SRobert Mustacchi.Vt timer_t
161dea9f5e6SRobert Mustacchitypes are defined as described in
162dea9f5e6SRobert Mustacchi.In sys/types.h .
163dea9f5e6SRobert MustacchiSee
164dea9f5e6SRobert Mustacchi.Xr types.h 3HEAD .
165dea9f5e6SRobert Mustacchi.Pp
166dea9f5e6SRobert MustacchiAlthough the value of
167dea9f5e6SRobert Mustacchi.Dv CLOCKS_PER_SEC
168dea9f5e6SRobert Mustacchiis required to be 1 million on all standard-conforming systems, it can
169dea9f5e6SRobert Mustacchibe variable on other systems, and it should not be assumed that
170dea9f5e6SRobert Mustacchi.Dv CLOCKS_PER_SEC
171dea9f5e6SRobert Mustacchiis a compile-time constant.
172dea9f5e6SRobert Mustacchi.Pp
173dea9f5e6SRobert MustacchiThe
174dea9f5e6SRobert Mustacchi.In time.h
175dea9f5e6SRobert Mustacchiheader provides a declaration for
176dea9f5e6SRobert Mustacchi.Dv getdate_err .
177dea9f5e6SRobert Mustacchi.Pp
178c10c16deSRichard LoweThe following are declared as variables:
179dea9f5e6SRobert Mustacchi.Bd -literal -offset indent
180c10c16deSRichard Loweextern int daylight;
181c10c16deSRichard Loweextern long timezone;
182c10c16deSRichard Loweextern char *tzname[];
183dea9f5e6SRobert Mustacchi.Ed
184dea9f5e6SRobert Mustacchi.Pp
185dea9f5e6SRobert MustacchiInclusion of the
186dea9f5e6SRobert Mustacchi.In time.h
187dea9f5e6SRobert Mustacchiheader can make visible all symbols from the
188dea9f5e6SRobert Mustacchi.In signal.h
189dea9f5e6SRobert Mustacchiheader.
190dea9f5e6SRobert Mustacchi.Sh USAGE
191dea9f5e6SRobert MustacchiThe range [0,60] for
192dea9f5e6SRobert Mustacchi.Fa tm_sec
193dea9f5e6SRobert Mustacchiallows for the occasional leap second.
194dea9f5e6SRobert Mustacchi.Pp
195dea9f5e6SRobert Mustacchi.Fa tm_year
196dea9f5e6SRobert Mustacchiis a signed value; therefore, years before 1900 can be represented.
197dea9f5e6SRobert Mustacchi.Pp
198dea9f5e6SRobert MustacchiTo obtain the number of clock ticks per second returned by the
199dea9f5e6SRobert Mustacchi.Fn times
200dea9f5e6SRobert Mustacchifunction, applications should call
201dea9f5e6SRobert Mustacchi.Fn sysconf "_SC_CLK_TCK" .
202dea9f5e6SRobert MustacchiSee
203dea9f5e6SRobert Mustacchi.Xr times 2
204dea9f5e6SRobert Mustacchiand
205dea9f5e6SRobert Mustacchi.Xr sysconf 3C .
206dea9f5e6SRobert Mustacchi.Sh INTERFACE STABILITY
207dea9f5e6SRobert Mustacchi.Sy Committed
208dea9f5e6SRobert Mustacchi.Sh SEE ALSO
209dea9f5e6SRobert Mustacchi.Xr time 2 ,
210dea9f5e6SRobert Mustacchi.Xr utime 2 ,
211dea9f5e6SRobert Mustacchi.Xr clock 3C ,
212dea9f5e6SRobert Mustacchi.Xr clock_settime 3C ,
213dea9f5e6SRobert Mustacchi.Xr ctime 3C ,
214dea9f5e6SRobert Mustacchi.Xr difftime 3C ,
215dea9f5e6SRobert Mustacchi.Xr getdate 3C ,
216dea9f5e6SRobert Mustacchi.Xr mktime 3C ,
217dea9f5e6SRobert Mustacchi.Xr nanosleep 3C ,
218dea9f5e6SRobert Mustacchi.Xr strftime 3C ,
219dea9f5e6SRobert Mustacchi.Xr strptime 3C ,
220dea9f5e6SRobert Mustacchi.Xr timer_create 3C ,
221dea9f5e6SRobert Mustacchi.Xr timer_delete 3C ,
222dea9f5e6SRobert Mustacchi.Xr timer_settime 3C ,
223dea9f5e6SRobert Mustacchi.Xr timespec_get 3C ,
224dea9f5e6SRobert Mustacchi.Xr types.h 3HEAD ,
225*bbf21555SRichard Lowe.Xr attributes 7 ,
226*bbf21555SRichard Lowe.Xr standards 7