newlib/libc/time/time.tex

   1 @node Timefns
   2 @chapter Time Functions (@file{time.h})
   3
   4 This chapter groups functions used either for reporting on time
   5 (elapsed, current, or compute time) or to perform calculations based
   6 on time.
   7
   8 The header file @file{time.h} defines three types.  @code{clock_t} and
   9 @code{time_t} are both used for representations of time particularly
  10 suitable for arithmetic.  (In this implementation, quantities of type
  11 @code{clock_t} have the highest resolution possible on your machine,
  12 and quantities of type @code{time_t} resolve to seconds.)  @code{size_t}
  13 is also defined if necessary for quantities representing sizes.
  14
  15 @file{time.h} also defines the structure @code{tm} for the traditional
  16 representation of Gregorian calendar time as a series of numbers, with
  17 the following fields:
  18
  19 @table @code
  20 @item tm_sec
  21 Seconds, between 0 and 60 inclusive (60 allows for leap seconds).
  22
  23 @item tm_min
  24 Minutes, between 0 and 59 inclusive.
  25
  26 @item tm_hour
  27 Hours, between 0 and 23 inclusive.
  28
  29 @item tm_mday
  30 Day of the month, between 1 and 31 inclusive.
  31
  32 @item tm_mon
  33 Month, between 0 (January) and 11 (December).
  34
  35 @item tm_year
  36 Year (since 1900), can be negative for earlier years.
  37
  38 @item tm_wday
  39 Day of week, between 0 (Sunday) and 6 (Saturday).
  40
  41 @item tm_yday
  42 Number of days elapsed since last January 1, between 0 and 365 inclusive.
  43
  44 @item tm_isdst
  45 Daylight Savings Time flag: positive means DST in effect, zero means DST
  46 not in effect, negative means no information about DST is available.
  47 Although for mktime(), negative means that it should decide if DST is in
  48 effect or not.
  49 @end table
  50
  51 @menu
  52 * Function asctime::     Format time as string
  53 * Function clock::       Cumulative processor time
  54 * Function ctime::       Convert time to local and format as string
  55 * Function difftime::    Subtract two times
  56 * Function gmtime::      Convert time to UTC (GMT) traditional representation
  57 * Function localtime::   Convert time to local representation
  58 * Function mktime::      Convert time to arithmetic representation
  59 * Function strftime::    Convert date and time to a user-formatted string
  60 * Function time::        Get current calendar time (as single number)
  61 * Function __tz_lock::   Lock time zone global variables
  62 * Function tzset::       Set timezone info
  63 @end menu
  64
  65 @page
  66 @include time/asctime.def
  67
  68 @page
  69 @include time/clock.def
  70
  71 @page
  72 @include time/ctime.def
  73
  74 @page
  75 @include time/difftime.def
  76
  77 @page
  78 @include time/gmtime.def
  79
  80 @page
  81 @include time/lcltime.def
  82
  83 @page
  84 @include time/mktime.def
  85
  86 @page
  87 @include time/strftime.def
  88
  89 @page
  90 @include time/time.def
  91
  92 @page
  93 @include time/tzlock.def
  94
  95 @page
  96 @include time/tzset.def