VxWorks Reference Manual : Libraries
ansiTime - ANSI time documentation
asctime( ) - convert broken-down time into a string (ANSI)
asctime_r( ) - convert broken-down time into a string (POSIX)
clock( ) - determine the processor time in use (ANSI)
ctime( ) - convert time in seconds into a string (ANSI)
ctime_r( ) - convert time in seconds into a string (POSIX)
difftime( ) - compute the difference between two calendar times (ANSI)
gmtime( ) - convert calendar time into UTC broken-down time (ANSI)
gmtime_r( ) - convert calendar time into broken-down time (POSIX)
localtime( ) - convert calendar time into broken-down time (ANSI)
localtime_r( ) - convert calendar time into broken-down time (POSIX)
mktime( ) - convert broken-down time into calendar time (ANSI)
strftime( ) - convert broken-down time into a formatted string (ANSI)
time( ) - determine the current calendar time (ANSI)
The header time.h defines two macros and declares four types and several functions for manipulating time. Many functions deal with a calendar time that represents the current date (according to the Gregorian calendar) and time. Some functions deal with local time, which is the calendar time expressed for some specific time zone, and with Daylight Saving Time, which is a temporary change in the algorithm for determining local time. The local time zone and Daylight Saving Time are implementation-defined.
The macros defined are NULL and:
- CLOCKS_PER_SEC
- the number of ticks per second.
The types declared are size_t and:
- clock_t, time_t
- arithmetic types capable of representing times.
- struct tm
- holds the components of a calendar time in what is known as "broken-down time." The structure contains at least the following members, in any order. The semantics of the members and their normal ranges are expressed in the comments.
The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available.
int tm_sec; seconds after the minute - [0, 59] int tm_min; minutes after the hour - [0, 59] int tm_hour; hours after midnight - [0, 23] int tm_mday; day of the month - [1, 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 Saving Time flag If the environment variable TIMEZONE is set, the information is retrieved from this variable, otherwise from the locale information. TIMEZONE is of the form:
name_of_zone:<(unused)>:time_in_minutes_from_UTC:daylight_start:daylight_end
To calculate local time, the value of time_in_minutes_from_UTC is subtracted from UTC; time_in_minutes_from_UTC must be positive.
Daylight information is expressed as mmddhh (month-day-hour), for example:
UTC::0:040102:100102
Where there is a pair of routines, such as div( ) and div_r( ), only the routine xxx_r( ) is reentrant. The xxx( ) routine is not reentrant.
time.h
ansiTime, ansiLocale, American National Standard X3.159-1989
asctime( ) - convert broken-down time into a string (ANSI)
char * asctime ( const struct tm * timeptr /* broken-down time */ )
This routine converts the broken-down time pointed to by timeptr into a string of the form:
SUN SEP 16 01:03:52 1973\n\0This routine is not reentrant. For a reentrant version, see asctime_r( ).
time.h
A pointer to the created string.
asctime_r( ) - convert broken-down time into a string (POSIX)
int asctime_r ( const struct tm * timeptr, /* broken-down time */ char * asctimeBuf, /* buffer to contain string */ size_t * buflen /* size of buffer */ )
This routine converts the broken-down time pointed to by timeptr into a string of the form:
SUN SEP 16 01:03:52 1973\n\0The string is copied to asctimeBuf.This routine is the POSIX re-entrant version of asctime( ).
time.h
The size of the created string.
clock( ) - determine the processor time in use (ANSI)
clock_t clock (void)
This routine returns the implementation's best approximation of the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by clock( ) should be divided by the value of the macro CLOCKS_PER_SEC. If the processor time used is not available or its value cannot be represented, clock( ) returns -1.
time.h
ERROR (-1).
ctime( ) - convert time in seconds into a string (ANSI)
char * ctime ( const time_t * timer /* calendar time in seconds */ )
This routine converts the calendar time pointed to by timer into local time in the form of a string. It is equivalent to:
asctime (localtime (timer));This routine is not reentrant. For a reentrant version, see ctime_r( ).
time.h
The pointer returned by asctime( ) with local broken-down time as the argument.
ansiTime, asctime( ), localtime( )
ctime_r( ) - convert time in seconds into a string (POSIX)
char * ctime_r ( const time_t * timer, /* calendar time in seconds */ char * asctimeBuf, /* buffer to contain the string */ size_t * buflen /* size of the buffer */ )
This routine converts the calendar time pointed to by timer into local time in the form of a string. It is equivalent to:
asctime (localtime (timer));This routine is the POSIX re-entrant version of ctime( ).
time.h
The pointer returned by asctime( ) with local broken-down time as the argument.
ansiTime, asctime( ), localtime( )
difftime( ) - compute the difference between two calendar times (ANSI)
double difftime ( time_t time1, /* later time, in seconds */ time_t time0 /* earlier time, in seconds */ )
This routine computes the difference between two calendar times: time1 - time0.
time.h
The time difference in seconds, expressed as a double.
gmtime( ) - convert calendar time into UTC broken-down time (ANSI)
struct tm *gmtime ( const time_t * timer /* calendar time in seconds */ )
This routine converts the calendar time pointed to by timer into broken-down time, expressed as Coordinated Universal Time (UTC).
This routine is not reentrant. For a reentrant version, see gmtime_r( ).
time.h
A pointer to a broken-down time structure (tm), or a null pointer if UTC is not available.
gmtime_r( ) - convert calendar time into broken-down time (POSIX)
int gmtime_r ( const time_t * timer, /* calendar time in seconds */ struct tm * timeBuffer /* buffer for broken down time */ )
This routine converts the calendar time pointed to by timer into broken-down time, expressed as Coordinated Universal Time (UTC). The broken-down time is stored in timeBuffer.
This routine is the POSIX re-entrant version of gmtime( ).
time.h
OK.
localtime( ) - convert calendar time into broken-down time (ANSI)
struct tm *localtime ( const time_t * timer /* calendar time in seconds */ )
This routine converts the calendar time pointed to by timer into broken-down time, expressed as local time.
This routine is not reentrant. For a reentrant version, see localtime_r( ).
time.h
A pointer to a tm structure containing the local broken-down time.
localtime_r( ) - convert calendar time into broken-down time (POSIX)
int localtime_r ( const time_t * timer, /* calendar time in seconds */ struct tm * timeBuffer /* buffer for the broken-down time */ )
This routine converts the calendar time pointed to by timer into broken-down time, expressed as local time. The broken-down time is stored in timeBuffer.
This routine is the POSIX re-entrant version of localtime( ).
time.h
OK.
mktime( ) - convert broken-down time into calendar time (ANSI)
time_t mktime ( struct tm * timeptr /* pointer to broken-down structure */ )
This routine converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by the time( ) function. The original values of the tm_wday and tm_yday components of the tm structure are ignored, and the original values of the other components are not restricted to the ranges indicated in time.h. On successful completion, the values of tm_wday and tm_yday are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated in time.h; the final value of tm_mday is not set until tm_mon and tm_year are determined.
time.h
The calendar time in seconds, or ERROR (-1) if calendar time cannot be calculated.
strftime( ) - convert broken-down time into a formatted string (ANSI)
size_t strftime ( char * s, /* string array */ size_t n, /* maximum size of array */ const char * format, /* format of output string */ const struct tm * tptr /* broken-down time */ )
This routine formats the broken-down time in tptr based on the conversion specified in the string format, and places the result in the string s.
The format is a multibyte character sequence, beginning and ending in its initial state. The format string consists of zero or more conversion specifiers and ordinary multibyte characters. A conversion specifier consists of a % character followed by a character that determines the behavior of the conversion. All ordinary multibyte characters (including the terminating NULL character) are copied unchanged to the array. If copying takes place between objects that overlap, the behavior is undefined. No more than n characters are placed into the array.
Each conversion specifier is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the LC_TIME category of the current locale and by the values contained in the structure pointed to by tptr.
- %a
- the locale's abbreviated weekday name.
- %A
- the locale's full weekday name.
- %b
- the locale's abbreviated month name.
- %B
- the locale's full month name.
- %c
- the locale's appropriate date and time representation.
- %d
- the day of the month as 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 decimal number (001-366).
- %m
- the month as a decimal number (01-12).
- %M
- the minute as a decimal number (00-59).
- %P
- the locale's equivalent of the AM/PM designations associated with a 12-hour clock.
- %S
- the second as a decimal number (00-59).
- %U
- the week number of the year (first Sunday as the first day of week 1) as a decimal number (00-53).
- %w
- the weekday as a decimal number (0-6), where Sunday is 0.
- %W
- the week number of the year (the first Monday as the first day of week 1) as a decimal number (00-53).
- %x
- the locale's appropriate date representation.
- %X
- the locale's appropriate 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 abbreviation, or by no characters if no time zone is determinable.
- %%
- %.
For any other conversion specifier, the behavior is undefined.
time.h
The number of characters in s, not including the terminating null character -- or zero if the number of characters in s, including the null character, is more than n (in which case the contents of s are indeterminate).
time( ) - determine the current calendar time (ANSI)
time_t time ( time_t * timer /* calendar time in seconds */ )
This routine returns the implementation's best approximation of current calendar time in seconds. If timer is non-NULL, the return value is also copied to the location timer points to.
time.h
The current calendar time in seconds, or ERROR (-1) if the calendar time is not available.