time/time.h

   1 /* Copyright (C) 1991-1999, 2000 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 Library General Public License as
   6    published by the Free Software Foundation; either version 2 of the
   7    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    Library General Public License for more details.
  13
  14    You should have received a copy of the GNU Library General Public
  15    License along with the GNU C Library; see the file COPYING.LIB.  If not,
  16    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17    Boston, MA 02111-1307, USA.  */
  18
  19 /*
  20  *      ISO C Standard: 4.12 DATE and TIME      <time.h>
  21  */
  22
  23 #ifndef _TIME_H
  24
  25 #if (! defined __need_time_t && !defined __need_clock_t && \
  26      ! defined __need_timespec)
  27 # define _TIME_H        1
  28 # include <features.h>
  29
  30 __BEGIN_DECLS
  31
  32 #endif
  33
  34 #ifdef  _TIME_H
  35 /* Get size_t and NULL from <stddef.h>.  */
  36 # define __need_size_t
  37 # define __need_NULL
  38 # include <stddef.h>
  39
  40 /* This defines CLOCKS_PER_SEC, which is the number of processor clock
  41    ticks per second.  */
  42 # include <bits/time.h>
  43
  44 /* This is the obsolete POSIX.1-1988 name for the same constant.  */
  45 # ifdef __USE_POSIX
  46 #  ifndef CLK_TCK
  47 #   define CLK_TCK      CLOCKS_PER_SEC
  48 #  endif
  49 # endif
  50
  51 #endif /* <time.h> included.  */
  52
  53
  54 #if !defined __clock_t_defined && (defined _TIME_H || defined __need_clock_t)
  55 # define __clock_t_defined      1
  56
  57 # include <bits/types.h>
  58
  59 /* Returned by `clock'.  */
  60 typedef __clock_t clock_t;
  61
  62 #endif /* clock_t not defined and <time.h> or need clock_t.  */
  63 #undef  __need_clock_t
  64
  65 #if !defined __time_t_defined && (defined _TIME_H || defined __need_time_t)
  66 # define __time_t_defined       1
  67
  68 # include <bits/types.h>
  69
  70 /* Returned by `time'.  */
  71 typedef __time_t time_t;
  72
  73 #endif /* time_t not defined and <time.h> or need time_t.  */
  74 #undef  __need_time_t
  75
  76
  77 #if !defined __timespec_defined && \
  78     ((defined _TIME_H && defined __USE_POSIX199309) || defined __need_timespec)
  79 # define __timespec_defined     1
  80
  81 /* POSIX.1b structure for a time value.  This is like a `struct timeval' but
  82    has nanoseconds instead of microseconds.  */
  83 struct timespec
  84   {
  85     long int tv_sec;            /* Seconds.  */
  86     long int tv_nsec;           /* Nanoseconds.  */
  87   };
  88
  89 #endif /* timespec not defined and <time.h> or need timespec.  */
  90 #undef  __need_timespec
  91
  92
  93 #ifdef  _TIME_H
  94 /* Used by other time functions.  */
  95 struct tm
  96 {
  97   int tm_sec;                   /* Seconds.     [0-60] (1 leap second) */
  98   int tm_min;                   /* Minutes.     [0-59] */
  99   int tm_hour;                  /* Hours.       [0-23] */
 100   int tm_mday;                  /* Day.         [1-31] */
 101   int tm_mon;                   /* Month.       [0-11] */
 102   int tm_year;                  /* Year - 1900.  */
 103   int tm_wday;                  /* Day of week. [0-6] */
 104   int tm_yday;                  /* Days in year.[0-365] */
 105   int tm_isdst;                 /* DST.         [-1/0/1]*/
 106
 107 # ifdef __USE_BSD
 108   long int tm_gmtoff;           /* Seconds east of UTC.  */
 109   __const char *tm_zone;        /* Timezone abbreviation.  */
 110 # else
 111   long int __tm_gmtoff;         /* Seconds east of UTC.  */
 112   __const char *__tm_zone;      /* Timezone abbreviation.  */
 113 # endif
 114 };
 115
 116
 117 #ifdef __USE_POSIX199309
 118 /* Clock ID used in clock and timer functions.  */
 119 typedef __clockid_t clockid_t;
 120
 121 /* Timer ID returned by `timer_create'.  */
 122 typedef __timer_t timer_t;
 123
 124 /* POSIX.1b structure for timer start values and intervals.  */
 125 struct itimerspec
 126   {
 127     struct timespec it_interval;
 128     struct timespec it_value;
 129   };
 130
 131 /* We can use a simple forward declaration.  */
 132 struct sigevent;
 133
 134 #endif  /* POSIX.1b */
 135
 136 #ifdef __USE_XOPEN2K
 137 # ifndef __pid_t_defined
 138 typedef __pid_t pid_t;
 139 #  define __pid_t_defined
 140 # endif
 141 #endif
 142
 143
 144 /* Time used by the program so far (user time + system time).
 145    The result / CLOCKS_PER_SECOND is program time in seconds.  */
 146 extern clock_t clock (void) __THROW;
 147
 148 /* Return the current time and put it in *TIMER if TIMER is not NULL.  */
 149 extern time_t time (time_t *__timer) __THROW;
 150
 151 /* Return the difference between TIME1 and TIME0.  */
 152 extern double difftime (time_t __time1, time_t __time0)
 153      __THROW __attribute__ ((__const__));
 154
 155 /* Return the `time_t' representation of TP and normalize TP.  */
 156 extern time_t mktime (struct tm *__tp) __THROW;
 157
 158
 159 /* Format TP into S according to FORMAT.
 160    Write no more than MAXSIZE characters and return the number
 161    of characters written, or 0 if it would exceed MAXSIZE.  */
 162 extern size_t strftime (char *__restrict __s, size_t __maxsize,
 163                         __const char *__restrict __format,
 164                         __const struct tm *__restrict __tp) __THROW;
 165
 166 # ifdef __USE_XOPEN
 167 /* Parse S according to FORMAT and store binary time information in TP.
 168    The return value is a pointer to the first unparsed character in S.  */
 169 extern char *strptime (__const char *__s, __const char *__fmt, struct tm *__tp)
 170      __THROW;
 171 # endif
 172
 173
 174 /* Return the `struct tm' representation of *TIMER
 175    in Universal Coordinated Time (aka Greenwich Mean Time).  */
 176 extern struct tm *gmtime (__const time_t *__timer) __THROW;
 177
 178 /* Return the `struct tm' representation
 179    of *TIMER in the local timezone.  */
 180 extern struct tm *localtime (__const time_t *__timer) __THROW;
 181
 182 # if defined __USE_POSIX || defined __USE_MISC
 183 /* Return the `struct tm' representation of *TIMER in UTC,
 184    using *TP to store the result.  */
 185 extern struct tm *gmtime_r (__const time_t *__restrict __timer,
 186                             struct tm *__restrict __tp) __THROW;
 187
 188 /* Return the `struct tm' representation of *TIMER in local time,
 189    using *TP to store the result.  */
 190 extern struct tm *localtime_r (__const time_t *__restrict __timer,
 191                                struct tm *__restrict __tp) __THROW;
 192 # endif /* POSIX or misc */
 193
 194 /* Return a string of the form "Day Mon dd hh:mm:ss yyyy\n"
 195    that is the representation of TP in this format.  */
 196 extern char *asctime (__const struct tm *__tp) __THROW;
 197
 198 /* Equivalent to `asctime (localtime (timer))'.  */
 199 extern char *ctime (__const time_t *__timer) __THROW;
 200
 201 # if defined __USE_POSIX || defined __USE_MISC
 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.  */
 206 extern 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 extern char *ctime_r (__const time_t *__restrict __timer,
 211                       char *__restrict __buf) __THROW;
 212 # endif /* POSIX or misc */
 213
 214
 215 /* Defined in localtime.c.  */
 216 extern char *__tzname[2];       /* Current timezone names.  */
 217 extern int __daylight;          /* If daylight-saving time is ever in use.  */
 218 extern long int __timezone;     /* Seconds west of UTC.  */
 219
 220
 221 # ifdef __USE_POSIX
 222 /* Same as above.  */
 223 extern char *tzname[2];
 224
 225 /* Set time conversion information from the TZ environment variable.
 226    If TZ is not defined, a locale-dependent default is used.  */
 227 extern void tzset (void) __THROW;
 228 # endif
 229
 230 # if defined __USE_SVID || defined __USE_XOPEN
 231 extern int daylight;
 232 extern long int timezone;
 233 # endif
 234
 235 # ifdef __USE_SVID
 236 /* Set the system time to *WHEN.
 237    This call is restricted to the superuser.  */
 238 extern int stime (__const time_t *__when) __THROW;
 239 # endif
 240
 241
 242 /* Nonzero if YEAR is a leap year (every 4 years,
 243    except every 100th isn't, and every 400th is).  */
 244 # define __isleap(year) \
 245   ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0))
 246
 247
 248 # ifdef __USE_MISC
 249 /* Miscellaneous functions many Unices inherited from the public domain
 250    localtime package.  These are included only for compatibility.  */
 251
 252 /* Like `mktime', but for TP represents Universal Time, not local time.  */
 253 extern time_t timegm (struct tm *__tp) __THROW;
 254
 255 /* Another name for `mktime'.  */
 256 extern time_t timelocal (struct tm *__tp) __THROW;
 257
 258 /* Return the number of days in YEAR.  */
 259 extern int dysize (int __year) __THROW;
 260 # endif
 261
 262
 263 # ifdef __USE_POSIX199309
 264 /* Pause execution for a number of nanoseconds.  */
 265 extern int nanosleep (__const struct timespec *__requested_time,
 266                       struct timespec *__remaining) __THROW;
 267
 268
 269 /* Get resolution of clock CLOCK_ID.  */
 270 extern int clock_getres (clockid_t __clock_id, struct timespec *__res) __THROW;
 271
 272 /* Get current value of clock CLOCK_ID and store it in TP.  */
 273 extern int clock_gettime (clockid_t __clock_id, struct timespec *__tp) __THROW;
 274
 275 /* Set clock CLOCK_ID to value TP.  */
 276 extern int clock_settime (clockid_t __clock_id, __const struct timespec *__tp)
 277      __THROW;
 278
 279 #  ifdef __USE_XOPEN2K
 280 /* Return clock ID for CPU-time clock.  */
 281 extern int clock_getcpuclockid (pid_t __pid, clockid_t *__clock_id) __THROW;
 282 #  endif
 283
 284
 285 /* Create new per-process timer using CLOCK_ID.  */
 286 extern int timer_create (clockid_t __clock_id, struct sigevent *__evp,
 287                          timer_t *__timerid) __THROW;
 288
 289 /* Delete timer TIMERID.  */
 290 extern int timer_delete (timer_t __timerid) __THROW;
 291
 292 /* Set timer TIMERID to VALUE, returning old value in OVLAUE.  */
 293 extern int timer_settime (timer_t __timerid, int __flags,
 294                           __const struct itimerspec *__value,
 295                           struct itimerspec *__ovalue) __THROW;
 296
 297 /* Get current value of timer TIMERID and store it in VLAUE.  */
 298 extern int timer_gettime (timer_t __timerid, struct itimerspec *__value)
 299      __THROW;
 300
 301 /* Get expiration overrun for timer TIMERID.  */
 302 extern int timer_getoverrun (timer_t __timerid) __THROW;
 303 # endif
 304
 305
 306 # ifdef __USE_XOPEN_EXTENDED
 307 /* Set to one of the following values to indicate an error.
 308      1  the DATEMSK environment variable is null or undefined,
 309      2  the template file cannot be opened for reading,
 310      3  failed to get file status information,
 311      4  the template file is not a regular file,
 312      5  an error is encountered while reading the template file,
 313      6  memory allication failed (not enough memory available),
 314      7  there is no line in the template that matches the input,
 315      8  invalid input specification Example: February 31 or a time is
 316         specified that can not be represented in a time_t (representing
 317         the time in seconds since 00:00:00 UTC, January 1, 1970) */
 318 extern int getdate_err;
 319
 320 /* Parse the given string as a date specification and return a value
 321    representing the value.  The templates from the file identified by
 322    the environment variable DATEMSK are used.  In case of an error
 323    `getdate_err' is set.  */
 324 extern struct tm *getdate (__const char *__string) __THROW;
 325 # endif
 326
 327 # ifdef __USE_GNU
 328 /* Since `getdate' is not reentrant because of the use of `getdate_err'
 329    and the static buffer to return the result in, we provide a thread-safe
 330    variant.  The functionality is the same.  The result is returned in
 331    the buffer pointed to by RESBUFP and in case of an error the return
 332    value is != 0 with the same values as given above for `getdate_err'.  */
 333 extern int getdate_r (__const char *__restrict __string,
 334                       struct tm *__restrict __resbufp) __THROW;
 335 # endif
 336
 337
 338 __END_DECLS
 339
 340 #endif /* <time.h> included.  */
 341
 342 #endif /* <time.h> not already included.  */