Date and Time: time.h

I l @ ve RuBoard

Date and Time: time.h

The time.h header file defines two macros. The first, also defined in many other header files, is NULL , representing the null pointer. The second macro is CLOCKS_PER_SEC ; dividing the value returned by clock() by this macro yields time in seconds.

The header file defines the types listed in Table F.17.

Table  F.17. Types defined in time.h .

Type	Description
size_t	The integer type returned by the sizeof operator.
clock_t	An arithmetic type suitable to represent time.
time_t	An arithmetic type suitable to represent time.
struct tm	A structure type for holding components of calendar time.

The components of the calendar type are referred to as broken-down time . Table F.18 lists the required members of a struct tm structure.

Table  F.18. Members of a struct tm structure.

Member	Description
int tm_sec	Seconds after the minute (0 “61)
int tm_min	Minutes after the hour (0 “59)
int tm_hour	Hours after midnight (0 “23)
int tm_mday	Day of the month (0 “31)
int tm_mon	Months since January (0 “11)
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 flag (greater than zero value means DST is in effect; zero means not in effect; negative means information not available)

The term calendar time represents the current date and time; for example, it could be the number of seconds elapsed since the first second of 1900. The term local time is the calendar time expressed for a local time zone. Table F.19 lists the time functions.

Table  F.19. Time functions.

Prototype	Description
clock_t clock(void);	Returns the implementation's best approximation to the processor time elapsed since the program was invoked; divide by CLOCKS_PER_SEC to get the time in seconds; returns (clock_t)(-1) if the time is not available or representable.
double difftime (time_t t1, time_t t0);	Calculates the difference ( t1 - t0 ) between two calendar times, expresses the result in seconds, and returns the result.
time_t mktime (struct tm *tmptr);	Converts the broken-down time in the structure pointed to by tmptr into a calendar time; having the same encoding used by the time() function, the structure is altered in that out-of-range values are adjusted (for example, 2 minutes, 100 seconds becomes 3 minutes, 40 seconds) and tm_wday and tm_yday are set to the values implied by the other members; returns (time_t)(-1) if the calendar time cannot be represented; otherwise , returns the calendar time in time_t format.
time_t time(time_t *ptm)	Returns the current calendar time and also places it in the location pointed to by ptm , providing ptm is not NULL ; returns (time_t)(-1) if the calendar time is not available.
char * asctime (const struct tm *tmpt);	Converts the broken-down time in the structure pointed to by tmpt into a string of the form Thu Feb 26 13:14:33 1998\n\0 and returns a pointer to that string.
char * ctime (const time_t *ptm); Wed Aug 11 10:48:24 1999\n\0	Converts the calendar time pointed to by ptm into a string of the form and returns a pointer to that string.
struct tm * gmtime (const time_t *ptm);	Converts the calendar time pointed to by ptm into a broken-down time, expressed as Coordinated Universal Time (UCT), and returns a pointer to a structure holding that information; returns NULL if UTC is not available.
struct tm *localtime(const time_t *ptm);	Converts the calendar time pointed to by ptm into a broken-down time, expressed as local time; stores a tm structure and returns a pointer to that structure.
size_t strftime(char *s, size_t max, const char *fmt, const struct tm *tmpt);	Copies string fmt to string s , replacing format specifiers (see Table F.20) in fmt with appropriate data derived from the contents of the broken-down time structure pointed to by tmpt ; no more than max characters are placed into s ; the function returns the number of characters placed (excluding the null character); if the resulting string (including null character) is larger than max characters, the function returns and the contents of s are indeterminate.

Table F.20 shows the format specifiers used by the strftime() function. Many replacement values, such as month names , depend on the current locale.

Table  F.20. Format specifiers used by the strftime() function.

Format Specifier	Replaced By
%a	Locale's abbreviated weekday name
%A	Locale's full weekday name
%b	Locale's abbreviated month name
%B	Locale's full month name
%c	Locale's appropriate date and time designation
%d	Day of the month as a decimal number (01 “31)
%H	The hour (24-hour clock) as a decimal number (00 “23)
%I	The hour (12-hour clock) as a decimal number (01 “12)
%j	The day of the year as a decimal number (001 “366)
%m	The month as a decimal number (01 “12)
%M	The minute as a decimal number (00 “59)
%p	Locale's equivalent of AM/PM for 12-hour clock
%S	The second as a decimal number (00 “61)
%U	Week number of the year, counting Sunday as the first day of week 1 (00 “53)
%w	Weekday as a decimal, beginning with Sunday (0 “6)
%W	Week number of the year, counting Monday as the first day of week 1 (00 “53)
%x	The locale's date representation
%X	The locale's time representation
%y	The year without century as a decimal number (00 “99)
%Y	The year with century as a decimal number
%Z	The time zone name or by no characters if the information is not available
%%	% (that is, the percent sign)

I l @ ve RuBoard