Implements some standard C time functions. More...

Collaboration diagram for Time handling Functions:

Data Structures
struct	_tm
	structure to store a date/time value. More...
Typedefs
typedef struct _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 ptm)
	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 ptm)
	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
int	_daylight
	Used to control daylight conversions.
long	_timezone
	Defines your local timezone.
long	_dstbias
	Difference between standard and daylight savings time in seconds.

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.

Typedef Documentation

typedef struct _tm tm

Type definition for struct _tm.

Definition at line 84 of file time.h.

long time_t

Serial date/time. Holds number of seconds after January 1st, 1970.

Definition at line 114 of file time.h.

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:: caltime/caltime.c, ftpd/ftpserv.c, httpd/httpserv.c, and tcps/tcps.c.

Definition at line 89 of file time.c.

References _mkgmtime(), free(), malloc(), NutGetSeconds(), NutRtcGetTime(), and _tm::tm_isdst.

Referenced by GetDosTimeStamp(), main(), MibRegisterSysVars(), NutFtpServerSession(), NutHttpSendHeaderTop(), and syslog_header().

Here is the call graph for this function:

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.

Definition at line 100 of file gmtime.c.

References _BASE_DOW, _DAY_SEC, _days, _FOUR_YEAR_SEC, _lpdays, _YEAR_SEC, _tm::tm_hour, _tm::tm_isdst, _tm::tm_mday, _tm::tm_min, _tm::tm_mon, _tm::tm_sec, _tm::tm_wday, _tm::tm_yday, and _tm::tm_year.

Referenced by gmtime(), and localtime_r().

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:: caltime/caltime.c, ftpd/ftpserv.c, and pppc/pppc.c.

Definition at line 195 of file gmtime.c.

References _tb, and gmtime_r().

Referenced by NutFtpTransferDirectoryOptions(), NutHttpSendHeaderTop(), NutSmtpSendMailHeader(), stime(), and syslog_header().

Here is the call graph for this function:

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.

Examples:: httpd/httpserv.c.

Definition at line 84 of file localtim.c.

References _DAY_SEC, _daylight, _dstbias, _isindst(), _timezone, gmtime_r(), LONG_MAX, NUTASSERT, _tm::tm_hour, _tm::tm_isdst, _tm::tm_mday, _tm::tm_min, _tm::tm_mon, _tm::tm_sec, _tm::tm_wday, _tm::tm_yday, and _tm::tm_year.

Referenced by localtime().

Here is the call graph for this function:

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:: caltime/caltime.c, and ftpd/ftpserv.c.

Definition at line 209 of file localtim.c.

References _tb, and localtime_r().

Referenced by GetDosTimeStamp(), main(), NutFtpServerSession(), and syslog_header().

Here is the call graph for this function:

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:: caltime/caltime.c, ftpd/ftpserv.c, and logtime/logtime.c.

Definition at line 119 of file time.c.

References gmtime(), NutGetSeconds(), and NutRtcSetTime().

Referenced by main(), and SNTP_resync().

Here is the call graph for this function:

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.

Examples:: caltime/caltime.c.

Definition at line 279 of file mktime.c.

Referenced by PhatDirEntryStatus(), and RfcTimeParse().

time_t _mkgmtime ( tm * timeptr )

Examples:: ftpd/ftpserv.c.

Definition at line 284 of file mktime.c.

Referenced by RfcTimeParse(), and time().

Variable Documentation

int _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.

Examples:: caltime/caltime.c.

Definition at line 65 of file tzset.c.

Referenced by _isindst(), localtime_r(), main(), and PhatDirEntryStatus().

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.

Examples:: caltime/caltime.c, ftpd/ftpserv.c, and logtime/logtime.c.

Definition at line 67 of file tzset.c.

Referenced by localtime_r(), and main().

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.

Examples:: caltime/caltime.c.

Definition at line 66 of file tzset.c.

Referenced by localtime_r().

Data Structures

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation