NAME

mktime - manipulate time and date values

SYNOPSIS

mktime [-f] [-F format] [-H hours] [-M minutes] [-S seconds] [-T hh:mm[:ss]] [-z] [-y year] [-m month] [-d month_day] [-D [yyyy-]mm-dd] [-t time_t]

DESCRIPTION

The mktime command is a command-line interface to the mktime(3) function from Standard C, and can be used to manipulate times and dates in shell scripts. It has a few enhancements over mktime(3), and a few minor differences which are detailed below.

The mktime command takes a base date and time (by default the current date and time), modifies it according to its options, and displays the result. Options for specifying the date and time can either specify an adjustment to the base value or an absolute number. To specify an adjust ment, put an explicit sign on the value (eg. +1 or -5); to specify an absolute number, leave the value unsigned (eg. 7). See the EXAMPLES section below for details.

Normally, if the resulting time can not be represented (for example a time ``skipped'' during a change to day light savings time), mktime tries to adjust the result to a valid time, first by assuming that the time is not dur ing Daylight Savings Time (that is, it sets tm_isdst in the struct tm to 0), and if that fails, by assuming that it is (by setting tm_isdst to 1). The -f option alters this behaviour; see the EXAMPLES section. Since this behaviour is not clearly defined by the C Standard, it is possible that some implementations may fail despite these attempts, or that different implementations will give dif ferent results, so if you are concerned, you should set the time to one that is not likely to be affected by a time change, such as midnight or noo.

Most options to mktime are processed in order, and so adjustments are cumulative. The exception is -t which, since it is setting the base time, happens before other options.

OPTIONS

-H hours: Set/adjust the base time hour by hours.
-M minutes: Set/adjust the base time minute by minutes.
-S seconds: Set/adjust the base time seconds by seconds.
-T hh:mm[:ss]: Set the base time to hh:mm:ss [or hh:mm:00]. This is almost equivalent to -H hh -M mm -S ss except that it cannot be used to adjust time, only set it. Although explicit signs will not allow adjusting the time, each field is not constrained to two dig its in the normal range of values, so 0:90:0 is allowed (and represents the time 90 minutes into that day).
-z: Set the time to zeroes. Equivalent to -T 00:00:00. Useful when you only care about the date, not the time.
-y year: Set/adjust the base date year by year. A value of year less than 1900 is taken to be a number years since 1900 (as with mktime(3)); a value of year greater than or or equal to 1900 is taken as is, ie. -y 97 and -y 1997 both specify the year 1997.
-m month: Set/adjust the base date month by month. NOTE: January is considered month 1.
-d month_day: Set/adjust the base date day of the month by month_day.
-D [yyyy-]mm-dd: Set the base date to [yyyy-]mm-dd. This is almost equivalent to -y yyyy -m mm -d dd except that it cannot be used to adjust time, only set it. Although explicit signs will not allow adjusting the date, each field is not constrained to a normal range of values, so 97-1-365 is allowed (and repre sents the 365th day of 1997).
-t time_t: Use time_t as the base time, instead of the current time.
-F format: A format string to display the resulting time. This format string is as for the Standard C func tion strftime(3), with the additional conversion specifer %t. This specifier is replaced with a representation of the time as a C time_t. The default format gives the date and time in a format suggested by ISO 8601:1988: YYYY-MM-DD hh:mm:ss.
-f: Fail if the specified date/time is not valid. Without this option mktime attempts to adjust to a valid time, as described above.

RETURNS

If mktime succeeds, it prints the resulting time according to the given format (or the default format if none was supplied), and exits with status 0.

If mktime cannot represent the resulting time, it exits with status 1.

If mktime was invoked incorrectly, it exits with status 2.

If mktime encounters a runtime error, such as being unable to get the system time, or being unable to allocate memory for the output string, it exits with status 3. Note that this may indicate an invalid format, since strftime(3) does not distinguish between an invalid format and having insufficient space to store its result.

DIFFERENCES FROM mktime(3)

mktime's notion of adjusting versus setting values does not exist with mktime(3), where you always fill in the absolute values.

mktime(3) uses a zero-based month (ie. January is 0); mktime uses a one-based month because it is more ``natu ral'' and it matches the output with the %m format.

mktime(3) always uses years since 1900; mktime does not (see -y).

EXAMPLES

These examples assume the use of the Bourne shell, and the results assume the commands were run Wednesday May 14, 1997 at 22:30:00 PDT, using the American (and Canadian) rules for Daylight Savings Time changes. Shell prompts are shown as "$", and user input is shown like this.

# Display the current time in the default format
$ mktime
1997-05-14 22:30:00

# Display the date and time 4 hours from now
$ mktime -H +4
1997-05-15 02:30:00

# Display the date for the first of this month
$ mktime -F '%A %B %d, %Y' -d 1
Thursday May 01, 1997

# Display the day of the week and month two weeks ago
$ mktime -F '%A %d' -d -14
Wednesday 30

# Display the last day this month
$ mktime -m +1 -d 0
1997-05-31 22:30:00

# Display the 256th day of this year
$ mktime -m 1 -d 256 -F '%a %b %d'
Sat Sep 13

# Display the day 2 days before March 1, 1996 $ mktime -D
1996-03-01 -d -2 -F '%a %b %d'
Wed Feb 28

# Display the time 2:30AM on April 6, 1997 PDT
# (North American Pacific timezone).
# NOTE: this is an invalid time; use -f to catch the error
$ mktime -f -D 1997-04-06 -T 2:30
mktime: invalid time
# Now let mktime adjust to a valid value:
$ mktime -D 1997-04-06 -T 2:30
1997-04-06 03:30:00

# Display midnight January 1, 2000, as a time_t
$ mktime -F '%t' -z -D 2000-01-01
946713600

# Display one day before the previouse time_t result
$ mktime -d -1 -t 946713600
1999-12-31 00:00:00

Sometimes it may be necessary to use multiple mktime com mands to get the desired date, or other shell commands may be required:

# The third last day of last month
$ mktime -F '%a %b %d' -d -3 -t `mktime -F '%t' -d 1`
Mon Apr 28

# The date of next Friday (Friday is day 5)
$ wday=`mktime -F '%w'`
$ mktime -F '%a %b %d' -d +`expr $ 7 + 5 - $wday $ % 7`
Fri May 16