Time

Modules
	Date Time
	Time Calculations
	Parsing
	Timezone

Data Structures
struct	M_time_gmtm_t
struct	M_timeval_t

Typedefs
typedef M_int64	M_time_t
typedef M_int64	M_suseconds_t
typedef struct M_time_tz	M_time_tz_t
typedef struct M_time_tzs	M_time_tzs_t

Enumerations
enum	M_time_tz_zones_t {   M_TIME_TZ_ZONE_ALL = 0 ,   M_TIME_TZ_ZONE_AFRICA = 1 << 1 ,   M_TIME_TZ_ZONE_AMERICA = 1 << 2 ,   M_TIME_TZ_ZONE_ANTARCTICA = 1 << 3 ,   M_TIME_TZ_ZONE_ARCTIC = 1 << 4 ,   M_TIME_TZ_ZONE_ASIA = 1 << 5 ,   M_TIME_TZ_ZONE_ATLANTIC = 1 << 6 ,   M_TIME_TZ_ZONE_AUSTRALIA = 1 << 7 ,   M_TIME_TZ_ZONE_EUROPE = 1 << 8 ,   M_TIME_TZ_ZONE_INDIAN = 1 << 9 ,   M_TIME_TZ_ZONE_PACIFIC = 1 << 10 ,   M_TIME_TZ_ZONE_ETC = 1 << 11 }
enum	M_time_tz_load_t {   M_TIME_TZ_LOAD_NORMAL = 0 ,   M_TIME_TZ_LOAD_LAZY = 1 << 1 }
enum	M_time_tz_alias_t {   M_TIME_TZ_ALIAS_ALL = 0 ,   M_TIME_TZ_ALIAS_OLSON_MAIN = 1 << 1 ,   M_TIME_TZ_ALIAS_OLSON_ALL = 1 << 2 ,   M_TIME_TZ_ALIAS_WINDOWS_MAIN = 1 << 3 ,   M_TIME_TZ_ALIAS_WINDOWS_ALL = 1 << 4 }
enum	M_time_result_t {   M_TIME_RESULT_SUCCESS = 0 ,   M_TIME_RESULT_INVALID ,   M_TIME_RESULT_ERROR ,   M_TIME_RESULT_DUP ,   M_TIME_RESULT_INI ,   M_TIME_RESULT_ABBR ,   M_TIME_RESULT_OFFSET ,   M_TIME_RESULT_DATE ,   M_TIME_RESULT_TIME ,   M_TIME_RESULT_DATETIME ,   M_TIME_RESULT_YEAR ,   M_TIME_RESULT_DSTABBR ,   M_TIME_RESULT_DSTOFFSET }
enum	M_time_load_source_t {   M_TIME_LOAD_SOURCE_FAIL = 0 ,   M_TIME_LOAD_SOURCE_SYSTEM ,   M_TIME_LOAD_SOURCE_FALLBACK }

Detailed Description

Time handling functions.

Features

Covers:

• Local
• GMT
• Normalization
• Conversion
• Diff
• Elapsed
• Time zone
• string reading
• string writing

Key data types

M_time_t is provided as a platform agnostic replacement for time_t. M_time_t a signed 64 bit data type. This allows systems which provide a 32 bit time_t to handle times above the 32 bit boundary. However, any functions (such as M_time) that use underlying system time functions will only operate using the bit max/min provided by the system time_t.

M_timeval_t (struct M_timeval) is also provided for the same reasons as M_time_t. In addition, not all platforms support struct timval in an obvious way. Windows in particular can have header conflict issues when dealing with struct timeval. Specifically, struct timeval is defined in Winsock2.h which much be included before Windows.h. Either this header would have to include, which can lead to problems is this header is included after Windows.h is declared. Or an application using mstdlib would have to include Winsock2.h, which is nonobvious.

Timezone

Time zone data is stored in a timezone database object. Data can be loaded in two ways.

• Loading a timezone database (Olson files, Windows registry).
• Loading individual timezone data.

Lazy loading is available when using a timezone database. Lazy loading has the data read into the db on demand instead of reading the data immediately. Only one timezone data source can be used for lazy loading.

When using lazy loading in a multi threaded environment all calls to M_time_tzs_get_tz need to be protected by a mutex or other access broker.

The tz (timezone) object should not be used directly. Instead it should be passed to M_time_tolocal or M_time_fromlocal.

Examples

Timezone

M_time_tzs_t      *tzs;
const M_time_tz_t *tz;
M_time_t           ts = 1375277153;
M_time_t           cs;
M_time_localtm_t   ltime;
 
M_mem_set(&ltime, 0, sizeof(ltime));
 
tzs = M_time_tzs_load_zoneinfo(NULL, M_TIME_TZ_ZONE_AMERICA, M_TIME_TZ_ALIAS_OLSON_MAIN, M_TIME_TZ_LOAD_LAZY);
tz  = M_time_tzs_get_tz(tzs, "America/New_York");
 
M_time_tolocal(ts, &ltime, tz);
 
M_printf("isdst='%s'\n", ltime.isdst?"YES":"NO");
 
cs = M_time_fromlocal(&ltime, tz);
if (ts != cs) {
    M_printf("time conversion failed\n");
} else {
    M_printf("time conversion success\n");
}
 
M_time_tzs_destroy(tzs);

System

M_time_localtm_t ltime;
M_time_t         ts;
 
M_mem_set(&ltime, 0, sizeof(ltime));
 
M_time_tolocal(0, &ltime, NULL);
t = M_time_fromlocal(&ltime, NULL);
 
if (t != 0) {
    M_printf("time conversion failed\n");
} else {
    M_printf("time conversion success\n");
}

Time Strings

M_time_t          ts;
char             *out;
M_time_localtm_t  ltime;
 
M_mem_set(&ltime, 0, sizeof(ltime));
 
ts  = M_time_from_str("1998/11/31 10:02:50", NULL, M_FALSE);
M_time_tolocal(ts, &ltime, NULL);
out = M_time_to_str("%Y-%m-%d %H:%M:%S %p", &tm);
M_printf("out='%s'\n", out);
M_free(out);

---

Data Structure Documentation

M_time_tm

struct M_time_tm

Broken down time stored as individual components.

Data Fields
M_int64	month	Month. 1-12
M_int64	day	Day of month. 1-X
M_int64	year	Year. Full year. E.g. 2013.
M_int64	year2	2digit Year. E.g. 13.
M_int64	hour	hour. 0=Midnight ... 23=11PM.
M_int64	min	minute. 0-59.
M_int64	sec	second. 0-59.
M_int64	wday	day of week. 0=Sun ... 6=Sat
M_int64	yday	day of year. 0-364 (or 365 on leap years)
M_int64	isdst	-1=DST unknown, 0=not DST, 1=is DST
M_time_t	gmtoff	Seconds west of Greenwich.
char	abbr[32]	Abbreviation for use with printing. This will only be filled if a M_time_tz_t is passed in with the time. If abbr is filled by a M_time_tz_t then the M_time_tz_t must remain valid for the life of the struct.

M_timeval_t

struct M_timeval_t

Number of seconds and microseconds since the Epoch.

Data Fields
M_time_t	tv_sec	Seconds.
M_suseconds_t	tv_usec	Microseconds.

Typedef Documentation

M_time_t

typedef M_int64 M_time_t

M_suseconds_t

typedef M_int64 M_suseconds_t

M_time_tz_t

typedef struct M_time_tz M_time_tz_t

M_time_tzs_t

typedef struct M_time_tzs M_time_tzs_t

Enumeration Type Documentation

M_time_tz_zones_t

enum M_time_tz_zones_t

Olson/TZ/Zoneinfo locations that can be loaded.

Enumerator
M_TIME_TZ_ZONE_ALL	Load all zones. This cannot be combined with individual zones.
M_TIME_TZ_ZONE_AFRICA	Load data form Africa.
M_TIME_TZ_ZONE_AMERICA	Load data form the Americas.
M_TIME_TZ_ZONE_ANTARCTICA	Load data form Antarctica.
M_TIME_TZ_ZONE_ARCTIC	Load data form the artic.
M_TIME_TZ_ZONE_ASIA	Load data form Asia.
M_TIME_TZ_ZONE_ATLANTIC	Load data form the Atlantic.
M_TIME_TZ_ZONE_AUSTRALIA	Load data form Australia.
M_TIME_TZ_ZONE_EUROPE	Load data form Europe.
M_TIME_TZ_ZONE_INDIAN	Load data form the Indian ocean region.
M_TIME_TZ_ZONE_PACIFIC	Load data form the Pacific.
M_TIME_TZ_ZONE_ETC	Load data form Etc (fixed offset) zones.

M_time_tz_load_t

enum M_time_tz_load_t

Flags to control loading behavior of Olson/TZ/Zoneinfo data.

Enumerator
M_TIME_TZ_LOAD_NORMAL	Load all data.
M_TIME_TZ_LOAD_LAZY	Lazy load data. This is really only useful for memory constrained environments where only a few zones will be in use but the overhead of loading all zones may be too much for the system.

M_time_tz_alias_t

enum M_time_tz_alias_t

Handle alias loading. Not all alias options will be avalaible for all zone data sources.

Enumerator
M_TIME_TZ_ALIAS_ALL	Include all names and aliases.
M_TIME_TZ_ALIAS_OLSON_MAIN	Include main Olson alias.
M_TIME_TZ_ALIAS_OLSON_ALL	Include all Olson aliases.
M_TIME_TZ_ALIAS_WINDOWS_MAIN	Include Windows zone names.
M_TIME_TZ_ALIAS_WINDOWS_ALL	Include Windows zone names.

M_time_result_t

enum M_time_result_t

Result codes specific to time operations.

Enumerator
M_TIME_RESULT_SUCCESS	Success.
M_TIME_RESULT_INVALID	Invalid argument.
M_TIME_RESULT_ERROR	General error.
M_TIME_RESULT_DUP	Duplicate.
M_TIME_RESULT_INI	ini failed to parse.
M_TIME_RESULT_ABBR	Std abbreviation failed to parse.
M_TIME_RESULT_OFFSET	Std offset failed to parse.
M_TIME_RESULT_DATE	Date failed to parse.
M_TIME_RESULT_TIME	Time failed to parse.
M_TIME_RESULT_DATETIME	Date/time failed to parse.
M_TIME_RESULT_YEAR	Year failed to parse.
M_TIME_RESULT_DSTABBR	DST abbreviation failed to parse.
M_TIME_RESULT_DSTOFFSET	DST offset failed to parse.

M_time_load_source_t

enum M_time_load_source_t

Source timezone data was loaded form.

See also

M_time_tzs_load

Enumerator
M_TIME_LOAD_SOURCE_FAIL	Timezone data failed to load. This can happen if no timezone data was loaded. For example, a specific M_time_tz_zones_t was requested but not available.
M_TIME_LOAD_SOURCE_SYSTEM	The system timezone data was loaded.
M_TIME_LOAD_SOURCE_FALLBACK	Main four US timezones were loaded as a fallback because system data could not be loaded.