Timezone handling routines. More...

Macros
#define	BUILTIN_TZID_PREFIX "/freeassociation.sourceforge.net/"
#define	BUILTIN_TZID_PREFIX_LEN 256
#define	ICALTIMEZONE_EXTRA_COVERAGE 5
#define	ICALTIMEZONE_MAX_YEAR 2037
#define	ZONEINFO_DIRECTORY PACKAGE_DATA_DIR "/zoneinfo"
#define	ZONES_TAB_FILENAME "zones.tab"

Functions
void	icaltimezone_convert_time (struct icaltimetype tt, icaltimezone from_zone, icaltimezone *to_zone)
icaltimezone *	icaltimezone_copy (const icaltimezone *originalzone)
bool	icaltimezone_dump_changes (icaltimezone zone, int max_year, FILE fp)
void	icaltimezone_expand_vtimezone (icalcomponent comp, int end_year, icalarray changes)
void	icaltimezone_free (icaltimezone *zone, int free_struct)
	Frees all memory used for the icaltimezone.
void	icaltimezone_free_builtin_timezones (void)
	Releases builtin timezone memory.
void	icaltimezone_free_zone_directory (void)
icaltimezone *	icaltimezone_get_builtin_timezone (const char *location)
icaltimezone *	icaltimezone_get_builtin_timezone_from_offset (int offset, const char *tzname)
icaltimezone *	icaltimezone_get_builtin_timezone_from_tzid (const char *tzid)
icalarray *	icaltimezone_get_builtin_timezones (void)
bool	icaltimezone_get_builtin_tzdata (void)
icalcomponent *	icaltimezone_get_component (icaltimezone *zone)
const char *	icaltimezone_get_display_name (icaltimezone *zone)
double	icaltimezone_get_latitude (const icaltimezone *zone)
const char *	icaltimezone_get_location (const icaltimezone *zone)
char *	icaltimezone_get_location_from_vtimezone (icalcomponent *component)
double	icaltimezone_get_longitude (const icaltimezone *zone)
const char *	icaltimezone_get_system_zone_directory (void)
const char *	icaltimezone_get_tzid (icaltimezone *zone)
const char *	icaltimezone_get_tznames (icaltimezone *zone)
char *	icaltimezone_get_tznames_from_vtimezone (icalcomponent *component)
int	icaltimezone_get_utc_offset (icaltimezone zone, const struct icaltimetype tt, int *is_daylight)
int	icaltimezone_get_utc_offset_of_utc_time (icaltimezone zone, const struct icaltimetype tt, int *is_daylight)
icaltimezone *	icaltimezone_get_utc_timezone (void)
const char *	icaltimezone_get_zone_directory (void)
icaltimezone *	icaltimezone_new (void)
void	icaltimezone_set_builtin_tzdata (bool set)
bool	icaltimezone_set_component (icaltimezone zone, icalcomponent comp)
void	icaltimezone_set_system_zone_directory (const char *zonepath)
void	icaltimezone_set_tzid_prefix (const char *new_prefix)
void	icaltimezone_set_zone_directory (const char *path)
void	icaltimezone_truncate_vtimezone (icalcomponent *vtz, icaltimetype start, icaltimetype end, bool ms_compatible)
const char *	icaltimezone_tzid_prefix (void)

Detailed Description

Timezone handling routines.

Definition in file icaltimezone.c.

Macro Definition Documentation

◆ BUILTIN_TZID_PREFIX

#define BUILTIN_TZID_PREFIX "/freeassociation.sourceforge.net/"

The default prefix we use to uniquely identify TZIDs. It must begin and end with forward slashes.

Use icaltimezone_set_tzid_prefix() and icaltimezone_tzid_prefix() to set/get this value.

Definition at line 71 of file icaltimezone.c.

◆ BUILTIN_TZID_PREFIX_LEN

#define BUILTIN_TZID_PREFIX_LEN 256

The maximum number of characters permitted for the BUILTIN_TZID_PREFIX string.

Definition at line 63 of file icaltimezone.c.

◆ ICALTIMEZONE_EXTRA_COVERAGE

#define ICALTIMEZONE_EXTRA_COVERAGE 5

The number of years of extra coverage we do when expanding the timezone changes.

Definition at line 106 of file icaltimezone.c.

◆ ICALTIMEZONE_MAX_YEAR

#define ICALTIMEZONE_MAX_YEAR 2037

This is the maximum year we will expand to, since 32-bit icaltime_t values only go up to the start of 2038.

Definition at line 115 of file icaltimezone.c.

◆ ZONEINFO_DIRECTORY

#define ZONEINFO_DIRECTORY PACKAGE_DATA_DIR "/zoneinfo"

This is the toplevel directory where the timezone data is installed in.

Definition at line 58 of file icaltimezone.c.

◆ ZONES_TAB_FILENAME

#define ZONES_TAB_FILENAME "zones.tab"

The name of the file containing the city names and coordinates of all the builtin timezones.

Definition at line 100 of file icaltimezone.c.

Function Documentation

◆ icaltimezone_convert_time()

void icaltimezone_convert_time	(	struct icaltimetype *	tt,
		icaltimezone *	from_zone,
		icaltimezone *	to_zone )

Rotate a time from one timezone to another.

Parameters

tt	is a the icaltimetype to rotate. If `tt` represents a date (ie. there is no associated time) then no conversion is performed.
from_zone	is the timezone to rotate from. Any timezone specified inside the icaltimetype is ignored. If `from_zone` is NULL then no conversion is performed.
to_zone	is the timezone to rotate to. If `to_zone` is NULL then the time is rotated to UTC.

Definition at line 830 of file icaltimezone.c.

◆ icaltimezone_copy()

icaltimezone * icaltimezone_copy ( const icaltimezone * originalzone )

Deep clones an icaltimezone.

Invalid icaltimezone data structures can also be cloned.

Parameters

originalzone is a pointer to an icaltimezone.

Returns: a pointer to the cloned icaltimezone.

Definition at line 243 of file icaltimezone.c.

◆ icaltimezone_dump_changes()

bool icaltimezone_dump_changes	(	icaltimezone *	zone,
		int	max_year,
		FILE *	fp )

Outputs a list of timezone changes for the given timezone to the given file, up to the maximum year given.

We compare this output with the output from 'vzic –dump-changes' to make sure that we are consistent. (vzic is the Olson timezone database to VTIMEZONE converter.)

The output format is:

 Zone-Name [tab] Date [tab] Time [tab] UTC-Offset

The Date and Time fields specify the time change in UTC.

The UTC Offset is for local (wall-clock) time. It is the amount of time to add to UTC to get local time.

Parameters

zone	is a pointer to a valid icaltimezone to use
max_year	is the maximum year to process
fp	is a pointer to FILE for a file that is opened for writing

Returns: true. always.

Definition at line 2010 of file icaltimezone.c.

◆ icaltimezone_expand_vtimezone()

void icaltimezone_expand_vtimezone	(	icalcomponent *	comp,
		int	end_year,
		icalarray *	changes )

Applies a list of timezone changes from an array of changes until an end year.

Parameters

comp	a pointer to a valid icalcomponent
end_year	the end year
changes	a pointer to an icalarray containing the changes to be applied

Definition at line 570 of file icaltimezone.c.

◆ icaltimezone_free()

void icaltimezone_free	(	icaltimezone *	zone,
		int	free_struct )

Frees all memory used for the icaltimezone.

Parameters

zone	The icaltimezone to be freed
free_struct	Whether to free the icaltimezone struct as well

Definition at line 277 of file icaltimezone.c.

◆ icaltimezone_free_builtin_timezones()

void icaltimezone_free_builtin_timezones ( void )

Releases builtin timezone memory.

Definition at line 1398 of file icaltimezone.c.

◆ icaltimezone_free_zone_directory()

void icaltimezone_free_zone_directory ( void )

Frees the zonefile directory.

Frees the memory allocated by the icaltimezone_set_zone_directory()

Definition at line 2301 of file icaltimezone.c.

◆ icaltimezone_get_builtin_timezone()

icaltimezone * icaltimezone_get_builtin_timezone ( const char * location )

Gets a single builtin timezone, given its Olson location.

Parameters

location a pointer to a char string containing the Olson location to search

Returns: a pointer to a builtin icaltimezone that matches the specified Olson location. NULL is returned if the location is empty or if the search fails.

Definition at line 1406 of file icaltimezone.c.

◆ icaltimezone_get_builtin_timezone_from_offset()

icaltimezone * icaltimezone_get_builtin_timezone_from_offset	(	int	offset,
		const char *	tzname )

Gets a single builtin timezone, given its offset from UTC.

Parameters

offset	the offset from UTC to search
tzname	a pointer to a char string containing a TZNAME to search.

Returns: a pointer to a builtin icaltimezone that matches the specified offset and tzname. NULL is returned if tzname is NULL or if the search fails.

Definition at line 1489 of file icaltimezone.c.

◆ icaltimezone_get_builtin_timezone_from_tzid()

icaltimezone * icaltimezone_get_builtin_timezone_from_tzid ( const char * tzid )

Gets Returns a single builtin timezone, given its TZID.

Parameters

tzid	a pointer to a char string containing the TZID to find

Returns: a pointer to a builting icaltimezone for the specified TZID.

Definition at line 1519 of file icaltimezone.c.

◆ icaltimezone_get_builtin_timezones()

icalarray * icaltimezone_get_builtin_timezones ( void )

Gets an icalarray of icaltimezone structs, one for each builtin timezone.

This will load and parse the zones.tab file to get the timezone names and their coordinates. It will not load the VTIMEZONE data for any timezones.

Returns: a pointer to an icalarray containing the list of icaltimezone structs associated with the buildtin timezones.

Definition at line 1389 of file icaltimezone.c.

◆ icaltimezone_get_builtin_tzdata()

bool icaltimezone_get_builtin_tzdata ( void )

Get if the library is using builtin timezone data.

Returns: true if the builtin timezone data is being used; false otherwise.

Definition at line 2321 of file icaltimezone.c.

◆ icaltimezone_get_component()

icalcomponent * icaltimezone_get_component ( icaltimezone * zone )

Gets the VTIMEZONE component of a timezone.

Parameters

zone	is a pointer to a valid icaltimezone.

Returns: a pointer to the VTIMEZONE component of the specified icaltimezone.

Definition at line 1291 of file icaltimezone.c.

◆ icaltimezone_get_display_name()

const char * icaltimezone_get_display_name ( icaltimezone * zone )

Get the timezone display name.

We prefer to use the Olson city name, but fall back on the TZNAME, or finally the TZID. We don't want to use "" as it may be wrongly interpreted as a floating time. Do not free the returned string.

Parameters

zone	a pointer to a valid icaltimezone

Returns: a pointer to a char string containing the timezone display name.

Definition at line 1330 of file icaltimezone.c.

◆ icaltimezone_get_latitude()

double icaltimezone_get_latitude ( const icaltimezone * zone )

Gets the latitude of a builtin timezone.

Parameters

zone	a pointer to a valid icaltimezone

Returns: the latitude of the specified icaltimezone as a double.

Definition at line 1267 of file icaltimezone.c.

◆ icaltimezone_get_location()

const char * icaltimezone_get_location ( const icaltimezone * zone )

Gets the LOCATION of a timezone.

Parameters

zone	a pointer to a valid icaltimezone

Returns: a pointer to a char string containing the LOCATION for the specified timezone. NULL will be returned for floating timezones.

Definition at line 1243 of file icaltimezone.c.

◆ icaltimezone_get_location_from_vtimezone()

char * icaltimezone_get_location_from_vtimezone ( icalcomponent * component )

Gets the LOCATION or X-LIC-LOCATION property from a VTIMEZONE.

Parameters

component is a pointer to a valid icalcomponent.

Returns: a pointer to a char string containing the LOCATION or X-LIC-LOCATION property for the specified icalcomponent.

Definition at line 365 of file icaltimezone.c.

◆ icaltimezone_get_longitude()

double icaltimezone_get_longitude ( const icaltimezone * zone )

Gets the longitude of a builtin timezone.

Parameters

zone	a pointer to a valid icaltimezone

Returns: the longitude of the specified icaltimezone as a double.

Definition at line 1279 of file icaltimezone.c.

◆ icaltimezone_get_system_zone_directory()

const char * icaltimezone_get_system_zone_directory ( void )

Gets the fullpath to the system zoneinfo directory (where zone.tab lives). The returned value points to static memory inside the library and should not try to be freed.

If the TZDIR variable appears in the environment, it will be searched first for zone.tab. If zone.tab is not located in TZDIR (or if TZDIR is not in the environment), then a list of well-known paths where the system zone.tab typically is installed is searched.

Returns: a pointer to a char string containing the system zoneinfo directory name.

Since: 4.0 previously known as icaltzutil_get_zone_directory

Definition at line 2268 of file icaltimezone.c.

◆ icaltimezone_get_tzid()

const char * icaltimezone_get_tzid ( icaltimezone * zone )

Gets the TZID of a timezone.

Parameters

zone	a pointer to a valid icaltimezone

Returns: a pointer to a char string containing the TZID for the specified icaltimezone. NULL will be returned for floating timezones.

Definition at line 1231 of file icaltimezone.c.

◆ icaltimezone_get_tznames()

const char * icaltimezone_get_tznames ( icaltimezone * zone )

Gets the TZNAME properties used in the latest STANDARD and DAYLIGHT components a a builtin timezone.

If they are the same it will return just one, e.g. "LMT". If they are different it will format them like "EST/EDT".

Parameters

zone	is a pointer to a valid icaltimezone

Returns: a pointer to a char string containing the TZNAME for the specified icaltimezone. NULL will be returned for floating timezones.

Definition at line 1255 of file icaltimezone.c.

◆ icaltimezone_get_tznames_from_vtimezone()

char * icaltimezone_get_tznames_from_vtimezone ( icalcomponent * component )

Gets the TZNAMEs used for the last STANDARD & DAYLIGHT components in a VTIMEZONE.

If both STANDARD and DAYLIGHT components use the same TZNAME, it returns that. If they use different TZNAMEs, it formats them like "EST/EDT". The returned string should be freed by the caller.

Parameters

component a pointer to a valid icalcomponent

Returns: a pointer to a char string containing the TZNAMEs.

Definition at line 393 of file icaltimezone.c.

◆ icaltimezone_get_utc_offset()

int icaltimezone_get_utc_offset	(	icaltimezone *	zone,
		const struct icaltimetype *	tt,
		int *	is_daylight )

Calculates the UTC offset of a given local time in the given timezone.

It is the number of seconds to add to UTC to get local time.

Parameters

zone	is a pointer to a valid icaltimezone
tt	is an icaltimetype with the local time
is_daylight	is a pointer to an int which will be set to 1 (true) on return if the time is in daylight-savings; in non-daylight-saving it will be set to 0 (false).

Returns: the UTC offset corresponding to the timezone change. For local times and UTC a 0 offset is returned. Additionally, if tt is NULL or if the tt year is too large a 0 offset is returned.

Definition at line 853 of file icaltimezone.c.

◆ icaltimezone_get_utc_offset_of_utc_time()

int icaltimezone_get_utc_offset_of_utc_time	(	icaltimezone *	zone,
		const struct icaltimetype *	tt,
		int *	is_daylight )

Calculates the UTC offset of a given UTC time in the given timezone.

It is the number of seconds to add to UTC to get local time.

Parameters

zone	is a pointer to a valid icaltimezone
tt	is an icaltimetype with the UTC time
is_daylight	is a pointer to an int which will be set to 1 (true) on return if the time is in daylight-savings; in non-daylight-saving it will be set to 0 (false).

Returns: the UTC offset corresponding to the timezone change. For local times and UTC a 0 offset is returned.

Definition at line 1018 of file icaltimezone.c.

◆ icaltimezone_get_utc_timezone()

icaltimezone * icaltimezone_get_utc_timezone ( void )

Gets the UTC timezone.

Returns: a pointer to an icaltimezone representing the UTC timezone.

Definition at line 1588 of file icaltimezone.c.

◆ icaltimezone_get_zone_directory()

const char * icaltimezone_get_zone_directory ( void )

Gets the directory to look for the zonefiles, either system or builtin.

Returns: a pointer to a char string containing the zonefile directory name.

Definition at line 2277 of file icaltimezone.c.

◆ icaltimezone_new()

icaltimezone * icaltimezone_new ( void )

Creates a new icaltimezone. The data structure contains all null values and is essentially invalid.

Returns: a pointer to the new invalid icaltimezone.

Definition at line 228 of file icaltimezone.c.

◆ icaltimezone_set_builtin_tzdata()

void icaltimezone_set_builtin_tzdata ( bool set )

Set the library to use builtin timezone data.

Parameters

set	if true, configures the library to use builtin timezone data; otherwise, the system timezone data is used.

Definition at line 2316 of file icaltimezone.c.

◆ icaltimezone_set_component()

bool icaltimezone_set_component	(	icaltimezone *	zone,
		icalcomponent *	comp )

Sets the VTIMEZONE component of an icaltimezone, initializing the tzid, location & tzname fields.

Parameters

zone	a pointer to a valid icaltimezone
comp	is a pointer to a valid icalcomponent to use

Returns: true on success or false on failure, i.e. no TZID was found.

Definition at line 1303 of file icaltimezone.c.

◆ icaltimezone_set_system_zone_directory()

void icaltimezone_set_system_zone_directory ( const char * zonepath )

Sets the fullpath to the system zoneinfo directory (zone.tab must reside in there).

Parameters

zonepath const character string containing the fullpath to the zoneinfo directory.

The internal zoneinfo path can be cleared if zonepath is empty or NULL.

Since: 4.0 previously known as icaltzutil_set_zone_directory

Definition at line 2233 of file icaltimezone.c.

◆ icaltimezone_set_tzid_prefix()

void icaltimezone_set_tzid_prefix ( const char * new_prefix )

Sets the prefix to be used for tzid's generated from system tzdata. Must be globally unique (such as a domain name owned by the developer of the calling application), and begin and end with forward slashes. The string must be less than 256 chars long.

No error or sanity checking is performed in this function; the caller is entirely responsible for using a proper tzid string.

Do not change or de-allocate the string buffer after calling this.

Parameters

new_prefix a string (properly formatted and less then 256 characters long) representing the tzid for the system tzdata. If not specified, the library default "/freeassociation.sourceforge.net/" is used.

Definition at line 2309 of file icaltimezone.c.

◆ icaltimezone_set_zone_directory()

void icaltimezone_set_zone_directory ( const char * path )

Sets the directory to look for the zonefiles, either system or builtin.

The memory allocated by this function should be freed using icaltimezone_set_zone_directory().

Parameters

path	is a char string containing the directory path for zoneinfo data.

Definition at line 2286 of file icaltimezone.c.

◆ icaltimezone_truncate_vtimezone()

void icaltimezone_truncate_vtimezone	(	icalcomponent *	vtz,
		icaltimetype	start,
		icaltimetype	end,
		bool	ms_compatible )

Truncate a VTIMEZONE component to the given start and end times.

If either time is null, then no truncation will occur at that point. If either time is non-null, then it MUST be specified as UTC. If the start time is non-null and ms_compatible is false, then the DTSTART of RRULEs will be adjusted to occur after the start time.

Parameters

vtz	is a pointer to a valid VTIMEZONE icalcomponent
start	is the starting icaltimetype
end	is the ending icaltimetype
ms_compatible	is a flag indicating if the truncation should be compatible with Microsoft Outlook/Exchange (which doesn't appear to like truncating the frontend of RRULEs).

Since: 3.0.6

Definition at line 2355 of file icaltimezone.c.

◆ icaltimezone_tzid_prefix()

const char * icaltimezone_tzid_prefix ( void )

Get the current setting of the tzid prefix.

Returns: a pointer to a char string containing the current tzid prefix.

Definition at line 223 of file icaltimezone.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BUILTIN_TZID_PREFIX

◆ BUILTIN_TZID_PREFIX_LEN

◆ ICALTIMEZONE_EXTRA_COVERAGE

◆ ICALTIMEZONE_MAX_YEAR

◆ ZONEINFO_DIRECTORY

◆ ZONES_TAB_FILENAME

Function Documentation

◆ icaltimezone_convert_time()

◆ icaltimezone_copy()

◆ icaltimezone_dump_changes()

◆ icaltimezone_expand_vtimezone()

◆ icaltimezone_free()

◆ icaltimezone_free_builtin_timezones()

◆ icaltimezone_free_zone_directory()

◆ icaltimezone_get_builtin_timezone()

◆ icaltimezone_get_builtin_timezone_from_offset()

◆ icaltimezone_get_builtin_timezone_from_tzid()

◆ icaltimezone_get_builtin_timezones()

◆ icaltimezone_get_builtin_tzdata()

◆ icaltimezone_get_component()

◆ icaltimezone_get_display_name()

◆ icaltimezone_get_latitude()

◆ icaltimezone_get_location()

◆ icaltimezone_get_location_from_vtimezone()

◆ icaltimezone_get_longitude()

◆ icaltimezone_get_system_zone_directory()

◆ icaltimezone_get_tzid()

◆ icaltimezone_get_tznames()

◆ icaltimezone_get_tznames_from_vtimezone()

◆ icaltimezone_get_utc_offset()

◆ icaltimezone_get_utc_offset_of_utc_time()

◆ icaltimezone_get_utc_timezone()

◆ icaltimezone_get_zone_directory()

◆ icaltimezone_new()

◆ icaltimezone_set_builtin_tzdata()

◆ icaltimezone_set_component()

◆ icaltimezone_set_system_zone_directory()

◆ icaltimezone_set_tzid_prefix()

◆ icaltimezone_set_zone_directory()

◆ icaltimezone_truncate_vtimezone()

◆ icaltimezone_tzid_prefix()