Go to the first, previous, next, last section, table of contents.
A common use for @command{awk} programs is the processing of 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.(34)
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, @command{gawk} provides the following functions for working with timestamps. They are @command{gawk} extensions; they are not specified in the POSIX standard, nor are they in any other known version of @command{awk}.(35) utility can also do many of the things described here. It's use may be preferable for simple time-related operations in shell scripts.} Optional parameters are enclosed in square brackets ([ and ]):
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,(36)
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,
@command{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 @command{date} utility.
(Versions of @command{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 section String Manipulation Functions),
in that it copies non-format 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 standard(37)
to support the following date format specifications:
%a
%A
%b
%B
%c
"C" locale.)
%C
%d
%D
%e
%F
%g
%G
%h
%H
%I
%j
%m
%M
%n
%p
%r
"C" locale.)
%R
%S
%t
%T
%u
%U
%V
%w
%W
%x
"C" locale.)
%X
"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
%%
If a conversion specifier is not one of the above, the behavior is
undefined.(39)
uses the system's version of strftime if it's there.
Typically, the conversion specifier either does not appear in the
returned string or it appears literally.}
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 @command{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 @command{gawk} (@pxref{Installation, ,Installing @command{gawk}}),
then the following additional format specifications are available:
%k
%l
%N
%C.
%o
%y.
%s
%v
Additionally, the alternate representations are recognized but their normal representations are used.
This example is an @command{awk} implementation of the POSIX @command{date} utility. Normally, the @command{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 `+', @command{date} copies non-format 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 @command{gawk} version of the @command{date} utility. It has a shell "wrapper" to handle the @option{-u} option, which requires that @command{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
}' "$@"
Go to the first, previous, next, last section, table of contents.