6 * @time: pointer to a #glktimeval_t structure.
8 * The current Unix time is stored in the structure @time. (The argument may not
9 * be %NULL.) This is the number of seconds since the beginning of 1970 (UTC).
11 * The first two values in the structure should be considered a single
12 * <emphasis>signed</emphasis> 64-bit number. This allows the #glktimeval_t to
13 * store a reasonable range of values in the future and past. The @high_sec
14 * value will remain zero until sometime in 2106. If your computer is running in
15 * 1969, perhaps due to an unexpected solar flare, then @high_sec will be
18 * The third value in the structure represents a fraction of a second, in
19 * microseconds (from 0 to 999999). The resolution of the glk_current_time()
20 * call is platform-dependent; the @microsec value may not be updated
24 glk_current_time(glktimeval_t *time)
26 g_return_if_fail(time != NULL);
30 * glk_current_simple_time:
31 * @factor: Factor by which to divide the time value.
33 * If dealing with 64-bit values is awkward, you can also get the current time
34 * as a lower-resolution 32-bit value. This is simply the Unix time divided by
35 * the @factor argument (which must not be zero). For example, if factor is 60,
36 * the result will be the number of minutes since 1970 (rounded towards negative
37 * infinity). If factor is 1, you will get the Unix time directly, but the value
38 * will be truncated starting some time in 2038.
40 * Returns: Unix time divided by @factor, truncated to 32 bits.
43 glk_current_simple_time(glui32 factor)
45 g_return_val_if_fail(factor != 0, -1);
51 * glk_time_to_date_utc:
52 * @time: A #glktimeval_t structure as returned by glk_current_time().
53 * @date: An empty #glkdate_t structure to fill in.
55 * Convert the given timestamp (as returned by glk_current_time()) to a
56 * broken-out structure. This function returns a date and time in universal time
60 * The seconds value may be 60 because of a leap second.
64 glk_time_to_date_utc(glktimeval_t *time, glkdate_t *date)
66 g_return_if_fail(time != NULL);
67 g_return_if_fail(date != NULL);
71 * glk_time_to_date_local:
72 * @time: A #glktimeval_t structure as returned by glk_current_time().
73 * @date: An empty #glkdate_t structure to fill in.
75 * Does the same thing as glk_time_to_date_utc(), but this function returns
79 glk_time_to_date_local(glktimeval_t *time, glkdate_t *date)
81 g_return_if_fail(time != NULL);
82 g_return_if_fail(date != NULL);
86 * glk_simple_time_to_date_utc:
87 * @time: Timestamp as returned by glk_current_simple_time().
88 * @factor: Factor by which to multiply @time in order to get seconds.
89 * @date: An empty #glkdate_t structure to fill in.
91 * Convert the given timestamp (as returned by glk_current_simple_time()) to a
92 * broken-out structure in universal time. The @time argument is multiplied by
93 * @factor to produce a Unix timestamp.
95 * Since the resolution of glk_simple_time_to_date_utc() and
96 * glk_simple_time_to_date_local() is no better than seconds, they will return
97 * zero for the microseconds value.
100 glk_simple_time_to_date_utc(glsi32 time, glui32 factor, glkdate_t *date)
102 g_return_if_fail(factor != 0);
103 g_return_if_fail(date != NULL);
107 * glk_simple_time_to_date_local:
108 * @time: Timestamp as returned by glk_current_simple_time().
109 * @factor: Factor by which to multiply @time in order to get seconds.
110 * @date: An empty #glkdate_t structure to fill in.
112 * Does the same thing as glk_simple_time_to_date_utc(), but fills in the @date
113 * structure in local time.
116 glk_simple_time_to_date_local(glsi32 time, glui32 factor, glkdate_t *date)
118 g_return_if_fail(factor != 0);
119 g_return_if_fail(date != NULL);
123 * glk_date_to_time_utc:
124 * @date: A date in the form of a #glkdate_t structure.
125 * @time: An empty #glktimeval_t structure to fill in.
127 * Convert the broken-out structure (interpreted as universal time) to a
128 * timestamp. The weekday value in @date is ignored. The other values need not
129 * be in their normal ranges; they will be normalized.
131 * If the time cannot be represented by the platform's time library, this may
132 * return -1 for the seconds value. (I.e., the @high_sec and @low_sec fields
133 * both $FFFFFFFF. The microseconds field is undefined in this case.)
136 glk_date_to_time_utc(glkdate_t *date, glktimeval_t *time)
138 g_return_if_fail(date != NULL);
139 g_return_if_fail(time != NULL);
143 * glk_date_to_time_local:
144 * @date: A date in the form of a #glkdate_t structure.
145 * @time: An empty #glktimeval_t structure to fill in.
147 * Does the same thing as glk_date_to_time_utc(), but interprets the broken-out
148 * structure as local time.
150 * The glk_date_to_time_local() function may not be smart about Daylight Saving
153 * If implemented with the mktime() libc function, it should use the negative
154 * @tm_isdst flag to <quote>attempt to divine whether summer time is in
159 glk_date_to_time_local(glkdate_t *date, glktimeval_t *time)
161 g_return_if_fail(date != NULL);
162 g_return_if_fail(time != NULL);
166 * glk_date_to_simple_time_utc:
167 * @date: A date in the form of a #glkdate_t structure.
168 * @factor: Factor by which to divide the time value.
170 * Convert the broken-out structure (interpreted as universal time) to a
171 * timestamp divided by @factor. The weekday value in @date is ignored. The
172 * other values need not be in their normal ranges; they will be normalized.
174 * If the time cannot be represented by the platform's time library, this may
177 * Returns: a timestamp divided by @factor, and truncated to 32 bits, or -1 on
181 glk_date_to_simple_time_utc(glkdate_t *date, glui32 factor)
183 g_return_val_if_fail(date != NULL, -1);
184 g_return_val_if_fail(factor != 0, -1);
190 * glk_date_to_simple_time_local:
191 * @date: A date in the form of a #glkdate_t structure.
192 * @factor: Factor by which to divide the time value.
194 * Does the same thing as glk_date_to_simple_time_utc(), but interprets the
195 * broken-out structure as local time.
197 * Returns: a timestamp divided by @factor, and truncated to 32 bits, or -1 on
201 glk_date_to_simple_time_local(glkdate_t *date, glui32 factor)
203 g_return_val_if_fail(date != NULL, -1);
204 g_return_val_if_fail(factor != 0, -1);