previous next contents
The Time Category

There are two representations of time commonly used in UNIX programs, time_t and struct tm.

time_t - data type representing the number of seconds since the epoch.

epoch - the time 00:00:00 Jan 1, 1970.

CUT - same as Coordinated Universal Time.

Coordinated Universal Time - the time at Greenwich England during the winter.

UTC - same as CUT.

Greenwich mean time - same as CUT.

tm - struct data type containing the current time.

localtime() - given a time_t argument, returns a tm struct. time() - returns a time_t representing the current time.

time string - NULL terminated string containing a printable version of the time.

asctime() - returns a time string in the C locale where the time is given by the struct tm argument.

ctime() - returns a time string in the C locale where the time is given by the time_t argument.

strftime(buf, size, fmt, tmptr) - loads a buffer at buf with a time string where the time is given by a struct tm pointer, tmptr, according to the format string at fmt. No more than size bytes of buf are loaded. strftime() may be used to obtain a time string in the current locale.

strftime() format string - NULL terminated multibyte string consisting of zero or more strftime() conversion specifiers and ordinary characters.

strftime() conversion specifier - a conversion specifier consisting of a % character, an optional field width and precision, and a conversion character that determines the conversion specification's behavior which is used to determine the placement and content of date or time information in a strftime() format string. One of the following: %a, %A, %b, %B, %c, %C, %d, %D, %E, %h, %H, %I, %j, %m, %M, %n, %N, %o, %p, %r, %R, %S, %t, %T, %U, %w, %W, %x, %X, %y, %Y, %Z, %%.

The format string for strftime() may be obtained by the call nl_langinfo(D_T_FMT).

strptime() - performs the reverse operation of strftime(). POSIX.1 specifies the behavior of time-related functions in relation to the TZ environment variable.

TZ - environment variable which specifies the time zone. There are two forms of TZ, standard TZ and implementation-defined TZ. An example of the most typical form of the TZ variable is "CST6CDT".

standard TZ - environment variable of the form std[+|-]offset[dst[offset][,startdate[/time],enddate[/time]]] where offset is of the form hh[:mm[:ss]] and hh may be a single digit. If no offset follows dst, summer time is assumed to be one hour ahead of standard time. std and dst must contain between 3 and TZNAME_MAX bytes. Only std is required. If dst is missing, no summer time applies to this locale. Any characters except :,-+NULL, may appear in these fields, but their meaning is unspecified. time has the same format as offset except that no leading sign shall be allowed. If no time is given, it is assumed to be 02:00:00. Three forms of the start(end)date will be permitted: Jn, n, and Mm.n.d.

Jn - form of start(end)date in standard TZ where Jn is the julian day n (1<=n<=365). Leap days shall not be counted.

n - form of start(end)date in standard TZ where n is a zero-based julian day (0<=n<=365). Leap days shall be counted, and it is possible to refer to February 29.

Mm.n.d - form of start(end)date in standard TZ where The dth day (0<=d<=6) of the week n of month m of the year where 1<=n<=5), 1<=m<=12, where week 5 means the last d day in month m which may occur in either the fourth or the fifth week. Week 1 is the first week in which the dth day occurs. Day zero is Sunday.

implementation-defined TZ - environment variable of the form :characters which allows time zone information to be handled in an implementation-defined manner.

The TZ environment variable allows such things as 1/2 hour time, double daylight time, and loar time to be handled correctly.

TZNAME_MAX - the maximum number of bytes permitted in a timezone name.

%a - strftime() conversion specifier replaced by the locale's abbreviated weekday name.

%A - strftime() conversion specifier replaced by the locale's full weekday name.

%b - strftime() conversion specifier replaced by the locale's abbreviated month name.

%B - strftime() conversion specifier replaced by the locale's full month name.

%c - strftime() conversion specifier replaced by the locale's appropriate date and time representation.

%C - strftime() conversion specifier replaced by the locale's long appropriate date and time representation.

%d - strftime() conversion specifier replaced by the day of the month as a decimal number [01,31].

%D - strftime() conversion specifier replaced by the date (%m/%d/%y).

%E - strftime() conversion specifier replaced by the locale's combined Emperor/Era name and year.

%h - strftime() conversion specifier replaced by the locale's abbreviated month name.

%H - strftime() conversion specifier replaced by the hour (24-hour clock) as a decimal number [00,23].

%I - strftime() conversion specifier replaced by the hour(12-hour clock) as a decimal number [01,12].

%j - strftime() conversion specifier replaced by the day of the year as a decimal number [001,366].

%m - strftime() conversion specifier replaced by the month as a decimal number [01,12].

%M - strftime() conversion specifier replaced by the minute as a decimal number [00,59].

%n - strftime() conversion specifier replaced by a newline character.

%N - strftime() conversion specifier replaced by the locale's Emperor/Era name.

%o - strftime() conversion specifier replaced by the locale's Emperor/Era year.

%p - strftime() conversion specifier replaced by the locale's equivalent of either AM or PM.

%r - strftime() conversion specifier replaced by the time in AM/PM notation according to British/US conventions (%I:%M:%S [AM|PM]).

%R - strftime() conversion specifier replaced by the time in 24 hour notation (%H:%M).

%S - strftime() conversion specifier replaced by the second as a decimal number [00,61].

%t - strftime() conversion specifier replaced by a tab character.

%T - strftime() conversion specifier replaced by the time (%H:%M:%S).

%U - strftime() conversion specifier replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].

%w - strftime() conversion specifier replaced by the weekday as a decimal number [0(Sunday),6].

%W - strftime() conversion specifier replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53].

%x - strftime() conversion specifier replaced by the locale's appropriate date representation.

%X - strftime() conversion specifier replaced by the locale's appropriate time representation.

%y - strftime() conversion specifier replaced by the year without century as a decimal number [00,99].

%Y - strftime() conversion specifier replaced by the year with century as a decimal number.

%Z - strftime() conversion specifier replaced by the timezone name, or by no characters if no timezone exists.

%% - strftime() conversion specifier replaced by %.

The %S strftime() conversion specifier supports the leap second and the double leap second.

field width - optional component of a strftime() conversion specifier of the form [-|0]w where w is a decimal digit strign specifying the minimum field width. By default, the value will be right justifieid with space padding on the left. If - is specified, it will be left justified with space padding on the right. If 0 is specified, it will be right justified and padded with zeros on the left.

precision specification - optional component of a strftime() conversion specifier of the form .p where p is a decimal digit string specifying the number of digits to appear for d, H, I, j, m, M, o, S, U, w, W, y and Y conversions, adn the maximum number of characters to be used from a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and % conversions.

strptime() format string - NULL terminated multibyte string consisting of zero or more strptime() conversion specifiers and ordinary characters.

strptime() conversion specifier - a conversion specifier consisting of a % character and a conversion character found in a strptime() format string which determines where date and time information will be located. One of the following: %a, %A, %b, %B, %c, %C, %d, %D, %E, %h, %H, %I, %j, %m, %M, %n, %N, %o, %p, %r, %R, %S, %t, %T, %U, %w, %W, %x, %X, %y, %Y, %Z, %%.

The strptime() conversion specifiers are identical to the strftime() conversion specifiers except in the behavior of a very few specifiers.

strptime() matches input names of days of week, etc, to locale-dependent names in order to load the tm struct. Case is ignored when matching date and time names. If the conversion fails, the contents of tm are undefined.

summer time - British term for Daylight Savings Time.

modified field descriptors - conversion specifiers defined by POSIX.2 for use by the date command. These conversion specifiers are formed by prepending either E or O to a select list of conversion specifiers.

abday - LC_TIME cultural data item or locale definition file keyword representing the abbreviated weekday names. Corresponds to the %a format specifier.

day - LC_TIME cultural data item or locale definition file keyword representing the weekday names beginning with Sunday. Corresponds to the %A format specifier.

abmon - LC_TIME cultural data item or locale definition file keyword representing the abbreviated month names. Corresponds to the %b format specifier.

mon - LC_TIME cultural data item or locale definition file keyword representing the month names beginning with January. Corresponds to the %B format specifier.

d_t_fmt - LC_TIME cultural data item or locale definition file keyword representing the appropriate date and time representation which may include any combination of characters and conversion specifiers. Corresponds to the %c format specifier.

d_fmt - LC_TIME cultural data item or locale definition file keyword representing the appropriate date representation which may include any combination of characters and conversion specifiers. Corresponds to the %x format specifier.

t_fmt - LC_TIME cultural data item or locale definition file keyword representing the appropriate time representation which may include any combination of characters and conversion specifiers. Corresponds to the %X format specifier.

am_pm - LC_TIME cultural data item or locale definition file keyword representing the appropriate equivalent of "AM" and "PM". Corresponds to the %p format specifier.

t_fmt_ampm - LC_TIME cultural data item or locale definition file keyword representing the appropriate time representation in the 12 hour clock format with am_pm. Corresponds to the %r format specifier.

era - LC_TIME cultural data item or locale definition file keyword representing alternate Eras. Corresponds to the %E field descriptor modifier. When used as a keyword, the format of the operand is unspecified, but shall support the definition of the %EC and %Ey field descriptors, and may also define the era_year format (%EY).

era_year - LC_TIME cultural data item or locale definition file keyword representing the format of the year in alternate Era format. Corresponds to the %EY format specifier.

era_d_fmt - LC_TIME cultural data item or locale definition file keyword representing the format of the date in alternate Era notation. Corresponds to the %Ex format specifier.

alt_digits - LC_TIME cultural data item or locale definition file keyword representing alternate symbols for digits. Corresponds to the %O field descriptor modifier. When used as a keyword, the operand shall consist of semicolon-separated strings. The first string shall be the alternate symbol corresponding with zero, and so on. Up to 100 alternate symbol strings can be specified.

The %O modifier indicates that the string corresponding to the value specified via the field descriptor shall be used instead of the value.

The %O modifier is primarily intended to provide for Kanji or Hindi digits in date formats.

It is implementation-defined whether era, era_year, era_d_fmt, or alt_digits are supported. If they are not supported, but present in a localedef source, they shall be ignored.


previous next contents