Time manipulation utilities [C library]

These functions convert between calendar date and UNIX representation of time. More...

Data Structures
struct	tm
	Broken down date and time structure. More...
Defines
#define	TIME_INVALID   ((time_t)-1)
	Indicates that a time is not valid.
Typedefs
typedef unsigned long	time_t
	Internal representation of time.
Functions
struct tm *	gmtime (time_t utc, struct tm *tm)
	Converts the unix time to broken-down representation.
struct tm *	localtime (time_t utc, struct tm *tm)
	Converts the unix time to the broken-down time structure.
time_t	mktime (const struct tm *tm)
	Converts a broken-down representation to unsigned UNIX time.

---

Detailed Description

These functions convert between calendar date and UNIX representation of time.

UNIX stores time as the number of seconds since 1970-01-01 00:00:00 GMT, known as the 'Epoch'. Most modern UNIX-ish systems store the time as a signed 64-bit quantity, allowing you to go back before the Big Bang and go forward to and beyond the end of the Solar System. The reference has changed from Greenwich Mean Time (GMT) to Universal Coordinated Time (UTC) and leap seconds were introduced, so things are getting a bit complicated.

This library, however, stores the number of seconds in a 32-bit unsigned integer. The unsigned nature means that you can only go back to the Epoch and your clock will roll over in 2106, less than a century in the future. In addition, the routines do not care about leap seconds (leap years are respected, of course). Despite those limitations, for practical timekeeping the format is sufficient; most embedded gizmos just keep track of the current time using a watch crystal. If you really need to go back more than 40 years or forward by more than a century or you need atomic precision timekeeping, alas, you will have to write your own specialised routines.

The routines in the library allow you to convert between the above mentioned format and the Gregorian calendar format. The structure that stores the calendar format (known as the broken-down time format) strongly mimics the same structure defined by the POSIX standard. However, instead of defining every field as an integer, the fields are only as wide as they have to be. This results in a significant space saving in the structure size.

Timezone management is left to you. The routines can take the time zone into account, in fact you must set the timezone field in the broken-down time structure, but that field is just an offset. It's you who has to maintain that offset according to your timezone and/or summer light saving time.

To use these functions you have to include time.h.

---

Typedef Documentation

time_t

Internal representation of time.

A 32-bit unsigned integer is used to store the number of seconds since the Epoch (1970-01-01 00:00:00 UTC). The value 0xffffffff is not allowed, it is reserved to signal errors. The 32-bit unsigned int will not roll over before 2106.

Returns:

nothing, it is a Doxygen 1.7.1 bug that you have to specify a return type for a typedef.

---

Function Documentation

struct tm* gmtime	(	time_t	utc,
		struct tm *	tm
	)			[read]

Converts the unix time to broken-down representation.

The function receives a UTC value and breaks it down to the individual fields of the tm structure. The function sets the structure's timezone field to 0, that is, to GMT. If the utc value is (time_t) -1, then the conversion will fail, all other values will succeed.

Parameters:

	utc	The unix time to convert
	tm	Pointer to the tm structure where the result will be stored

Returns:

The pointer to the tm structure if the conversion was successful, NULL otherwise.

Attention:

The C standard defines this function with the prototype
struct tm *gmtime( const time_t *timep );
The function should fetch the time value from the location pointed by the timep pointer and return a pointer to a statically allocated structure, therefore it is not thread safe. As a band-aid solution a new function has been defined in the standard:
struct tm *gmtime_r( const time_t *timep, struct tm *tm );
This implementation uses the gmtime_r() semantics but calls the function gmtime(). Furthermore, instead of passing a pointer to the UNIX time, the implementation passes it directly. If you want a really standard-compliant function you can write one easily:

        struct tm *gmtime_r( const time_t *timep, struct tm *tm )
        {
            return gmtime( *timep, tm );
        }

struct tm* localtime	(	time_t	utc,
		struct tm *	tm
	)			[read]

Converts the unix time to the broken-down time structure.

This function has the same semantics as gmtime(), with one exception. The tm structure's timezone field is assumed to be valid and the UTC time argument is offseted by tm->tm_gmtoff before conversion. If the timezone offset is more than +/- 1 day or if the offseted value is less than 0 or more than (time_t) -2, then the conversion will fail.

Parameters:

	utc	The unix time to convert
	tm	Pointer to the tm structure where the result will be stored

Returns:

The pointer to the tm structure if the conversion was successful, NULL otherwise.

Attention:

The same differences between the C standard and this implementation apply as with the gmtime() function.

time_t mktime

(

const struct tm *

tm

)

Converts a broken-down representation to unsigned UNIX time.

The function returns the number of seconds between 1970-01-01 00:00:00 UTC and the local time represented in the structure. The tm_wday and tm_yday fields are ignored. The tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec and tm_gmtoff fields are used to calculate a time. The fields are not checked for validity, except:

• the tm_mon field must be between 0 and 11, since there's no way to determine the length of a month beyond December
• the tm_gmtoff field is checked to be between +/- 24 hours.
• the tm_year field is checked to be at least 70

Furthermore, the calculated time must fit in time_t. If the structure contains invalid or unrepresentable time, then TIME_INVALID is returned.

Parameters:

tm

Pointer to the broken-down time structure.

Returns:

The UNIX time corresponding to the structure

Attention:

The C standard specifies that the function, after calculating the UNIX time, converts it back to the structure, so that the structure becomes normalised. This implementation deviates from the standard because it does not convert the UNIX time back. If you want to do that, all it takes is a call to localtime(). However, if you do not want to do that, there's no reason to waste CPU time with unnecessary calculations.