Time handling Functions
[C Runtime Library.]

Collaboration diagram for Time handling Functions:

---

Detailed Description

Implements some standard C time functions.

Use these functions to get the current time and convert, adjust, and store it as necessary. The current time is the system time.

Data Structures
struct	_tm
	structure to store a date/time value. More...
Typedefs
typedef _tm	tm
	Type definition for struct _tm.
typedef long	time_t
	Serial date/time. Holds number of seconds after January 1st, 1970.
Functions
time_t	time (time_t *timer)
	Get the system time.
int	gmtime_r (CONST time_t *timer, tm *theTime)
	Convert a time value to a structure.
tm *	gmtime (CONST time_t *timer)
	Convert a time value to a structure.
int	localtime_r (CONST time_t *timer, tm *theTime)
	Convert a time value and correct for the local time zone.
tm *	localtime (CONST time_t *timer)
	Convert a time value and correct for the local time zone.
int	stime (time_t *timer)
	Set the system time.
time_t	mktime (tm *timeptr)
	Convert the local time to a calendar value.
time_t	_mkgmtime (tm *timeptr)
Variables
u_char	_daylight
	Used to control daylight conversions.
long	_timezone
	Defines your local timezone.
long	_dstbias
	Difference between standard and daylight savings time in seconds.

---

Function Documentation

time_t time (  time_t *  timer  )

Get the system time. The time function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC), according to the system clock. The return value is stored in the location given by timer. This parameter may be NULL, in which case the return value is not stored. Parameters: timer  Pointer to the storage location for time. Returns: Return the time in elapsed seconds. There is no error return. Examples: ftpd/ftpserv.c.

int gmtime_r (  CONST time_t *  timer, tm *  ptm )

Convert a time value to a structure. Thread safe version of gmtime. See gmtime for more information. Parameters: timer  Pointer to stored time. The time is represented as seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). ptm  Pointer to structure tm where the converted time is stored. Returns: Returns nonzero value if any error occured.

tm * gmtime (  CONST time_t *  timer  )

Convert a time value to a structure. The gmtime function breaks down the timer value and stores it in a statically allocated structure of type tm, defined in time.h. The value of timer is usually obtained from a call to the time function. Parameters: timer  Pointer to stored time. The time is represented as seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). Returns: Returns a pointer to a structure of type tm. The fields of the returned structure hold the evaluated value of the timer argument in UTC rather than in local time. Note: This function is not thread safe, because it uses a static variable to store the calculated values. To be safe, you must surround the call to gmtime and the usage of the returned pointer with ::NutEnterCritical() and ::NutExitCritical()! Examples: ftpd/ftpserv.c.

int localtime_r (  CONST time_t *  timer, tm *  ptm )

Convert a time value and correct for the local time zone. Thread safe version of localtime. See localtime for more information. Parameters: timer  Pointer to stored time. ptm  Pointer to structure tm where the converted time is stored. Returns: Always return 0.

tm * localtime (  CONST time_t *  timer  )

Convert a time value and correct for the local time zone. The localtime function converts a time stored as a time_t value and stores the result in a structure of type tm. The long value timer represents the seconds elapsed since midnight (00:00:00), January 1, 1970, UTC. This value is usually obtained from the time function. gmtime, mktime, and localtime all use a single statically allocated tm structure for the conversion. Each call to one of these routines destroys the result of the previous call. localtime corrects for the local time zone if the user first sets the global variable _timezone. Parameters: timer  Pointer to stored time. Returns: Return a pointer to the structure result. If the value in timer represents a date before midnight, January 1, 1970, return NULL. Examples: ftpd/ftpserv.c.

int stime (  time_t *  timer  )

Set the system time. Parameters: timer  Pointer to the storage location for time. Returns: This function always returns 0. Examples: ftpd/ftpserv.c, and logtime/logtime.c.

time_t mktime (  tm *  timeptr  )

Convert the local time to a calendar value. The mktime function converts the supplied time structure (possibly incomplete) pointed to by timeptr into a fully defined structure with normalized values and then converts it to a time_t calendar time value. The converted time has the same encoding as the values returned by the time function. The original values of the tm_wday and tm_yday components of the timeptr structure are ignored, and the original values of the other components are not restricted to their normal ranges. After an adjustment to Greenwich Mean Time (GMT), mktime handles dates from midnight, January 1, 1970, to January 19, 3:14:07, 2038. This adjustment may cause mktime to return -1 (cast to time_t) even though the date you specify is within range. For example, if you are in Cairo, Egypt, which is two hours ahead of GMT, two hours will first be subtracted from the date you specify in timeptr; this may now put your date out of range. If successful, mktime sets the values of tm_wday and tm_yday as appropriate and sets the other components to represent the specified calendar time, but with their values forced to the normal ranges. The final value of tm_mday is not set until tm_mon and tm_year are determined. When specifying a tm structure time, set the tm_isdst field to: Zero (0) to indicate that standard time is in effect. A value greater than 0 to indicate that daylight savings time is in effect. tm_isdst is a required field. If not set, its value is undefined and the return value from mktime is unpredictable. If timeptr points to a tm structure returned by a previous call to gmtime or localtime, the tm_isdst field contains the correct value. Note: Note that gmtime and localtime use a single statically allocated buffer for the conversion. If you supply this buffer to mktime, the previous contents are destroyed. Parameters: timeptr  Pointer to time structure. Returns: mktime returns the specified calendar time encoded as a value of type time_t. If timeptr references a date before midnight, January 1, 1970, or if the calendar time cannot be represented, mktime returns –1 cast to type time_t. When using mktime and if timeptr references a date after 3:14:07 January 19, 2038, UTC, it will return –1 cast to type time_t.

---

Variable Documentation

u_char _daylight

Used to control daylight conversions. Assign a nonzero value to enable daylight conversions. If enabled the hour part of time values is adjusted if we are in daylight saving time. Zero value to disable conversion. Default is enabled.

long _timezone

Defines your local timezone. Difference in seconds between universal coordinated time and local time. This value is subtracted from the universal coordinated time to calculate your local time. Default value is 5 * 60 * 60 = 18000, which defines the time zone EST (GMT-5). Note: Before using the time functions, set _timezone to your local value.

long _dstbias

Difference between standard and daylight savings time in seconds. This value is used to calculate the daylight savings time by subtracting this value from the standard time. Unit is seconds. Usually daylight savings time is one hour in advance to standard time, thus the default value is -1 * 60 * 60 = -3600.

---