path: root/time/time.h

/* Copyright (C) 1991-2025 Free Software Foundation, Inc.
   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the GNU C Library; if not, see
   <https://www.gnu.org/licenses/>.  */

/*
 *	ISO C99 Standard: 7.23 Date and time	<time.h>
 */

#ifndef	_TIME_H
#define _TIME_H	1

#include <features.h>

#define __need_size_t
#define __need_NULL
#include <stddef.h>

/* This defines CLOCKS_PER_SEC, which is the number of processor clock
   ticks per second, and possibly a number of other constants.   */
#include <bits/time.h>

/* Many of the typedefs and structs whose official home is this header
   may also need to be defined by other headers.  */
#include <bits/types/clock_t.h>
#include <bits/types/time_t.h>
#include <bits/types/struct_tm.h>

#if defined __USE_POSIX199309 || defined __USE_ISOC11
# include <bits/types/struct_timespec.h>
#endif

#ifdef __USE_POSIX199309
# include <bits/types/clockid_t.h>
# include <bits/types/timer_t.h>
# include <bits/types/struct_itimerspec.h>
struct sigevent;
#endif

#ifdef __USE_XOPEN2K
# ifndef __pid_t_defined
typedef __pid_t pid_t;
#  define __pid_t_defined
# endif
#endif

#ifdef __USE_XOPEN2K8
# include <bits/types/locale_t.h>
#endif

#ifdef __USE_ISOC11
/* Time base values for timespec_get.  */
# define TIME_UTC 1
#endif

__BEGIN_DECLS

/* Time used by the program so far (user time + system time).
   The result / CLOCKS_PER_SEC is program time in seconds.  */
extern clock_t clock (void) __THROW;

#ifndef __USE_TIME64_REDIRECTS
/* Return the current time and put it in *TIMER if TIMER is not NULL.  */
extern time_t time (time_t *__timer) __THROW;

/* Return the difference between TIME1 and TIME0.  */
extern double difftime (time_t __time1, time_t __time0);

/* Return the `time_t' representation of TP and normalize TP.  */
extern time_t mktime (struct tm *__tp) __THROW;
#else
# ifdef __REDIRECT_NTH
extern time_t __REDIRECT_NTH (time, (time_t *__timer), __time64);
extern double __REDIRECT_NTH (difftime, (time_t __time1, time_t __time0),
                              __difftime64);
extern time_t __REDIRECT_NTH (mktime, (struct tm *__tp), __mktime64);
# else
#  define time __time64
#  define difftime __difftime64
#  define mktime __mktime64
# endif
#endif

/* Format TP into S according to FORMAT.
   Write no more than MAXSIZE characters and return the number
   of characters written, or 0 if it would exceed MAXSIZE.  */
extern size_t strftime (char *__restrict __s, size_t __maxsize,
			const char *__restrict __format,
			const struct tm *__restrict __tp)
			__THROW __nonnull((1, 3, 4));

#ifdef __USE_XOPEN
/* Parse S according to FORMAT and store binary time information in TP.
   The return value is a pointer to the first unparsed character in S.  */
extern char *strptime (const char *__restrict __s,
		       const char *__restrict __fmt, struct tm *__tp)
     __THROW;
#endif

#ifdef __USE_XOPEN2K8
/* Similar to the two functions above but take the information from
   the provided locale and not the global locale.  */

extern size_t strftime_l (char *__restrict __s, size_t __maxsize,
			  const char *__restrict __format,
			  const struct tm *__restrict __tp,
			  locale_t __loc) __THROW;
#endif

#ifdef __USE_GNU
extern char *strptime_l (const char *__restrict __s,
			 const char *__restrict __fmt, struct tm *__tp,
			 locale_t __loc) __THROW;
#endif


#ifndef __USE_TIME64_REDIRECTS
/* Return the `struct tm' representation of *TIMER
   in Universal Coordinated Time (aka Greenwich Mean Time).  */
extern struct tm *gmtime (const time_t *__timer) __THROW;

/* Return the `struct tm' representation
   of *TIMER in the local timezone.  */
extern struct tm *localtime (const time_t *__timer) __THROW;

#else
# ifdef __REDIRECT_NTH
extern struct tm*__REDIRECT_NTH (gmtime, (const time_t *__timer), __gmtime64);
extern struct tm *__REDIRECT_NTH (localtime, (const time_t *__timer),
				  __localtime64);
# else
#  define gmtime __gmtime64
#  define localtime __localtime64
# endif
#endif


#if defined __USE_POSIX || __GLIBC_USE (ISOC23)
# ifndef __USE_TIME64_REDIRECTS
/* Return the `struct tm' representation of *TIMER in UTC,
   using *TP to store the result.  */
extern struct tm *gmtime_r (const time_t *__restrict __timer,
			    struct tm *__restrict __tp) __THROW;

/* Return the `struct tm' representation of *TIMER in local time,
   using *TP to store the result.  */
extern struct tm *localtime_r (const time_t *__restrict __timer,
			       struct tm *__restrict __tp) __THROW;
# else
#  ifdef __REDIRECT_NTH
extern struct tm*__REDIRECT_NTH (gmtime_r, (const time_t *__restrict __timer,
                                            struct tm *__restrict __tp),
                                 __gmtime64_r);

extern struct tm*__REDIRECT_NTH (localtime_r, (const time_t *__restrict __t,
                                               struct tm *__restrict __tp),
                                 __localtime64_r);
#  else
#   define gmtime_r __gmtime64_r
#   define localtime_r __localtime_r
#  endif
# endif
#endif	/* POSIX || C23 */

/* Return a string of the form "Day Mon dd hh:mm:ss yyyy\n"
   that is the representation of TP in this format.  */
extern char *asctime (const struct tm *__tp) __THROW;

/* Equivalent to `asctime (localtime (timer))'.  */
#ifndef __USE_TIME64_REDIRECTS
extern char *ctime (const time_t