Previous Table of Contents Next


3.10.6.4. mktime

time_t mktime(struct tm *tp)

mktime attempts to compute the time_t value corresponding to the local date and time represented by the tm structure pointed to by tp. The date is determined by tm_mon and tm_mday; tm_wday and tm_yday are ignored on input. If tm_isdst is negative, mktime attempts to determine whether DST will or would have applied on the given date, and act accordingly; if tm_isdst is positive or zero, the caller is asserting that the given time does or does not have a DST offset applied, respectively. If any of tm_sec, tm_min, tm_hour, tm_mday, or tm_mon has a value outside the expected range, mktime normalizes them in the process of computing a date (and also adjusts their values in *tp). For example, 25:70 on January 32 is converted to 2:10 on February 2. Finally, appropriate values of tm_wday and tm_yday are set in *tp. The return value is the converted time_t value, or -1 if the conversion is impossible (e.g., the date represented by the tm structure is outside the range representable by a time_t).

mktime’s defined handling of non-normalized dates makes it useful for performing simple calendar calculations. For example, to add n days to a date, it is often sufficient to store the date in a tm structure, increment tm_mday by n, call mktime, and read the corrected date out of the tm structure.

3.10.6.5. difftime

double difftime(time_t t1, time_t t2)

difftime computes the difference between two time_t values and returns the result t1 - t2 as a number of seconds. It is useful for performing portable date calculations in spite of the implementation-defined encoding of time_t values.

3.10.6.6. clock

clock_t clock(void)

The clock function deals with yet a third representation of time, namely processor clock ticks, of potentially subsecond resolution. clock is supposed to return the number of processor ticks that have elapsed since the program began execution. The frequency of the clock ticks measured by clock is system dependent, but the macro CLOCKS_PER_SEC is defined such that a clock_t value, divided by CLOCKS_PER_SEC, yields the elapsed time in seconds. (Of course, it is also possible that the clock_t value, whatever its underlying type is, will have overflowed during the execution of a long-running program.)

3.10.6.7. strftime

size_t strftime(char *buf, size_t bufsize,
        const char *fmt, const struct tm *tp)

strftime performs flexible formatting of the date and time represented by the tm structure pointed to by tp, under control of the fmt string. Like printf, characters from the fmt string are copied through to the output, except for % characters, which request insertion of certain values. Like sprintf, the output is copied to a user-supplied character array pointed to by buf. Unlike sprintf, the size of this buffer is specified by the bufsize argument so that strftime can guarantee not to overflow it.

The format specifiers and their resulting output (and, where relevant, the corresponding member in struct tm) are as follow. The format specifiers must appear as shown; no printf-like flags or width specifiers are supported. Many of the output values are locale specific (see section 3.10.9).

%a The weekday name (from tm_wday) as a three- character abbreviation
%A The full weekday name (from tm_wday)
%b The month name (from tm_mon) as a three-character abbreviation
%B The full month name (from tm_mon)
%c A complete (implementation- and locale-specific) date and time representation
%d The day of the month (tm_mday)
%H The hour (tm_hour) on a 24-hour clock
%I The hour (from tm_hour) on a 12-hour clock
%j The day of the year (from tm_yday), 1-based
%m The month (from tm_mon), as a 1-based, two-digit number
%M The minute (tm_min)
%p An AM/PM string (from tm_hour)
%S The second (tm_sec)
%U The week number, where the first Sunday of the year begins week 1
%w The day of the week (tm_wday), as a number (0 = Sunday)
%W The week number, where the first Monday of the year begins week 1
%x A complete (implementation- and locale-specific) date representation
%X A complete (implementation- and locale-specific) time representation
%y The last two digits of the year (from tm_year)
%Y The year (from tm_year) as a four-digit number
%Z The time zone name, if available; otherwise nothing
%% A single % character

strftime returns the number of characters written to buf, or 0 if the given bufsize was too small to write the complete output (including the terminating \0).


Previous Table of Contents Next