1/* Copyright (C) 1991-2026 Free Software Foundation, Inc.
2 This file is part of the GNU C Library.
3
4 The GNU C Library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 The GNU C Library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public
15 License along with the GNU C Library; if not, see
16 <https://www.gnu.org/licenses/>. */
17
18/*
19 * ISO C99 Standard: 7.23 Date and time <time.h>
20 */
21
22#ifndef _TIME_H
23#define _TIME_H 1
24
25#include <features.h>
26
27#define __need_size_t
28#define __need_NULL
29#include <stddef.h>
30
31#if __GLIBC_USE (ISOC23)
32# define __STDC_VERSION_TIME_H__ 202311L
33#endif
34
35/* This defines CLOCKS_PER_SEC, which is the number of processor clock
36 ticks per second, and possibly a number of other constants. */
37#include <bits/time.h>
38
39/* Many of the typedefs and structs whose official home is this header
40 may also need to be defined by other headers. */
41#include <bits/types/clock_t.h>
42#include <bits/types/time_t.h>
43#include <bits/types/struct_tm.h>
44
45#if defined __USE_POSIX199309 || defined __USE_ISOC11
46# include <bits/types/struct_timespec.h>
47#endif
48
49#ifdef __USE_POSIX199309
50# include <bits/types/clockid_t.h>
51# include <bits/types/timer_t.h>
52# include <bits/types/struct_itimerspec.h>
53struct sigevent;
54#endif
55
56#ifdef __USE_XOPEN2K
57# ifndef __pid_t_defined
58typedef __pid_t pid_t;
59# define __pid_t_defined
60# endif
61#endif
62
63#ifdef __USE_XOPEN2K8
64# include <bits/types/locale_t.h>
65#endif
66
67#ifdef __USE_ISOC11
68/* Time base values for timespec_get. */
69# define TIME_UTC 1
70#endif
71#if __GLIBC_USE (ISOC23)
72# define TIME_MONOTONIC 2
73# define TIME_ACTIVE 3
74# define TIME_THREAD_ACTIVE 4
75#endif
76
77__BEGIN_DECLS
78
79/* Time used by the program so far (user time + system time).
80 The result / CLOCKS_PER_SEC is program time in seconds. */
81extern clock_t clock (void) __THROW;
82
83#ifndef __USE_TIME64_REDIRECTS
84/* Return the current time and put it in *TIMER if TIMER is not NULL. */
85extern time_t time (time_t *__timer) __THROW;
86
87/* Return the difference between TIME1 and TIME0. */
88extern double difftime (time_t __time1, time_t __time0);
89
90/* Return the `time_t' representation of TP and normalize TP. */
91extern time_t mktime (struct tm *__tp) __THROW;
92#else
93# ifdef __REDIRECT_NTH
94extern time_t __REDIRECT_NTH (time, (time_t *__timer), __time64);
95extern double __REDIRECT_NTH (difftime, (time_t __time1, time_t __time0),
96 __difftime64);
97extern time_t __REDIRECT_NTH (mktime, (struct tm *__tp), __mktime64);
98# else
99# define time __time64
100# define difftime __difftime64
101# define mktime __mktime64
102# endif
103#endif
104
105/* Format TP into S according to FORMAT.
106 Write no more than MAXSIZE characters and return the number
107 of characters written, or 0 if it would exceed MAXSIZE. */
108extern size_t strftime (char *__restrict __s, size_t __maxsize,
109 const char *__restrict __format,
110 const struct tm *__restrict __tp)
111 __THROW __nonnull((1, 3, 4));
112
113#ifdef __USE_XOPEN
114/* Parse S according to FORMAT and store binary time information in TP.
115 The return value is a pointer to the first unparsed character in S. */
116extern char *strptime (const char *__restrict __s,
117 const char *__restrict __fmt, struct tm *__tp)
118 __THROW;
119#endif
120
121#ifdef __USE_XOPEN2K8
122/* Similar to the two functions above but take the information from
123 the provided locale and not the global locale. */
124
125extern size_t strftime_l (char *__restrict __s, size_t __maxsize,
126 const char *__restrict __format,
127 const struct tm *__restrict __tp,
128 locale_t __loc) __THROW;
129#endif
130
131#ifdef __USE_GNU
132extern char *strptime_l (const char *__restrict __s,
133 const char *__restrict __fmt, struct tm *__tp,
134 locale_t __loc) __THROW;
135#endif
136
137
138#ifndef __USE_TIME64_REDIRECTS
139/* Return the `struct tm' representation of *TIMER
140 in Universal Coordinated Time (aka Greenwich Mean Time). */
141extern struct tm *gmtime (const time_t *__timer) __THROW;
142
143/* Return the `struct tm' representation
144 of *TIMER in the local timezone. */
145extern struct tm *localtime (const time_t *__timer) __THROW;
146
147#else
148# ifdef __REDIRECT_NTH
149extern struct tm*__REDIRECT_NTH (gmtime, (const time_t *__timer), __gmtime64);
150extern struct tm *__REDIRECT_NTH (localtime, (const time_t *__timer),
151 __localtime64);
152# else
153# define gmtime __gmtime64
154# define localtime __localtime64
155# endif
156#endif
157
158
159#if defined __USE_POSIX || __GLIBC_USE (ISOC23)
160# ifndef __USE_TIME64_REDIRECTS
161/* Return the `struct tm' representation of *TIMER in UTC,
162 using *TP to store the result. */
163extern struct tm *gmtime_r (const time_t *__restrict __timer,
164 struct tm *__restrict __tp) __THROW;
165
166/* Return the `struct tm' representation of *TIMER in local time,
167 using *TP to store the result. */
168extern struct tm *localtime_r (const time_t *__restrict __timer,
169 struct tm *__restrict __tp) __THROW;
170# else
171# ifdef __REDIRECT_NTH
172extern struct tm*__REDIRECT_NTH (gmtime_r, (const time_t *__restrict __timer,
173 struct tm *__restrict __tp),
174 __gmtime64_r);
175
176extern struct tm*__REDIRECT_NTH (localtime_r, (const time_t *__restrict __t,
177 struct tm *__restrict __tp),
178 __localtime64_r);
179# else
180# define gmtime_r __gmtime64_r
181# define localtime_r __localtime_r
182# endif
183# endif
184#endif /* POSIX || C23 */
185
186/* Return a string of the form "Day Mon dd hh:mm:ss yyyy\n"
187 that is the representation of TP in this format. */
188extern char *asctime (const struct tm *__tp) __THROW;
189
190/* Equivalent to `asctime (localtime (timer))'. */
191#ifndef __USE_TIME64_REDIRECTS
192extern char *ctime (const time_t *__timer) __THROW;
193#else
194# ifdef __REDIRECT_NTH
195extern char *__REDIRECT_NTH (ctime, (const time_t *__timer), __ctime64);
196# else
197# define ctime __ctime64
198# endif
199#endif
200
201#ifdef __USE_POSIX
202/* Reentrant versions of the above functions. */
203
204/* Return in BUF a string of the form "Day Mon dd hh:mm:ss yyyy\n"
205 that is the representation of TP in this format. */
206extern char *asctime_r (const struct tm *__restrict __tp,
207 char *__restrict __buf) __THROW;
208
209/* Equivalent to `asctime_r (localtime_r (timer, *TMP*), buf)'. */
210#ifndef __USE_TIME64_REDIRECTS
211extern char *ctime_r (const time_t *__restrict __timer,
212 char *__restrict __buf) __THROW;
213#else
214# ifdef __REDIRECT_NTH
215extern char *__REDIRECT_NTH (ctime_r, (const time_t *__restrict __timer,
216 char *__restrict __buf), __ctime64_r);
217# else
218# define ctime_r __ctime64_r
219# endif
220#endif
221
222#endif /* POSIX */
223
224
225/* Defined in localtime.c. */
226extern char *__tzname[2]; /* Current time zone abbreviations. */
227extern int __daylight; /* If daylight-saving time is ever in use. */
228extern long int __timezone; /* Seconds west of UTC. */
229
230
231#ifdef __USE_POSIX
232/* Same as above. */
233extern char *tzname[2];
234
235/* Set time conversion information from the TZ environment variable.
236 If TZ is not defined, a locale-dependent default is used. */
237extern void tzset (void) __THROW;
238#endif
239
240#if defined __USE_MISC || defined __USE_XOPEN
241extern int daylight;
242extern long int timezone;
243#endif
244
245
246/* Nonzero if YEAR is a leap year (every 4 years,
247 except every 100th isn't, and every 400th is). */
248#define __isleap(year) \
249 ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0))
250
251
252#if defined __USE_MISC || __GLIBC_USE (ISOC23)
253# ifndef __USE_TIME64_REDIRECTS
254/* Like `mktime', but for TP represents Universal Time, not local time. */
255extern time_t timegm (struct tm *__tp) __THROW;
256# else
257# ifdef __REDIRECT_NTH
258extern time_t __REDIRECT_NTH (timegm, (struct tm *__tp), __timegm64);
259# else
260# define timegm __timegm64
261# endif
262# endif
263#endif
264
265
266#ifdef __USE_MISC
267/* Miscellaneous functions many Unices inherited from the public domain
268 localtime package. These are included only for compatibility. */
269
270#ifndef __USE_TIME64_REDIRECTS
271/* Another name for `mktime'. */
272extern time_t timelocal (struct tm *__tp) __THROW;
273#else
274# ifdef __REDIRECT_NTH
275extern time_t __REDIRECT_NTH (timelocal, (struct tm *__tp), __mktime64);
276# endif
277#endif
278
279/* Return the number of days in YEAR. */
280extern int dysize (int __year) __THROW __attribute__ ((__const__));
281#endif
282
283
284#ifdef __USE_POSIX199309
285# ifndef __USE_TIME64_REDIRECTS
286/* Pause execution for a number of nanoseconds.
287
288 This function is a cancellation point and therefore not marked with
289 __THROW. */
290extern int nanosleep (const struct timespec *__requested_time,
291 struct timespec *__remaining);
292
293/* Get resolution of clock CLOCK_ID. */
294extern int clock_getres (clockid_t __clock_id, struct timespec *__res) __THROW;
295
296/* Get current value of clock CLOCK_ID and store it in TP. */
297extern int clock_gettime (clockid_t __clock_id, struct timespec *__tp)
298 __THROW __nonnull((2));
299
300/* Set clock CLOCK_ID to value TP. */
301extern int clock_settime (clockid_t __clock_id, const struct timespec *__tp)
302 __THROW __nonnull((2));
303# else
304# ifdef __REDIRECT
305extern int __REDIRECT (nanosleep, (const struct timespec *__requested_time,
306 struct timespec *__remaining),
307 __nanosleep64);
308extern int __REDIRECT_NTH (clock_getres, (clockid_t __clock_id,
309 struct timespec *__res),
310 __clock_getres64);
311extern int __REDIRECT_NTH (clock_gettime, (clockid_t __clock_id, struct
312 timespec *__tp), __clock_gettime64)
313 __nonnull((2));
314extern int __REDIRECT_NTH (clock_settime, (clockid_t __clock_id, const struct
315 timespec *__tp), __clock_settime64)
316 __nonnull((2));
317# else
318# define nanosleep __nanosleep64
319# define clock_getres __clock_getres64
320# define clock_gettime __clock_gettime64
321# define clock_settime __clock_settime64
322# endif
323# endif
324
325
326# ifdef __USE_XOPEN2K
327/* High-resolution sleep with the specified clock.
328
329 This function is a cancellation point and therefore not marked with
330 __THROW. */
331# ifndef __USE_TIME64_REDIRECTS
332extern int clock_nanosleep (clockid_t __clock_id, int __flags,
333 const struct timespec *__req,
334 struct timespec *__rem);
335# else
336# ifdef __REDIRECT
337extern int __REDIRECT (clock_nanosleep, (clockid_t __clock_id, int __flags,
338 const struct timespec *__req,
339 struct timespec *__rem),
340 __clock_nanosleep_time64);
341# else
342# define clock_nanosleep __clock_nanosleep_time64
343# endif
344# endif
345
346/* Return clock ID for CPU-time clock. */
347extern int clock_getcpuclockid (pid_t __pid, clockid_t *__clock_id) __THROW;
348# endif
349
350
351/* Create new per-process timer using CLOCK_ID. */
352extern int timer_create (clockid_t __clock_id,
353 struct sigevent *__restrict __evp,
354 timer_t *__restrict __timerid) __THROW;
355
356/* Delete timer TIMERID. */
357extern int timer_delete (timer_t __timerid) __THROW;
358
359/* Set timer TIMERID to VALUE, returning old value in OVALUE. */
360# ifndef __USE_TIME64_REDIRECTS
361extern int timer_settime (timer_t __timerid, int __flags,
362 const struct itimerspec *__restrict __value,
363 struct itimerspec *__restrict __ovalue) __THROW;
364
365/* Get current value of timer TIMERID and store it in VALUE. */
366extern int timer_gettime (timer_t __timerid, struct itimerspec *__value)
367 __THROW;
368# else
369# ifdef __REDIRECT_NTH
370extern int __REDIRECT_NTH (timer_settime, (timer_t __timerid, int __flags,
371 const struct itimerspec *__restrict __value,
372 struct itimerspec *__restrict __ovalue),
373 __timer_settime64);
374
375extern int __REDIRECT_NTH (timer_gettime, (timer_t __timerid,
376 struct itimerspec *__value),
377 __timer_gettime64);
378# else
379# define timer_settime __timer_settime64
380# define timer_gettime __timer_gettime64
381# endif
382# endif
383
384/* Get expiration overrun for timer TIMERID. */
385extern int timer_getoverrun (timer_t __timerid) __THROW;
386#endif
387
388
389#ifdef __USE_ISOC11
390# ifndef __USE_TIME64_REDIRECTS
391/* Set TS to calendar time based in time base BASE. */
392extern int timespec_get (struct timespec *__ts, int __base)
393 __THROW __nonnull ((1));
394# else
395# ifdef __REDIRECT_NTH
396extern int __REDIRECT_NTH (timespec_get, (struct timespec *__ts, int __base),
397 __timespec_get64) __nonnull ((1));
398# else
399# define timespec_get __timespec_get64
400# endif
401# endif
402#endif
403
404
405#if __GLIBC_USE (ISOC23)
406# ifndef __USE_TIME64_REDIRECTS
407/* Set TS to resolution of time base BASE. */
408extern int timespec_getres (struct timespec *__ts, int __base)
409 __THROW;
410# else
411# ifdef __REDIRECT_NTH
412extern int __REDIRECT_NTH (timespec_getres, (struct timespec *__ts,
413 int __base),
414 __timespec_getres64);
415# else
416# define timespec_getres __timespec_getres64
417# endif
418# endif
419#endif
420
421
422#ifdef __USE_XOPEN_EXTENDED
423/* Set to one of the following values to indicate an error.
424 1 the DATEMSK environment variable is null or undefined,
425 2 the template file cannot be opened for reading,
426 3 failed to get file status information,
427 4 the template file is not a regular file,
428 5 an error is encountered while reading the template file,
429 6 memory allication failed (not enough memory available),
430 7 there is no line in the template that matches the input,
431 8 invalid input specification Example: February 31 or a time is
432 specified that can not be represented in a time_t (representing
433 the time in seconds since 00:00:00 UTC, January 1, 1970) */
434extern int getdate_err;
435
436/* Parse the given string as a date specification and return a value
437 representing the value. The templates from the file identified by
438 the environment variable DATEMSK are used. In case of an error
439 `getdate_err' is set.
440
441 This function is a possible cancellation point and therefore not
442 marked with __THROW. */
443extern struct tm *getdate (const char *__string);
444#endif
445
446#ifdef __USE_GNU
447/* Since `getdate' is not reentrant because of the use of `getdate_err'
448 and the static buffer to return the result in, we provide a thread-safe
449 variant. The functionality is the same. The result is returned in
450 the buffer pointed to by RESBUFP and in case of an error the return
451 value is != 0 with the same values as given above for `getdate_err'.
452
453 This function is not part of POSIX and therefore no official
454 cancellation point. But due to similarity with an POSIX interface
455 or due to the implementation it is a cancellation point and
456 therefore not marked with __THROW. */
457extern int getdate_r (const char *__restrict __string,
458 struct tm *__restrict __resbufp);
459#endif
460
461__END_DECLS
462
463#endif /* time.h. */
464