Node:Time Functions, Next:Bitwise Functions, Previous:I/O Functions, Up:Built-in
gawk's Timestamp Functionsawk programs are commonly used to process log files
containing timestamp information, indicating when a
particular log record was written. Many programs log their timestamp
in the form returned by the time system call, which is the
number of seconds since a particular epoch. On POSIX-compliant systems,
it is the number of seconds since
1970-01-01 00:00:00 UTC, not counting leap seconds.1
All known POSIX-compliant systems support timestamps from 0 through
2^31 - 1, which is sufficient to represent times through
2038-01-19 03:14:07 UTC. Many systems support a wider range of timestamps,
including negative timestamps that represent times before the
epoch.
In order to make it easier to process such log files and to produce
useful reports, gawk provides the following functions for
working with timestamps. They are gawk extensions; they are
not specified in the POSIX standard, nor are they in any other known
version of awk.2
Optional parameters are enclosed in square brackets ([ ]):
systime()
mktime(datespec)
systime. It is similar to the function of the
same name in ISO C. The argument, datespec, is a string of the form
"YYYY MM DD HH MM SS [DST]".
The string consists of six or seven numbers representing, respectively,
the full year including century, the month from 1 to 12, the day of the month
from 1 to 31, the hour of the day from 0 to 23, the minute from 0 to
59, the second from 0 to 60,3
and an optional daylight-savings flag.
The values of these numbers need not be within the ranges specified;
for example, an hour of -1 means 1 hour before midnight.
The origin-zero Gregorian calendar is assumed, with year 0 preceding
year 1 and year -1 preceding year 0.
The time is assumed to be in the local timezone.
If the daylight-savings flag is positive, the time is assumed to be
daylight savings time; if zero, the time is assumed to be standard
time; and if negative (the default), mktime attempts to determine
whether daylight savings time is in effect for the specified time.
If datespec does not contain enough elements or if the resulting time
is out of range, mktime returns -1.
strftime([format [, timestamp]])
systime function. If no timestamp argument is supplied,
gawk uses the current time of day as the timestamp.
If no format argument is supplied, strftime uses
"%a %b %d %H:%M:%S %Z %Y". This format string produces
output that is (almost) equivalent to that of the date utility.
(Versions of gawk prior to 3.0 require the format argument.)
The systime function allows you to compare a timestamp from a
log file with the current time of day. In particular, it is easy to
determine how long ago a particular record was logged. It also allows
you to produce log records using the "seconds since the epoch" format.
The mktime function allows you to convert a textual representation
of a date and time into a timestamp. This makes it easy to do before/after
comparisons of dates and times, particularly when dealing with date and
time data coming from an external source, such as a log file.
The strftime function allows you to easily turn a timestamp
into human-readable information. It is similar in nature to the sprintf
function
(see String Manipulation Functions),
in that it copies nonformat specification characters verbatim to the
returned string, while substituting date and time values for format
specifications in the format string.
strftime is guaranteed by the 1999 ISO C standard4
to support the following date format specifications:
%a
%A
%b
%B
%c
%A %B %d %T %Y in the "C" locale.)
%C
%d
%D
%m/%d/%y.
%e
%F
%Y-%m-%d.
This is the ISO 8601 date format.
%g
%G
%h
%b.
%H
%I
%j
%m
%M
%n
%p
%r
%I:%M:%S %p in the "C" locale.)
%R
%H:%M.
%S
%t
%T
%H:%M:%S.
%u
%U
%V
%w
%W
%x
%A %B %d %Y in the "C" locale.)
%X
%T in the "C" locale.)
%y
%Y
%z
%Z
%Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH
%OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy
%c, %C,
and so on).5
(These facilitate compliance with the POSIX date utility.)
%%
%.
If a conversion specifier is not one of the above, the behavior is undefined.6
Informally, a locale is the geographic place in which a program
is meant to run. For example, a common way to abbreviate the date
September 4, 1991 in the United States is "9/4/91."
In many countries in Europe, however, it is abbreviated "4.9.91."
Thus, the %x specification in a "US" locale might produce
9/4/91, while in a "EUROPE" locale, it might produce
4.9.91. The ISO C standard defines a default "C"
locale, which is an environment that is typical of what most C programmers
are used to.
A public-domain C version of strftime is supplied with gawk
for systems that are not yet fully standards-compliant.
It supports all of the just listed format specifications.
If that version is
used to compile gawk (see Installing gawk),
then the following additional format specifications are available:
%k
%l
%N
%C.
%o
%y.
%s
%v
20-JUN-1991).
Additionally, the alternate representations are recognized but their normal representations are used.
This example is an awk implementation of the POSIX
date utility. Normally, the date utility prints the
current date and time of day in a well-known format. However, if you
provide an argument to it that begins with a +, date
copies nonformat specifier characters to the standard output and
interprets the current time according to the format specifiers in
the string. For example:
$ date '+Today is %A, %B %d, %Y.' -| Today is Thursday, September 14, 2000.
Here is the gawk version of the date utility.
It has a shell "wrapper" to handle the -u option,
which requires that date run as if the time zone
is set to UTC:
#! /bin/sh
#
# date --- approximate the P1003.2 'date' command
case $1 in
-u) TZ=UTC0 # use UTC
export TZ
shift ;;
esac
gawk 'BEGIN {
format = "%a %b %d %H:%M:%S %Z %Y"
exitval = 0
if (ARGC > 2)
exitval = 1
else if (ARGC == 2) {
format = ARGV[1]
if (format ~ /^\+/)
format = substr(format, 2) # remove leading +
}
print strftime(format)
exit exitval
}' "$@"
See Glossary, especially the entries ``Epoch'' and ``UTC.''
The GNU date utility can
also do many of the things described here. Its use may be preferable
for simple time-related operations in shell scripts.
Occasionally there are minutes in a year with a leap second, which is why the seconds can go up to 60.
As this
is a recent standard, not every system's strftime necessarily
supports all of the conversions listed here.
If you don't understand any of this, don't worry about
it; these facilities are meant to make it easier to ``internationalize''
programs.
Other internationalization features are described in
Internationalization with gawk.
This is because ISO C leaves the
behavior of the C version of strftime undefined and gawk
uses the system's version of strftime if it's there.
Typically, the conversion specifier either does not appear in the
returned string or appears literally.