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