Draft 2002-06-13

<ctime>

The <ctime> header is a wrapper for the C standard <time.h> header, which declares types and functions for working with dates and times.

asctime function

Convert a time to a string

char* asctime(const tm* tmptr)

The asctime function formats a time as a character string. It returns a pointer to a static buffer that is overwritten with each call.

The returned value has the format "Ddd Mmm DD HH:MM:SS YYYY\n", followed by a terminating null character. Thus, the result always has length 25. The day of the week (Ddd) and month name (Mmm) are not localized. The day of the month (DD) always takes up the same number of characters, using a leading space if necessary. The hours (HH), minutes (MM), and seconds (SS) use a leading zero if necessary.

See Also

ctime function, gmtime function, localtime function

clock function

Get the processor time

clock_t clock()

The clock function returns the amount of processor time used since an implementation-defined start time. The time is returned in implementation-defined units, where there are CLOCKS_PER_SEC units per second.

The value returned by the clock function is not useful by itself, but is intended to be used by comparing with the value returned from an earlier call to clock. For example, the first statement in the main function might be a call to clock; the difference between subsequent calls and the original call tell you how much time has elapsed since the program started.

If the environment cannot provide the processor time, static_cast<clock_t>(-1) is returned.

See Also

clock_t type, CLOCKS_PER_SEC macro, time function

clock_t type

Represent processor time

typedef ... clock_t

The clock_t type is an arithmetic type returned by the clock function.

See Also

clock function

CLOCKS_PER_SEC macro

Processor time resolution

int CLOCKS_PER_SEC

The CLOCKS_PER_SEC macro returns the number of clock ticks per second.

See Also

clock function

ctime function

Convert a time to a string

char* ctime(const time_t* timeptr)

The ctime function converts the calendar time pointed to by timeptr to local time, and formats the time as a string. It is equivalent to

std::asctime(std::localtime(timeptr));

See Also

asctime function, localtime function

difftime function

Compute the difference between two times

double difftime(time_t t1, time_t t2);

The difftime function computes the difference between two times: t1 - t2. The return value is in seconds.

See Also

time function, time_t type

gmtime function

Extract parts of a UTC time

tm* gmtime(const time_t* timeptr)

The gmtime function expands the calendar time pointed to by timeptr into a static tm object, using Coordinated Universal Time (UTC). It returns a pointer to the static object. Subsequent calls to gmtime overwrite the object.

If UTC is not available (for example, the host operating system does not provide the time zone offset), NULL is returned.

See Also

localtime function, tm struct

localtime function

Get the parts of a local time

tm* localtime(const time_t* timeptr)

The localtime function expands the calendar time pointed to by timeptr into a static tm object, using local time. It returns a pointer to the static object. Subsequent calls to localtime overwrite the object.

See Also

gmtime function, tm struct

mktime function

Make a time from parts

time_t mktime(tm* tmptr)

The mktime function makes a time_t time by assembling the parts in a tm object, interpreted as local time. The tm_wday and tm_yday members are ignored, and other fields are permitted to be outside their normal ranges.

If the conversion is successful, the corresponding time is returned, and the tm_wday and tm_yday members are set, and the other fields are changed if necessary to reflect their normal ranges.

If the time cannot be represented as a time_t value, static_cast<time_t>(-1) is returned.

See Also

localtime function, time_t type, tm struct

NULL macro

NULL pointer

#define NULL 0

The NULL macro expands to the integer 0, which represents a null pointer.

See Also

NULL in <cstddef>

size_t type

Size type

typedef ... size_t

The size_t type is the type of the result of the sizeof operator. It is an unsigned integral type. The exact type is implementation-defined.

See Also

size_t in <cstddef>

strftime function

Format a time as a string

size_t strftime(char* str, size_t n, const char* fmt,
                const tm* tmptr)

The strftime function formats a tm object as a string. Up to n bytes are stored in str, including a terminating null character. The return value is the number of characters actually stored, not counting the final null character. If the formatted result requires more than n characters, the return value is zero.

Characters from format are copied to str, except for conversion specifiers, which start with a percent sign (%), followed by one of the letters shown in Table 13-6. The LC_TIME category in the current locale dictates the text that is copied to str for each conversion specifier.

Table 13-6: Conversion specifiers for strftime
Specifier Description
a Abbreviated weekday name
A Full weekday name
b Abbreviated month name
B Full month name
C Complete date and time
D Day of the month (01-31)
H Hour (00-23), 24-hour clock
I Hour (01-12), 12-hour clock
j Day of the year (001-366)
m Month (01-12)
M Minutes (00-59)
P AM/PM designation for use with a 12-hour clock
S Second (00-61), up to 2 leap seconds
U Week number (00-53), week 1 starts with the first Sunday
w Weekday (0-6), Sunday is day 0
W Week number (00-53), week 1 starts with first Monday
x Date
X Time
y Year in century (00-99)
Y Year
Z Time zone name or abbreviation, or empty string if time zone is unknown
% Literal %

See Also

asctime function, ctime function, tm struct

time function

Get the current date and time

time_t time(time_t *timeptr)

The time function returns the current date and time in an unspecified format. If the host environment cannot provide the calendar time, static_cast<time_t>(-1) is returned.

If timeptr is not NULL, the return value is also stored in *timeptr.

See Also

clock function, time_t type

tm struct

Represent the parts of a date and time

struct tm {
  int tm_sec;   /* seconds: 0-61 */
  int tm_min;   /* minutes: 0-60 */
  int tm_hour;  /* hours:   0-24 */
  int tm_mday;  /* day of month: 1-31 */
  int tm_mon;   /* month: 1-12 */
  int tm_year;  /* years since 1900 */
  int tm_wday;  /* days since Sunday: 0-6 */
  int tm_yday;  /* days since January 1: 0-365 */
  int tm_isdst; /* Daylight Savings Time */
}

The tm structure stores parts of a date and time. The values returned by localtime and gmtime will always be in the ranges shown above. (Note that two extra leap seconds are allowed for tm_sec.)

The tm_isdst member is positive when Daylight Savings Time is in effect, zero when it is not in effect, or negative if it is unknown.

The order of the members is implementation-defined. An implementation can have additional members.

See Also

gmtime function, localtime function, mktime function