


Synopsys:
     #include <time.h>
     char *asctime(const struct tm *CLOCK);
     char *asctime_r(const struct tm *CLOCK, char *BUF);
   
Description:
Format the time value at CLOCK into a string of the form
      Wed Jun 15 11:38:07 1988\n\0
   The string is generated in a static buffer; each call to 'asctime'/'asctime_r'
overwrites the string generated by previous calls.

Returns:
A pointer to the string containing a formatted timestamp.

Portability:
ANSI C requires asctime.

   asctime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     clock_t clock(void);
   
Description:
'clock' calculates the best available approximation of the cumulative amount
of time used by your program since it started.  To convert the result into
seconds, divide by the macro 'CLOCKS_PER_SEC'.

Returns:
The amount of processor time used so far by your program, in units
defined by the machine-dependent macro CLOCKS_PER_SEC.  If no
measurement is available, the result is (clock_t)-1.

Portability:
ANSI C requires clock and CLOCKS_PER_SEC.

   Supporting OS subroutine required: times.

 





Synopsys:
     #include <time.h>
     char *ctime(const time_t *CLOCK);
     char *ctime_r(const time_t *CLOCK, char *BUF);
   
Description:
'ctime'/'ctime_r' converts the time value at CLOCK to local time (like localtime)
and format it into a string of the form
      Wed Jun 15 11:38:07 1988\n\0
   (like asctime).

Returns:
A pointer to the string containing a formatted timestamp.

Portability:
ANSI C requires ctime.

   ctime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     double difftime(time_t TIM1, time_t TIM2);
   
Description:
'difftime' subtracts the two times in the arguments: TIM1 - TIM2.

Returns:
The difference (in seconds) between TIM2 and TIM1, as a double.

Portability:
ANSI C requires difftime, and defines its result to be in seconds in
all implementations.

   difftime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     struct tm *gmtime(const time_t *CLOCK);
     struct tm *gmtime_r(const time_t *CLOCK, struct tm *RES);
   
Description:
'gmtime'/'gmtime_r' assumes the time at CLOCK represents a local time.  gmtime
converts it to UTC (Universal Coordinated Time, also known in some
countries as GMT, Greenwich Mean time), then converts the
representation from the arithmetic representation to the traditional
representation defined by struct tm.

gmtime constructs the traditional time representation in static
storage; each call to gmtime or localtime will overwrite the
information generated by previous calls to either function.

Returns:
A pointer to the traditional time representation (struct tm).

Portability:
ANSI C requires gmtime.

   gmtime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     struct tm *localtime(time_t *CLOCK);
     struct tm *localtime_r(time_t *CLOCK, struct tm *RES);
   
Description:
'localtime'/'localtime_r' converts the time at CLOCK into local time, then
converts its representation from the arithmetic representation to the
traditional representation defined by struct tm.

localtime constructs the traditional time representation in static
storage; each call to gmtime or localtime will overwrite the
information generated by previous calls to either function.

mktime is the inverse of localtime.

Returns:
A pointer to the traditional time representation (struct tm).

Portability:
ANSI C requires localtime.

   localtime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     time_t mktime(struct tm *TIMP);
   
Description:
'mktime' assumes the time at TIMP is a local time, and converts its
representation from the traditional representation defined by struct
tm into a representation suitable for arithmetic.

localtime is the inverse of mktime.

Returns:
If the contents of the structure at TIMP do not form a valid calendar
time representation, the result is -1.  Otherwise, the result is the
time, converted to a time_t value.

Portability:
ANSI C requires mktime.

   mktime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     size_t strftime(char *S, size_t MAXSIZE,
         const char *FORMAT, const struct tm *TIMP);
   
Description:
'strftime' converts a struct tm representation of the time (at TIMP)
into a null-terminated string, starting at S and occupying no more than
MAXSIZE characters.

   You control the format of the output using the string at FORMAT.
*FORMAT can contain two kinds of specifications: text to be copied
literally into the formatted string, and time conversion
specifications.  Time conversion specifications are two- and
three-character sequences beginning with % (use %% to include a
percent sign in the output).  Each defined conversion specification
selects only the specified field(s) of calendar time data from *TIMP,
and converts it to a string in one of the following ways:

%a
     A three-letter abbreviation for the day of the week. [tm_wday]

%A
     The full name for the day of the week, one of Sunday,
     Monday, Tuesday, Wednesday, Thursday, Friday,
     or Saturday. [tm_wday]

%b
     A three-letter abbreviation for the month name. [tm_mon]

%B
     The full name of the month, one of January, February,
     March, April, May, June, July, August,
     September, October, November, December. [tm_mon]

%c
     A string representing the complete date and time, in the form
     "%a %b %e %H:%M:%S %Y" (example "Mon Apr 01 13:13:13 1992").
     [tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday]

%C
     The century, that is, the year divided by 100 then truncated.  For
     4-digit years, the result is zero-padded and exactly two
     characters; but for other years, there may a negative sign or more
     digits.  In this way, %C%y is equivalent to %Y. [tm_year]

%d
     The day of the month, formatted with two digits (from 01 to
     31). [tm_mday]

%D
     A string representing the date, in the form "%m/%d/%y".
     [tm_mday, tm_mon, tm_year]

%e
     The day of the month, formatted with leading space if single digit
     (from 1 to 31). [tm_mday]

%Ex
     In some locales, the E modifier selects alternative
     representations of certain modifiers x.  But in the "C" locale
     supported by newlib, it is ignored, and treated as %x.

%F
     A string representing the ISO 8601:2000 date format, in the form
     "%Y-%m-%d". [tm_mday, tm_mon, tm_year]

%g
     The last two digits of the week-based year, see specifier %G (from
     00 to 99). [tm_year, tm_wday, tm_yday]

%G
     The week-based year. In the ISO 8601:2000 calendar, week 1 of the
     year includes January 4th, and begin on Mondays. Therefore, if
     January 1st, 2nd, or 3rd falls on a Sunday, that day and earlier
     belong to the last week of the previous year; and if December
     29th, 30th, or 31st falls on Monday, that day and later belong to
     week 1 of the next year.  For consistency with %Y, it always has
     at least four characters.  Example: "%G" for Saturday 2nd January
     1999 gives "1998", and for Tuesday 30th December 1997 gives
     "1998". [tm_year, tm_wday, tm_yday]

%h
     A three-letter abbreviation for the month name (synonym for "%b").
     [tm_mon]

%H
     The hour (on a 24-hour clock), formatted with two digits (from
     00 to 23). [tm_hour]

%I
     The hour (on a 12-hour clock), formatted with two digits (from
     01 to 12). [tm_hour]

%j
     The count of days in the year, formatted with three digits (from
     001 to 366). [tm_yday]

%k
     The hour (on a 24-hour clock), formatted with leading space if
     single digit (from 0 to 23). Non-POSIX extension. [tm_hour]

%l
     The hour (on a 12-hour clock), formatted with leading space if
     single digit (from 1 to 12). Non-POSIX extension. [tm_hour]

%m
     The month number, formatted with two digits (from 01 to
     12).  [tm_mon]

%M
     The minute, formatted with two digits (from 00 to 59).
     [tm_min]

%n
     A newline character (\n).

%Ox
     In some locales, the O modifier selects alternative digit
     characters for certain modifiers x.  But in the "C" locale
     supported by newlib, it is ignored, and treated as %x.

%p
     Either AM or PM as appropriate. [tm_hour]

%r
     The 12-hour time, to the second.  Equivalent to "%I:%M:%S %p".
     [tm_sec, tm_min, tm_hour]

%R
     The 24-hour time, to the minute.  Equivalent to "%H:%M". [tm_min,
     tm_hour]

%S
     The second, formatted with two digits (from 00 to 60).  The
     value 60 accounts for the occasional leap second. [tm_sec]

%t
     A tab character (\t).

%T
     The 24-hour time, to the second.  Equivalent to "%H:%M:%S".
     [tm_sec, tm_min, tm_hour]

%u
     The weekday as a number, 1-based from Monday (from 1 to
     7). [tm_wday]

%U
     The week number, where weeks start on Sunday, week 1 contains the
     first Sunday in a year, and earlier days are in week 0.  Formatted
     with two digits (from 00 to 53).  See also %W. [tm_wday,
     tm_yday]

%V
     The week number, where weeks start on Monday, week 1 contains
     January 4th, and earlier days are in the previous year.  Formatted
     with two digits (from 01 to 53).  See also %G. [tm_year,
     tm_wday, tm_yday]

%w
     The weekday as a number, 0-based from Sunday (from 0 to 6).
     [tm_wday]

%W
     The week number, where weeks start on Monday, week 1 contains the
     first Monday in a year, and earlier days are in week 0.  Formatted
     with two digits (from 00 to 53). [tm_wday, tm_yday]

%x
     A string representing the complete date, equivalent to "%m/%d/%y".
     [tm_mon, tm_mday, tm_year]

%X
     A string representing the full time of day (hours, minutes, and
     seconds), equivalent to "%H:%M:%S". [tm_sec, tm_min, tm_hour]

%y
     The last two digits of the year (from 00 to 99). [tm_year]

%Y
     The full year, equivalent to %C%y.  It will always have at least
     four characters, but may have more.  The year is accurate even
     when tm_year added to the offset of 1900 overflows an int.
     [tm_year]

%z
     The offset from UTC.  The format consists of a sign (negative is
     west of Greewich), two characters for hour, then two characters
     for minutes (-hhmm or +hhmm).  If tm_isdst is negative, the offset
     is unknown and no output is generated; if it is zero, the offset
     is the standard offset for the current time zone; and if it is
     positive, the offset is the daylight savings offset for the
     current timezone. The offset is determined from the TZ environment
     variable, as if by calling tzset(). [tm_isdst]

%Z
     The time zone name.  If tm_isdst is negative, no output is
     generated.  Otherwise, the time zone name is based on the TZ
     environment variable, as if by calling tzset(). [tm_isdst]

%%
     A single character, %.

Returns:
When the formatted time takes up no more than MAXSIZE characters, the
result is the length of the formatted string.  Otherwise, if the
formatting operation was abandoned due to lack of room, the result is
0, and the string starting at S corresponds to just those parts of
*FORMAT that could be completely filled in within the MAXSIZE limit.

Portability:
ANSI C requires strftime, but does not specify the contents of *S
when the formatted string would require more than MAXSIZE characters.
Unrecognized specifiers and fields of timp that are out of range
cause undefined results.  Since some formats expand to 0 bytes, it is
wise to set *S to a nonzero value beforehand to distinguish between
failure and an empty string.  This implementation does not support s
being NULL, nor overlapping s and format.

   strftime requires no supporting OS subroutines.

 





Synopsys:
     #include <time.h>
     time_t time(time_t *T);
   
Description:
'time' looks up the best available representation of the current time
and returns it, encoded as a 'time_t'.  It stores the same value at T
unless the argument is NULL.

Returns:
A -1 result means the current time is not available; otherwise the
result represents the current time.

Portability:
ANSI C requires time.

   Supporting OS subroutine required: Some implementations require
gettimeofday.

 





Synopsys:
     #include "local.h"
     void __tz_lock (void);
     void __tz_unlock (void);
   
Description:
The tzset facility functions call these functions when they need to
ensure the values of global variables.  The version of these routines
supplied in the library use the lock API defined in sys/lock.h.  If
multiple threads of execution can call the time functions and give up
scheduling in the middle, then you you need to define your own versions
of these functions in order to safely lock the time zone variables
during a call.  If you do not, the results of localtime, mktime,
ctime, and strftime are undefined.

   The lock '__tz_lock' may not be called recursively; that is, a call
__tz_lock will always lock all subsequent __tz_lock calls until the
corresponding '__tz_unlock' call on the same thread is made.

 





Synopsys:
     #include <time.h>
     void tzset(void);
     void _tzset_r (struct _reent *);
   
Description:
'tzset' examines the TZ environment variable and sets up the three
external variables: '_timezone', '_daylight', and 'tzname'.  The value
of _timezone shall be the offset from the current time zone to GMT.
The value of _daylight shall be 0 if there is no daylight savings
time for the current time zone, otherwise it will be non-zero.  The
tzname array has two entries: the first is the name of the standard
time zone, the second is the name of the daylight-savings time zone.

   The TZ environment variable is expected to be in the following POSIX
format:

   stdoffset1[dst[offset2][,start[/time1],end[/time2]]]

   where: std is the name of the standard time-zone (minimum 3 chars)
offset1 is the value to add to local time to arrive at Universal time
it has the form:  hh[:mm[:ss]] dst is the name of the alternate
(daylight-savings) time-zone (min 3 chars) offset2 is the value to add
to local time to arrive at Universal time it has the same format as the
std offset start is the day that the alternate time-zone starts time1
is the optional time that the alternate time-zone starts (this is in
local time and defaults to 02:00:00 if not specified) end is the day
that the alternate time-zone ends time2 is the time that the alternate
time-zone ends (it is in local time and defaults to 02:00:00 if not
specified)

   Note that there is no white-space padding between fields.  Also note
that if TZ is null, the default is Universal GMT which has no
daylight-savings time.  If TZ is empty, the default EST5EDT is used.

   The function '_tzset_r' is identical to tzset only it is reentrant
and is used for applications that use multiple threads.

Returns:
There is no return value.

Portability:
tzset is part of the POSIX standard.

   Supporting OS subroutine required: None

