lib/time.in.h

   1 /* A more-standard <time.h>.
   2
   3    Copyright (C) 2007-2024 Free Software Foundation, Inc.
   4
   5    This file is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU Lesser General Public License as
   7    published by the Free Software Foundation; either version 2.1 of the
   8    License, or (at your option) any later version.
   9
  10    This file is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 #if __GNUC__ >= 3
  19 @PRAGMA_SYSTEM_HEADER@
  20 #endif
  21 @PRAGMA_COLUMNS@
  22
  23 /* This file uses #include_next of a system file that defines time_t.
  24    For the 'year2038' module to work right, <config.h> needs to have been
  25    included before.  */
  26 #if !_GL_CONFIG_H_INCLUDED
  27  #error "Please include config.h first."
  28 #endif
  29
  30 /* Don't get in the way of glibc when it includes time.h merely to
  31    declare a few standard symbols, rather than to declare all the
  32    symbols.  (However, skip this for MinGW as it treats __need_time_t
  33    incompatibly.)  Also, Solaris 8 <time.h> eventually includes itself
  34    recursively; if that is happening, just include the system <time.h>
  35    without adding our own declarations.  */
  36 #if (((defined __need_time_t || defined __need_clock_t \
  37        || defined __need_timespec)                     \
  38       && !defined __MINGW32__)                         \
  39      || defined _@GUARD_PREFIX@_TIME_H)
  40
  41 # @INCLUDE_NEXT@ @NEXT_TIME_H@
  42
  43 #else
  44
  45 # define _@GUARD_PREFIX@_TIME_H
  46
  47 /* mingw's <time.h> provides the functions asctime_r, ctime_r, gmtime_r,
  48    localtime_r only if <unistd.h> or <pthread.h> has been included before.  */
  49 # if defined __MINGW32__
  50 #  include <unistd.h>
  51 # endif
  52
  53 # @INCLUDE_NEXT@ @NEXT_TIME_H@
  54
  55 /* This file uses _GL_ATTRIBUTE_DEPRECATED, GNULIB_POSIXCHECK,
  56    HAVE_RAW_DECL_*.  */
  57 # if !_GL_CONFIG_H_INCLUDED
  58 #  error "Please include config.h first."
  59 # endif
  60
  61 /* NetBSD 5.0 mis-defines NULL.  */
  62 # include <stddef.h>
  63
  64 /* The definitions of _GL_FUNCDECL_RPL etc. are copied here.  */
  65
  66 /* The definition of _GL_ARG_NONNULL is copied here.  */
  67
  68 /* The definition of _GL_WARN_ON_USE is copied here.  */
  69
  70 /* Some systems don't define struct timespec (e.g., AIX 4.1).
  71    Or they define it with the wrong member names or define it in <sys/time.h>
  72    (e.g., FreeBSD circa 1997).  Stock Mingw prior to 3.0 does not define it,
  73    but the pthreads-win32 library defines it in <pthread.h>.  */
  74 # if ! @TIME_H_DEFINES_STRUCT_TIMESPEC@
  75 #  if @SYS_TIME_H_DEFINES_STRUCT_TIMESPEC@
  76 #   include <sys/time.h>
  77 #  elif @PTHREAD_H_DEFINES_STRUCT_TIMESPEC@
  78 #   include <pthread.h>
  79 #  elif @UNISTD_H_DEFINES_STRUCT_TIMESPEC@
  80 #   include <unistd.h>
  81 #  else
  82
  83 #   ifdef __cplusplus
  84 extern "C" {
  85 #   endif
  86
  87 #   if !GNULIB_defined_struct_timespec
  88 #    undef timespec
  89 #    define timespec rpl_timespec
  90 struct timespec
  91 {
  92   time_t tv_sec;
  93   long int tv_nsec;
  94 };
  95 #    define GNULIB_defined_struct_timespec 1
  96 #   endif
  97
  98 #   ifdef __cplusplus
  99 }
 100 #   endif
 101
 102 #  endif
 103 # endif
 104
 105 # if !GNULIB_defined_struct_time_t_must_be_integral
 106 /* https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_types.h.html
 107    requires time_t to be an integer type, even though C99 permits floating
 108    point.  We don't know of any implementation that uses floating
 109    point, and it is much easier to write code that doesn't have to
 110    worry about that corner case, so we force the issue.  */
 111 struct __time_t_must_be_integral {
 112   unsigned int __floating_time_t_unsupported : (time_t) 1;
 113 };
 114 #  define GNULIB_defined_struct_time_t_must_be_integral 1
 115 # endif
 116
 117 /* Define TIME_UTC, a positive integer constant used for timespec_get().  */
 118 # if ! @TIME_H_DEFINES_TIME_UTC@
 119 #  if !GNULIB_defined_TIME_UTC
 120 #   define TIME_UTC 1
 121 #   define GNULIB_defined_TIME_UTC 1
 122 #  endif
 123 # endif
 124
 125 /* Set *TS to the current time, and return BASE.
 126    Upon failure, return 0.  */
 127 # if @GNULIB_TIMESPEC_GET@
 128 #  if @REPLACE_TIMESPEC_GET@
 129 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 130 #    undef timespec_get
 131 #    define timespec_get rpl_timespec_get
 132 #   endif
 133 _GL_FUNCDECL_RPL (timespec_get, int, (struct timespec *ts, int base)
 134                                      _GL_ARG_NONNULL ((1)));
 135 _GL_CXXALIAS_RPL (timespec_get, int, (struct timespec *ts, int base));
 136 #  else
 137 #   if !@HAVE_TIMESPEC_GET@
 138 _GL_FUNCDECL_SYS (timespec_get, int, (struct timespec *ts, int base)
 139                                      _GL_ARG_NONNULL ((1)));
 140 #   endif
 141 _GL_CXXALIAS_SYS (timespec_get, int, (struct timespec *ts, int base));
 142 #  endif
 143 #  if __GLIBC__ >= 2
 144 _GL_CXXALIASWARN (timespec_get);
 145 #  endif
 146 # elif defined GNULIB_POSIXCHECK
 147 #  undef timespec_get
 148 #  if HAVE_RAW_DECL_TIMESPEC_GET
 149 _GL_WARN_ON_USE (timespec_get, "timespec_get is unportable - "
 150                  "use gnulib module timespec_get for portability");
 151 #  endif
 152 # endif
 153
 154 /* Set *TS to the current time resolution, and return BASE.
 155    Upon failure, return 0.  */
 156 # if @GNULIB_TIMESPEC_GETRES@
 157 #  if @REPLACE_TIMESPEC_GETRES@
 158 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 159 #    undef timespec_getres
 160 #    define timespec_getres rpl_timespec_getres
 161 #   endif
 162 _GL_FUNCDECL_RPL (timespec_getres, int, (struct timespec *ts, int base)
 163                                         _GL_ARG_NONNULL ((1)));
 164 _GL_CXXALIAS_RPL (timespec_getres, int, (struct timespec *ts, int base));
 165 #  else
 166 #   if !@HAVE_TIMESPEC_GETRES@
 167 _GL_FUNCDECL_SYS (timespec_getres, int, (struct timespec *ts, int base)
 168                                         _GL_ARG_NONNULL ((1)));
 169 #   endif
 170 _GL_CXXALIAS_SYS (timespec_getres, int, (struct timespec *ts, int base));
 171 #  endif
 172 _GL_CXXALIASWARN (timespec_getres);
 173 # elif defined GNULIB_POSIXCHECK
 174 #  undef timespec_getres
 175 #  if HAVE_RAW_DECL_TIMESPEC_GETRES
 176 _GL_WARN_ON_USE (timespec_getres, "timespec_getres is unportable - "
 177                  "use gnulib module timespec_getres for portability");
 178 #  endif
 179 # endif
 180
 181 /* Return the number of seconds that have elapsed since the Epoch.  */
 182 # if @GNULIB_TIME@
 183 #  if @REPLACE_TIME@
 184 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 185 #    define time rpl_time
 186 #   endif
 187 _GL_FUNCDECL_RPL (time, time_t, (time_t *__tp));
 188 _GL_CXXALIAS_RPL (time, time_t, (time_t *__tp));
 189 #  else
 190 _GL_CXXALIAS_SYS (time, time_t, (time_t *__tp));
 191 #  endif
 192 #  if __GLIBC__ >= 2
 193 _GL_CXXALIASWARN (time);
 194 #  endif
 195 # elif defined GNULIB_POSIXCHECK
 196 #  undef time
 197 #  if HAVE_RAW_DECL_TIME
 198 _GL_WARN_ON_USE (time, "time has consistency problems - "
 199                  "use gnulib module time for portability");
 200 #  endif
 201 # endif
 202
 203 /* Sleep for at least RQTP seconds unless interrupted,  If interrupted,
 204    return -1 and store the remaining time into RMTP.  See
 205    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html>.  */
 206 # if @GNULIB_NANOSLEEP@
 207 #  if @REPLACE_NANOSLEEP@
 208 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 209 #    define nanosleep rpl_nanosleep
 210 #   endif
 211 _GL_FUNCDECL_RPL (nanosleep, int,
 212                   (struct timespec const *__rqtp, struct timespec *__rmtp)
 213                   _GL_ARG_NONNULL ((1)));
 214 _GL_CXXALIAS_RPL (nanosleep, int,
 215                   (struct timespec const *__rqtp, struct timespec *__rmtp));
 216 #  else
 217 #   if ! @HAVE_NANOSLEEP@
 218 _GL_FUNCDECL_SYS (nanosleep, int,
 219                   (struct timespec const *__rqtp, struct timespec *__rmtp)
 220                   _GL_ARG_NONNULL ((1)));
 221 #   endif
 222 _GL_CXXALIAS_SYS (nanosleep, int,
 223                   (struct timespec const *__rqtp, struct timespec *__rmtp));
 224 #  endif
 225 _GL_CXXALIASWARN (nanosleep);
 226 # elif defined GNULIB_POSIXCHECK
 227 #  undef nanosleep
 228 #  if HAVE_RAW_DECL_NANOSLEEP
 229 _GL_WARN_ON_USE (nanosleep, "nanosleep is unportable - "
 230                  "use gnulib module nanosleep for portability");
 231 #  endif
 232 # endif
 233
 234 /* Initialize time conversion information.  */
 235 # if @GNULIB_TZSET@
 236 #  if @REPLACE_TZSET@
 237 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 238 #    undef tzset
 239 #    define tzset rpl_tzset
 240 #   endif
 241 _GL_FUNCDECL_RPL (tzset, void, (void));
 242 _GL_CXXALIAS_RPL (tzset, void, (void));
 243 #  elif defined _WIN32 && !defined __CYGWIN__
 244 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 245 #    undef tzset
 246 #    define tzset _tzset
 247 #   endif
 248 _GL_CXXALIAS_MDA (tzset, void, (void));
 249 #  else
 250 _GL_CXXALIAS_SYS (tzset, void, (void));
 251 #  endif
 252 _GL_CXXALIASWARN (tzset);
 253 # elif @GNULIB_MDA_TZSET@
 254 /* On native Windows, map 'tzset' to '_tzset', so that -loldnames is not
 255    required.  In C++ with GNULIB_NAMESPACE, avoid differences between
 256    platforms by defining GNULIB_NAMESPACE::tzset always.  */
 257 #  if defined _WIN32 && !defined __CYGWIN__
 258 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 259 #    undef tzset
 260 #    define tzset _tzset
 261 #   endif
 262 _GL_CXXALIAS_MDA (tzset, void, (void));
 263 #  else
 264 _GL_CXXALIAS_SYS (tzset, void, (void));
 265 #  endif
 266 _GL_CXXALIASWARN (tzset);
 267 # elif defined GNULIB_POSIXCHECK
 268 #  undef tzset
 269 #  if HAVE_RAW_DECL_TZSET
 270 _GL_WARN_ON_USE (tzset, "tzset has portability problems - "
 271                  "use gnulib module tzset for portability");
 272 #  endif
 273 # endif
 274
 275 /* Return the 'time_t' representation of TP and normalize TP.  */
 276 # if @GNULIB_MKTIME@
 277 #  if @REPLACE_MKTIME@
 278 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 279 #    define mktime rpl_mktime
 280 #   endif
 281 _GL_FUNCDECL_RPL (mktime, time_t, (struct tm *__tp) _GL_ARG_NONNULL ((1)));
 282 _GL_CXXALIAS_RPL (mktime, time_t, (struct tm *__tp));
 283 #  else
 284 _GL_CXXALIAS_SYS (mktime, time_t, (struct tm *__tp));
 285 #  endif
 286 #  if __GLIBC__ >= 2
 287 _GL_CXXALIASWARN (mktime);
 288 #  endif
 289 # elif defined GNULIB_POSIXCHECK
 290 #  undef mktime
 291 #  if HAVE_RAW_DECL_MKTIME
 292 _GL_WARN_ON_USE (mktime, "mktime has portability problems - "
 293                  "use gnulib module mktime for portability");
 294 #  endif
 295 # endif
 296
 297 /* Convert TIMER to RESULT, assuming local time and UTC respectively.  See
 298    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/localtime_r.html> and
 299    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/gmtime_r.html>.  */
 300 # if @GNULIB_TIME_R@
 301 #  if @REPLACE_LOCALTIME_R@
 302 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 303 #    undef localtime_r
 304 #    define localtime_r rpl_localtime_r
 305 #   endif
 306 _GL_FUNCDECL_RPL (localtime_r, struct tm *, (time_t const *restrict __timer,
 307                                              struct tm *restrict __result)
 308                                             _GL_ARG_NONNULL ((1, 2)));
 309 _GL_CXXALIAS_RPL (localtime_r, struct tm *, (time_t const *restrict __timer,
 310                                              struct tm *restrict __result));
 311 #  else
 312 #   if ! @HAVE_DECL_LOCALTIME_R@
 313 _GL_FUNCDECL_SYS (localtime_r, struct tm *, (time_t const *restrict __timer,
 314                                              struct tm *restrict __result)
 315                                             _GL_ARG_NONNULL ((1, 2)));
 316 #   endif
 317 _GL_CXXALIAS_SYS (localtime_r, struct tm *, (time_t const *restrict __timer,
 318                                              struct tm *restrict __result));
 319 #  endif
 320 #  if @HAVE_DECL_LOCALTIME_R@
 321 _GL_CXXALIASWARN (localtime_r);
 322 #  endif
 323 #  if @REPLACE_LOCALTIME_R@
 324 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 325 #    undef gmtime_r
 326 #    define gmtime_r rpl_gmtime_r
 327 #   endif
 328 _GL_FUNCDECL_RPL (gmtime_r, struct tm *, (time_t const *restrict __timer,
 329                                           struct tm *restrict __result)
 330                                          _GL_ARG_NONNULL ((1, 2)));
 331 _GL_CXXALIAS_RPL (gmtime_r, struct tm *, (time_t const *restrict __timer,
 332                                           struct tm *restrict __result));
 333 #  else
 334 #   if ! @HAVE_DECL_LOCALTIME_R@
 335 _GL_FUNCDECL_SYS (gmtime_r, struct tm *, (time_t const *restrict __timer,
 336                                           struct tm *restrict __result)
 337                                          _GL_ARG_NONNULL ((1, 2)));
 338 #   endif
 339 _GL_CXXALIAS_SYS (gmtime_r, struct tm *, (time_t const *restrict __timer,
 340                                           struct tm *restrict __result));
 341 #  endif
 342 #  if @HAVE_DECL_LOCALTIME_R@
 343 _GL_CXXALIASWARN (gmtime_r);
 344 #  endif
 345 # elif defined GNULIB_POSIXCHECK
 346 #  undef localtime_r
 347 #  if HAVE_RAW_DECL_LOCALTIME_R
 348 _GL_WARN_ON_USE (localtime_r, "localtime_r is unportable - "
 349                  "use gnulib module time_r for portability");
 350 #  endif
 351 #  undef gmtime_r
 352 #  if HAVE_RAW_DECL_GMTIME_R
 353 _GL_WARN_ON_USE (gmtime_r, "gmtime_r is unportable - "
 354                  "use gnulib module time_r for portability");
 355 #  endif
 356 # endif
 357
 358 /* Convert TIMER to RESULT, assuming local time and UTC respectively.  See
 359    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/localtime.html> and
 360    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/gmtime.html>.  */
 361 # if @GNULIB_LOCALTIME@ || @REPLACE_LOCALTIME@
 362 #  if @REPLACE_LOCALTIME@
 363 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 364 #    undef localtime
 365 #    define localtime rpl_localtime
 366 #   endif
 367 _GL_FUNCDECL_RPL (localtime, struct tm *, (time_t const *__timer)
 368                                           _GL_ARG_NONNULL ((1)));
 369 _GL_CXXALIAS_RPL (localtime, struct tm *, (time_t const *__timer));
 370 #  else
 371 _GL_CXXALIAS_SYS (localtime, struct tm *, (time_t const *__timer));
 372 #  endif
 373 #  if __GLIBC__ >= 2
 374 _GL_CXXALIASWARN (localtime);
 375 #  endif
 376 # elif defined GNULIB_POSIXCHECK
 377 #  undef localtime
 378 #  if HAVE_RAW_DECL_LOCALTIME
 379 _GL_WARN_ON_USE (localtime, "localtime has portability problems - "
 380                  "use gnulib module localtime for portability");
 381 #  endif
 382 # endif
 383
 384 # if 0 || @REPLACE_GMTIME@
 385 #  if @REPLACE_GMTIME@
 386 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 387 #    undef gmtime
 388 #    define gmtime rpl_gmtime
 389 #   endif
 390 _GL_FUNCDECL_RPL (gmtime, struct tm *, (time_t const *__timer)
 391                                        _GL_ARG_NONNULL ((1)));
 392 _GL_CXXALIAS_RPL (gmtime, struct tm *, (time_t const *__timer));
 393 #  else
 394 _GL_CXXALIAS_SYS (gmtime, struct tm *, (time_t const *__timer));
 395 #  endif
 396 _GL_CXXALIASWARN (gmtime);
 397 # endif
 398
 399 /* Parse BUF as a timestamp, assuming FORMAT specifies its layout, and store
 400    the resulting broken-down time into TM.  See
 401    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/strptime.html>.  */
 402 # if @GNULIB_STRPTIME@
 403 #  if ! @HAVE_STRPTIME@
 404 _GL_FUNCDECL_SYS (strptime, char *, (char const *restrict __buf,
 405                                      char const *restrict __format,
 406                                      struct tm *restrict __tm)
 407                                     _GL_ARG_NONNULL ((1, 2, 3)));
 408 #  endif
 409 _GL_CXXALIAS_SYS (strptime, char *, (char const *restrict __buf,
 410                                      char const *restrict __format,
 411                                      struct tm *restrict __tm));
 412 _GL_CXXALIASWARN (strptime);
 413 # elif defined GNULIB_POSIXCHECK
 414 #  undef strptime
 415 #  if HAVE_RAW_DECL_STRPTIME
 416 _GL_WARN_ON_USE (strptime, "strptime is unportable - "
 417                  "use gnulib module strptime for portability");
 418 #  endif
 419 # endif
 420
 421 /* Convert *TP to a date and time string.  See
 422    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/ctime.html>.  */
 423 # if @GNULIB_CTIME@
 424 #  if @REPLACE_CTIME@
 425 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 426 #    define ctime rpl_ctime
 427 #   endif
 428 #   ifndef __cplusplus
 429 _GL_ATTRIBUTE_DEPRECATED
 430 #   endif
 431 _GL_FUNCDECL_RPL (ctime, char *, (time_t const *__tp)
 432                                  _GL_ARG_NONNULL ((1)));
 433 _GL_CXXALIAS_RPL (ctime, char *, (time_t const *__tp));
 434 #  else
 435 _GL_CXXALIAS_SYS (ctime, char *, (time_t const *__tp));
 436 #  endif
 437 #  if __GLIBC__ >= 2
 438 _GL_CXXALIASWARN (ctime);
 439 #  endif
 440 # elif defined GNULIB_POSIXCHECK
 441 /* No need to warn about portability, as a more serious warning is below.  */
 442 # endif
 443
 444 /* Convert *TP to a date and time string.  See
 445    <https://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.html>.  */
 446 # if @GNULIB_STRFTIME@
 447 #  if @REPLACE_STRFTIME@
 448 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 449 #    define strftime rpl_strftime
 450 #   endif
 451 _GL_FUNCDECL_RPL (strftime, size_t,
 452                   (char *restrict __buf, size_t __bufsize,
 453                    const char *restrict __fmt, const struct tm *restrict __tp)
 454                   _GL_ARG_NONNULL ((1, 3, 4)));
 455 _GL_CXXALIAS_RPL (strftime, size_t,
 456                   (char *restrict __buf, size_t __bufsize,
 457                    const char *restrict __fmt, const struct tm *restrict __tp));
 458 #  else
 459 _GL_CXXALIAS_SYS (strftime, size_t,
 460                   (char *restrict __buf, size_t __bufsize,
 461                    const char *restrict __fmt, const struct tm *restrict __tp));
 462 #  endif
 463 #  if __GLIBC__ >= 2
 464 _GL_CXXALIASWARN (strftime);
 465 #  endif
 466 # elif defined GNULIB_POSIXCHECK
 467 #  undef strftime
 468 #  if HAVE_RAW_DECL_STRFTIME
 469 _GL_WARN_ON_USE (strftime, "strftime has portability problems - "
 470                  "use gnulib module strftime-fixes for portability");
 471 #  endif
 472 # endif
 473
 474 # if defined _GNU_SOURCE && @GNULIB_TIME_RZ@ && ! @HAVE_TIMEZONE_T@
 475 /* Functions that use a first-class time zone data type, instead of
 476    relying on an implicit global time zone.
 477    Inspired by NetBSD.  */
 478
 479 /* Represents a time zone.
 480    (timezone_t) NULL stands for UTC.  */
 481 typedef struct tm_zone *timezone_t;
 482
 483 /* tzalloc (name)
 484    Returns a time zone object for the given time zone NAME.  This object
 485    represents the time zone that other functions would use it the TZ
 486    environment variable was set to NAME.
 487    If NAME is NULL, the result represents the time zone that other functions
 488    would use it the TZ environment variable was unset.
 489    May return NULL if NAME is invalid (this is platform dependent) or
 490    upon memory allocation failure.  */
 491 _GL_FUNCDECL_SYS (tzalloc, timezone_t, (char const *__name));
 492 _GL_CXXALIAS_SYS (tzalloc, timezone_t, (char const *__name));
 493
 494 /* tzfree (tz)
 495    Frees a time zone object.
 496    The argument must have been returned by tzalloc().  */
 497 _GL_FUNCDECL_SYS (tzfree, void, (timezone_t __tz));
 498 _GL_CXXALIAS_SYS (tzfree, void, (timezone_t __tz));
 499
 500 /* localtime_rz (tz, &t, &result)
 501    Converts an absolute time T to a broken-down time RESULT, assuming the
 502    time zone TZ.
 503    This function is like 'localtime_r', but relies on the argument TZ instead
 504    of an implicit global time zone.  */
 505 _GL_FUNCDECL_SYS (localtime_rz, struct tm *,
 506                   (timezone_t __tz, time_t const *restrict __timer,
 507                    struct tm *restrict __result) _GL_ARG_NONNULL ((2, 3)));
 508 _GL_CXXALIAS_SYS (localtime_rz, struct tm *,
 509                   (timezone_t __tz, time_t const *restrict __timer,
 510                    struct tm *restrict __result));
 511
 512 /* mktime_z (tz, &tm)
 513    Normalizes the broken-down time TM and converts it to an absolute time,
 514    assuming the time zone TZ.  Returns the absolute time.
 515    This function is like 'mktime', but relies on the argument TZ instead
 516    of an implicit global time zone.  */
 517 _GL_FUNCDECL_SYS (mktime_z, time_t,
 518                   (timezone_t __tz, struct tm *restrict __tm)
 519                   _GL_ARG_NONNULL ((2)));
 520 _GL_CXXALIAS_SYS (mktime_z, time_t,
 521                   (timezone_t __tz, struct tm *restrict __tm));
 522
 523 /* Time zone abbreviation strings (returned by 'localtime_rz' or 'mktime_z'
 524    in the 'tm_zone' member of 'struct tm') are valid as long as
 525      - the 'struct tm' argument is not destroyed or overwritten,
 526    and
 527      - the 'timezone_t' argument is not freed through tzfree().  */
 528
 529 # endif
 530
 531 /* Convert TM to a time_t value, assuming UTC.  */
 532 # if @GNULIB_TIMEGM@
 533 #  if @REPLACE_TIMEGM@
 534 #   if !(defined __cplusplus && defined GNULIB_NAMESPACE)
 535 #    undef timegm
 536 #    define timegm rpl_timegm
 537 #   endif
 538 _GL_FUNCDECL_RPL (timegm, time_t, (struct tm *__tm) _GL_ARG_NONNULL ((1)));
 539 _GL_CXXALIAS_RPL (timegm, time_t, (struct tm *__tm));
 540 #  else
 541 #   if ! @HAVE_TIMEGM@
 542 _GL_FUNCDECL_SYS (timegm, time_t, (struct tm *__tm) _GL_ARG_NONNULL ((1)));
 543 #   endif
 544 _GL_CXXALIAS_SYS (timegm, time_t, (struct tm *__tm));
 545 #  endif
 546 #  if __GLIBC__ >= 2
 547 _GL_CXXALIASWARN (timegm);
 548 #  endif
 549 # elif defined GNULIB_POSIXCHECK
 550 #  undef timegm
 551 #  if HAVE_RAW_DECL_TIMEGM
 552 _GL_WARN_ON_USE (timegm, "timegm is unportable - "
 553                  "use gnulib module timegm for portability");
 554 #  endif
 555 # endif
 556
 557 /* Encourage applications to avoid unsafe functions that can overrun
 558    buffers when given outlandish struct tm values.  Portable
 559    applications should use strftime (or even sprintf) instead.  */
 560 # if defined GNULIB_POSIXCHECK
 561 #  undef asctime
 562 #  if HAVE_RAW_DECL_ASCTIME
 563 _GL_WARN_ON_USE (asctime, "asctime can overrun buffers in some cases - "
 564                  "better use strftime (or even sprintf) instead");
 565 #  endif
 566 # endif
 567 # if defined GNULIB_POSIXCHECK
 568 #  undef asctime_r
 569 #  if HAVE_RAW_DECL_ASCTIME_R
 570 _GL_WARN_ON_USE (asctime_r, "asctime_r can overrun buffers in some cases - "
 571                  "better use strftime (or even sprintf) instead");
 572 #  endif
 573 # endif
 574 # if defined GNULIB_POSIXCHECK
 575 #  undef ctime
 576 #  if HAVE_RAW_DECL_CTIME
 577 _GL_WARN_ON_USE (ctime, "ctime can overrun buffers in some cases - "
 578                  "better use strftime (or even sprintf) instead");
 579 #  endif
 580 # endif
 581 # if defined GNULIB_POSIXCHECK
 582 #  undef ctime_r
 583 #  if HAVE_RAW_DECL_CTIME_R
 584 _GL_WARN_ON_USE (ctime_r, "ctime_r can overrun buffers in some cases - "
 585                  "better use strftime (or even sprintf) instead");
 586 #  endif
 587 # endif
 588
 589 #endif