- Generated on Sat Aug 23 2025 01:46:17 for php-internal-docs by
1.13.2
|
php-internal-docs 8.4.8
Unofficial docs for php/php-src
|
#include <stdlib.h>#include <stdbool.h>#include <limits.h>#include <inttypes.h>Go to the source code of this file.
Data Structures | |
| struct | _tlocinfo |
| struct | _timelib_posix_trans_info |
| struct | _timelib_posix_str |
| struct | _timelib_posix_transitions |
| struct | _timelib_tzinfo |
| struct | _timelib_rel_time |
| struct | _timelib_time_offset |
| struct | _timelib_time |
| struct | _timelib_abbr_info |
| struct | _timelib_error_message |
| struct | _timelib_error_container |
| struct | _timelib_tz_lookup_table |
| struct | _timelib_tzdb_index_entry |
| struct | _timelib_tzdb |
| struct | _timelib_format_specifier |
| struct | _timelib_format_config |
| #define TIMELIB_ERROR_CORRUPT_TRANSITIONS_DONT_INCREASE 0x02 |
| #define TIMELIB_ULONG_MAX UINT32_MAX |
| typedef struct _timelib_abbr_info timelib_abbr_info |
| typedef struct _timelib_error_container timelib_error_container |
| typedef struct _timelib_error_message timelib_error_message |
| typedef struct _timelib_format_config timelib_format_config |
| typedef struct _timelib_format_specifier timelib_format_specifier |
| typedef int32_t timelib_long |
| typedef struct _timelib_posix_str timelib_posix_str |
| typedef struct _timelib_posix_trans_info timelib_posix_trans_info |
| typedef struct _timelib_posix_transitions timelib_posix_transitions |
| typedef struct _timelib_rel_time timelib_rel_time |
| typedef signed long long timelib_sll |
| typedef struct _timelib_time timelib_time |
| typedef struct _timelib_time_offset timelib_time_offset |
| typedef timelib_tzinfo *(* timelib_tz_get_wrapper) (const char *tzname, const timelib_tzdb *tzdb, int *error_code) |
| typedef struct _timelib_tz_lookup_table timelib_tz_lookup_table |
| typedef struct _timelib_tzdb timelib_tzdb |
| typedef struct _timelib_tzdb_index_entry timelib_tzdb_index_entry |
| typedef struct _timelib_tzinfo timelib_tzinfo |
| typedef unsigned long long timelib_ull |
| typedef uint32_t timelib_ulong |
| timelib_time * timelib_add | ( | timelib_time * | t, |
| timelib_rel_time * | interval ) |
Adds the relative time information 'interval' to the base time 't'.
This can be a relative time as created by 'timelib_diff', but also by more complex statements such as "next workday".
Definition at line 211 of file interval.c.
| timelib_time * timelib_add_wall | ( | timelib_time * | t, |
| timelib_rel_time * | interval ) |
Definition at line 284 of file interval.c.
| int timelib_astro_rise_set_altitude | ( | timelib_time * | t_loc, |
| double | lon, | ||
| double | lat, | ||
| double | altit, | ||
| int | upper_limb, | ||
| double * | h_rise, | ||
| double * | h_set, | ||
| timelib_sll * | ts_rise, | ||
| timelib_sll * | ts_set, | ||
| timelib_sll * | ts_transit ) |
Calculates when the Sun is above a certain latitude.
Parameters:
Out Parameters:
Return Values:
Note: timestamp = unixtimestamp (NEEDS to be 00:00:00 UT) Eastern longitude positive, Western longitude negative Northern latitude positive, Southern latitude negative The longitude value IS critical in this function! altit = the altitude which the Sun should cross Set to -35/60 degrees for rise/set, -6 degrees for civil, -12 degrees for nautical and -18 degrees for astronomical twilight. upper_limb: non-zero -> upper limb, zero -> center Set to non-zero (e.g. 1) when computing rise/set times, and to zero when computing start/end of twilight. *rise = where to store the rise time *set = where to store the set time Both times are relative to the specified altitude, and thus this function can be used to compute various twilight times, as well as rise/set times Return value: 0 = sun rises/sets this day, times stored at *trise and *tset. +1 = sun above the specified "horizon" 24 hours. *trise set to time when the sun is at south, minus 12 hours while *tset is set to the south time plus 12 hours. "Day" length = 24 hours -1 = sun is below the specified "horizon" 24 hours "Day" length = 0 hours, *trise and *tset are both set to the time when the sun is at south.
| const timelib_tzdb * timelib_builtin_db | ( | void | ) |
Returns a pointer to the built-in time zone database.
You must not free the returned pointer as it is part of the text segment.
Definition at line 606 of file parse_tz.c.
| void timelib_date_from_isodate | ( | timelib_sll | iy, |
| timelib_sll | iw, | ||
| timelib_sll | id, | ||
| timelib_sll * | y, | ||
| timelib_sll * | m, | ||
| timelib_sll * | d ) |
| timelib_long timelib_date_to_int | ( | timelib_time * | d, |
| int * | error ) |
Converts the 'sse' value of 'd' to a timelib_long type.
If the value fits in the TIMELIB_LONG_MIN and TIMELIB_LONG_MAX range, the value is cast to (timelib_long) and returned. If *error is not a NULL pointer, it will be set to 0.
If the value does not fit in the range, the function returns 0 and if *error is not a NULL pointer, it will be set to 1.
timelib_long is a 32 bit signed long integer on 32 bit platforms, and a 64 bit signed long long integer on 64 bit platforms. In other words, it makes sure that the value in 'sse' (which is always a signed long long 64 bit integer) can be used safely outside of the library.
| timelib_sll timelib_day_of_week | ( | timelib_sll | y, |
| timelib_sll | m, | ||
| timelib_sll | d ) |
| timelib_sll timelib_day_of_year | ( | timelib_sll | y, |
| timelib_sll | m, | ||
| timelib_sll | d ) |
| timelib_sll timelib_daynr_from_weeknr | ( | timelib_sll | iy, |
| timelib_sll | iw, | ||
| timelib_sll | id ) |
| timelib_sll timelib_days_in_month | ( | timelib_sll | y, |
| timelib_sll | m ) |
| void timelib_decimal_hour_to_hms | ( | double | h, |
| int * | hour, | ||
| int * | min, | ||
| int * | sec ) |
| timelib_rel_time * timelib_diff | ( | timelib_time * | one, |
| timelib_time * | two ) |
Calculates the difference between two times
The result is a timelib_rel_time structure that describes how you can convert from 'one' to 'two' with 'timelib_add'. This does not necessarily mean that you can go from 'two' to 'one' by using 'timelib_sub' due to the way months and days are calculated.
Definition at line 146 of file interval.c.
| int timelib_diff_days | ( | timelib_time * | one, |
| timelib_time * | two ) |
Calculates the difference in full days between two times
The result is the number of full days between 'one' and 'two'. It does take into account 23 and 25 hour (and variants) days when the zone_type is TIMELIB_ZONETYPE_ID and have the same TZID for 'one' and 'two'.
Definition at line 181 of file interval.c.
| void timelib_do_normalize | ( | timelib_time * | base | ) |
Takes the information from the y/m/d/h/i/s fields and makes sure their values are in the right range.
If a value under- or overflows it will adjust the larger measure up (or down). It also takes into account leap days.
Definition at line 226 of file tm2unixtime.c.
| void timelib_do_rel_normalize | ( | timelib_time * | base, |
| timelib_rel_time * | rt ) |
Takes the information from the y/m/d/h/i/s fields of 'rt' and makes sure their values are in the right range.
If a value under- or overflows it will adjust the larger measure up (or down). As this function operates on a relative date/time, it also takes into account leap days and correctly accounts for the difference depending on the base date/time in 'base'.
Definition at line 188 of file tm2unixtime.c.
| void timelib_dump_date | ( | timelib_time * | d, |
| int | options ) |
| void timelib_dump_rel_time | ( | timelib_rel_time * | d | ) |
| void timelib_dump_tzinfo | ( | timelib_tzinfo * | tz | ) |
Displays debugging information about the time zone information in 'tz'.
Definition at line 510 of file parse_tz.c.
| timelib_sll timelib_epoch_days_from_time | ( | timelib_time * | time | ) |
Returns the number of days from the y/m/d fields of 'time' since the Unix Epoch.
Definition at line 453 of file tm2unixtime.c.
| void timelib_error_container_dtor | ( | timelib_error_container * | errors | ) |
Frees up the resources allocated while converting strings to timelib_time structures with the timelib_strtotime and timelib_strtointerval functions.
| void timelib_fill_holes | ( | timelib_time * | parsed, |
| timelib_time * | now, | ||
| int | options ) |
Definition at line 25529 of file parse_date.c.
| timelib_sll timelib_get_current_offset | ( | timelib_time * | t | ) |
Returns the UTC offset currently applicable for the information stored in 't'.
The value returned is the UTC offset in seconds East.
Definition at line 937 of file parse_tz.c.
| const char * timelib_get_error_message | ( | int | error_code | ) |
| timelib_time_offset * timelib_get_time_zone_info | ( | timelib_sll | ts, |
| timelib_tzinfo * | tz ) |
Returns offset information with time zone 'tz' for the time stamp 'ts'.
The returned information contains: the offset in seconds East of UTC (in 'offset'), whether DST is active ('is_dst'), what the current time zone abbreviation is ('abbr') and the transition time that got to this state (in 'transition_time');
Definition at line 881 of file parse_tz.c.
| int timelib_get_time_zone_offset_info | ( | timelib_sll | ts, |
| timelib_tzinfo * | tz, | ||
| int32_t * | offset, | ||
| timelib_sll * | transition_time, | ||
| unsigned int * | is_dst ) |
Returns offset information with time zone 'tz' for the time stamp 'ts'.
The returned information contains: the offset in seconds East of UTC (in the output parameter 'offset'), whether DST is active (in the output parameter 'is_dst'), and the transition time that got to this state (in the output parameter 'transition_time'); if NULL is passed, the value is not retrieved
Returns 1 if successful, 0 for failure.
Definition at line 913 of file parse_tz.c.
| void timelib_get_transitions_for_year | ( | timelib_tzinfo * | tz, |
| timelib_sll | year, | ||
| timelib_posix_transitions * | transitions ) |
Calculate the two yearly to/from DST
Definition at line 500 of file parse_posix.c.
| void timelib_hms_to_decimal_hour | ( | int | hour, |
| int | min, | ||
| int | sec, | ||
| double * | h ) |
| timelib_sll timelib_hms_to_seconds | ( | timelib_sll | h, |
| timelib_sll | m, | ||
| timelib_sll | s ) |
| void timelib_hmsf_to_decimal_hour | ( | int | hour, |
| int | min, | ||
| int | sec, | ||
| int | us, | ||
| double * | h ) |
| timelib_sll timelib_iso_day_of_week | ( | timelib_sll | y, |
| timelib_sll | m, | ||
| timelib_sll | d ) |
| void timelib_isodate_from_date | ( | timelib_sll | y, |
| timelib_sll | m, | ||
| timelib_sll | d, | ||
| timelib_sll * | iy, | ||
| timelib_sll * | iw, | ||
| timelib_sll * | id ) |
| void timelib_isoweek_from_date | ( | timelib_sll | y, |
| timelib_sll | m, | ||
| timelib_sll | d, | ||
| timelib_sll * | iw, | ||
| timelib_sll * | iy ) |
| timelib_time * timelib_parse_from_format | ( | const char * | format, |
| const char * | s, | ||
| size_t | len, | ||
| timelib_error_container ** | errors, | ||
| const timelib_tzdb * | tzdb, | ||
| timelib_tz_get_wrapper | tz_get_wrapper ) |
Definition at line 25032 of file parse_date.c.
| timelib_time * timelib_parse_from_format_with_map | ( | const char * | format, |
| const char * | s, | ||
| size_t | len, | ||
| timelib_error_container ** | errors, | ||
| const timelib_tzdb * | tzdb, | ||
| timelib_tz_get_wrapper | tz_get_wrapper, | ||
| const timelib_format_config * | format_config ) |
Definition at line 25037 of file parse_date.c.
| timelib_posix_str * timelib_parse_posix_str | ( | const char * | posix | ) |
Definition at line 323 of file parse_posix.c.
| timelib_tzinfo * timelib_parse_tzfile | ( | const char * | timezone, |
| const timelib_tzdb * | tzdb, | ||
| int * | error_code ) |
Converts the binary stored time zone information from 'tzdb' for the time zone 'timezone' into a structure the library can use for calculations.
The function can be used on both timelib_builtin_db as well as a time zone db as opened by timelib_zoneinfo.
'error_code' must not be a null pointer, and will always be written to. If the value is TIMELIB_ERROR_NO_ERROR then the file was parsed without problems.
The function will return null upon failure, and also set an error code through 'error_code'.
The error code is one of the TIMELIB_ERROR_* constants as listed above. These error constants can be converted into a string by timelib_get_error_message.
If the function returns not-null, the 'error_code' might have a non-null value that can be used to detect incompatibilities. The only one that is currently detected is whether the file is a 'slim' file, in which case 'error_code' will be set to TIMELIB_ERROR_SLIM_FILE.
This function allocates memory for the new time zone structure, which must be freed after use. Although it is recommended that a cache of each used time zone is kept.
Definition at line 662 of file parse_tz.c.
| timelib_long timelib_parse_zone | ( | const char ** | ptr, |
| int * | dst, | ||
| timelib_time * | t, | ||
| int * | tz_not_found, | ||
| const timelib_tzdb * | tzdb, | ||
| timelib_tz_get_wrapper | tz_wrapper ) |
DEPRECATED, but still used by PHP.
Definition at line 940 of file parse_date.c.
| void timelib_posix_str_dtor | ( | timelib_posix_str * | ps | ) |
Definition at line 305 of file parse_posix.c.
| timelib_rel_time * timelib_rel_time_clone | ( | timelib_rel_time * | tz | ) |
Creates a new timelib_rel_time resource and copies over the information from 'tz'.
Must be freed with 'timelib_rel_time_dtor'.
| timelib_rel_time * timelib_rel_time_ctor | ( | void | ) |
| void timelib_rel_time_dtor | ( | timelib_rel_time * | t | ) |
| int timelib_same_timezone | ( | timelib_time * | one, |
| timelib_time * | two ) |
Returns whether the timezone information in *one and *two are the same
A timezone is considered the same if:
Definition at line 955 of file parse_tz.c.
| void timelib_set_timezone | ( | timelib_time * | t, |
| timelib_tzinfo * | tz ) |
Attaches the time zone information in 'tz' to to 't'.
It fetches the right UTC offset that is currently stored in the time stamp field in 't' ('sse'), and assigns that to the 'z' field and 'dst' field (whether DST is in effect at the time). It also sets the current abbreviation to the 'tz_addr' field, making sure that if a value was already set it was freed.
The time zone information in 'tz' is not duplicated into the 't' field so it should not be freed until all timelib_time* variables have been freed as well.
Definition at line 191 of file unixtime2tm.c.
| void timelib_set_timezone_from_abbr | ( | timelib_time * | t, |
| timelib_abbr_info | abbr_info ) |
Attaches the information from 'abbr_info' as time zone information to 't'.
The timelib_abbr_info struct contains an abbreviation ('abbr') which string value is duplicated, as well as a 'utc_offset' and 'dst' flag. It only supports a 'dst' change over of 1 hour.
Definition at line 177 of file unixtime2tm.c.
| void timelib_set_timezone_from_offset | ( | timelib_time * | t, |
| timelib_sll | utc_offset ) |
Attaches the UTC offset as time zone information to 't'.
'utc_offset' is in seconds East of UTC.
Definition at line 163 of file unixtime2tm.c.
| void timelib_strtointerval | ( | const char * | s, |
| size_t | len, | ||
| timelib_time ** | begin, | ||
| timelib_time ** | end, | ||
| timelib_rel_time ** | period, | ||
| int * | recurrences, | ||
| timelib_error_container ** | errors ) |
Parses a subset of an ISO 8601 intervals specification string into its constituent parts.
If the **errors points to a timelib_error_container variable, warnings and errors will be recorded. You are responsible for freeing the stored information with timelib_error_container_dtor(). To see whether errors have occurred, inspect errors->errors_count. To see whether warnings have occurred, inspect errors->warnings_count.
Definition at line 971 of file parse_iso_intervals.c.
| timelib_time * timelib_strtotime | ( | const char * | s, |
| size_t | len, | ||
| timelib_error_container ** | errors, | ||
| const timelib_tzdb * | tzdb, | ||
| timelib_tz_get_wrapper | tz_get_wrapper ) |
Definition at line 24849 of file parse_date.c.
| timelib_time * timelib_sub | ( | timelib_time * | t, |
| timelib_rel_time * | interval ) |
Subtracts the relative time information 'interval' to the base time 't'.
This can be a relative time as created by 'timelib_diff'. Unlike with 'timelib_add', this does not support more complex statements such as "next workday".
Definition at line 242 of file interval.c.
| timelib_time * timelib_sub_wall | ( | timelib_time * | t, |
| timelib_rel_time * | interval ) |
Definition at line 338 of file interval.c.
| timelib_time * timelib_time_clone | ( | timelib_time * | orig | ) |
Creates a new timelib_time resource and copies over the information from 'orig'.
Must be freed with 'timelib_time_dtor'.
| int timelib_time_compare | ( | timelib_time * | t1, |
| timelib_time * | t2 ) |
Compares two timelib_time structures and returns which one is earlier in time.
To decide which comes earlier it uses the 'sse' (Seconds Since Epoch) and 'us' (microseconds) fields.
Returns -1 if t1 < t2, 0 if t1 == t2, and -1 if t1 > t2.
| timelib_time * timelib_time_ctor | ( | void | ) |
| void timelib_time_dtor | ( | timelib_time * | t | ) |
| timelib_time_offset * timelib_time_offset_ctor | ( | void | ) |
| void timelib_time_offset_dtor | ( | timelib_time_offset * | t | ) |
| int timelib_timestamp_is_in_dst | ( | timelib_sll | ts, |
| timelib_tzinfo * | tz ) |
Returns whether DST is active with time zone 'tz' for the time stamp 'ts'.
Returns 0 if DST is not active, 1 if DST is active, or -1 if no transitions were available through 'tz'.
Definition at line 870 of file parse_tz.c.
| const timelib_tz_lookup_table * timelib_timezone_abbreviations_list | ( | void | ) |
Definition at line 25586 of file parse_date.c.
| const char * timelib_timezone_id_from_abbr | ( | const char * | abbr, |
| timelib_long | gmtoffset, | ||
| int | isdst ) |
Definition at line 25574 of file parse_date.c.
| int timelib_timezone_id_is_valid | ( | const char * | timezone, |
| const timelib_tzdb * | tzdb ) |
Returns whether the time zone ID 'timezone' is available in the time zone database as pointed to be 'tzdb'.
Definition at line 617 of file parse_tz.c.
| const timelib_tzdb_index_entry * timelib_timezone_identifiers_list | ( | const timelib_tzdb * | tzdb, |
| int * | count ) |
Returns a pointer to the start of an array containing a list of timezone identifiers.
The amount of entries in the array is returned through the 'count' OUT parameter.
Each entry contains the time zone ID ('id' field), and the position within the time zone information ('pos' field). The pos field should not be used.
Definition at line 611 of file parse_tz.c.
| double timelib_ts_to_j2000 | ( | timelib_sll | ts | ) |
Converts the Unix Epoch time stamp 'ts' to the J2000 epoch
The value returned is the number of whole days since 2000-01-01T12:00:00 UTC: https://en.wikipedia.org/wiki/Epoch_(astronomy)#Julian_years_and_J2000
| double timelib_ts_to_julianday | ( | timelib_sll | ts | ) |
Converts the Unix Epoch time stamp 'ts' to a Julian Day
The value returned is the number of whole days since -4714-11-24T12:00:00 UTC (in the proleptic Gregorian calendar): https://en.wikipedia.org/wiki/Julian_day
| timelib_tzinfo * timelib_tzinfo_clone | ( | timelib_tzinfo * | tz | ) |
Deep-clones a timelib_tzinfo structure.
This allocates resources that need to be freed with 'timelib_tzinfo_dtor'
Definition at line 745 of file parse_tz.c.
| void timelib_tzinfo_dtor | ( | timelib_tzinfo * | tz | ) |
Frees up the resources allocated by 'timelib_parse_tzfile'.
Definition at line 728 of file parse_tz.c.
| void timelib_unixtime2date | ( | timelib_sll | ts, |
| timelib_sll * | y, | ||
| timelib_sll * | m, | ||
| timelib_sll * | d ) |
Takes the unix timestamp in seconds from 'ts', and calculates y, m, and d, in the proleptic Gregorian calendar.
It uses the algorithm from howardhinnant.github.io/date_algorithms.html
Definition at line 29 of file unixtime2tm.c.
| void timelib_unixtime2gmt | ( | timelib_time * | tm, |
| timelib_sll | ts ) |
Takes the unix timestamp in seconds from 'ts' and populates the y/m/d/h/i/s fields of 'tm' without taking time zones into account
Definition at line 57 of file unixtime2tm.c.
| void timelib_unixtime2local | ( | timelib_time * | tm, |
| timelib_sll | ts ) |
Takes the Unix timestamp from 'ts', and calculates the y/m/d/h/i/s fields according to the time zone information attached to 'tm'.
Definition at line 120 of file unixtime2tm.c.
| void timelib_update_from_sse | ( | timelib_time * | tm | ) |
Takes the Unix timestamp stored in 'tm', and calculates the y/m/d/h/i/s fields according to the time zone information attached to 'tm'.
Definition at line 83 of file unixtime2tm.c.
| void timelib_update_ts | ( | timelib_time * | time, |
| timelib_tzinfo * | tzi ) |
Uses the y/m/d/h/i/s fields to calculate and store the equivalent timestamp in the sse field.
It uses the time zone information associated with 'time' to account for the right UTC offset and/or DST rules. You can associate time zone information with the timelib_set_timezone_* functions (see below).
If the type is 'TIMELIB_ZONETYPE_ID' and there is no associated tzinfo, it will use the second argument 'tzi' to provide the rules necessary to calculate the right timestamp.
Definition at line 467 of file tm2unixtime.c.
| int timelib_valid_date | ( | timelib_sll | y, |
| timelib_sll | m, | ||
| timelib_sll | d ) |
| int timelib_valid_time | ( | timelib_sll | h, |
| timelib_sll | i, | ||
| timelib_sll | s ) |
| timelib_tzdb * timelib_zoneinfo | ( | const char * | directory | ) |
Scans the directory and subdirectories of 'directory' for valid time zone files and builds a time zone database out of these files.
Typically, the directory should point to '/usr/share/zoneinfo'.
Unlike 'timelib_builtin_db', the return value of this function must be freed with the 'timelib_zoneinfo_dtor' function.
| void timelib_zoneinfo_dtor | ( | timelib_tzdb * | tzdb | ) |
Frees up the resources as created through 'timelib_zoneinfo'.
This function must be used to free up all the resources that have been allocated while calling 'timelib_zoneinfo'.
1.13.2