touch: Add the -d option from POSIX.1-2008.

This is much like -t but with a different format which is ISO8601-like and
allows fractions of a second.

The precision is limited to microseconds because of utimes() and friends,
even though stat() returns nanoseconds.

MFC after:	10 days

1 files changed, 40 insertions, 2 deletions

diff --git a/usr.bin/touch/touch.1 b/usr.bin/touch/touch.1
index 87789ec..6201b28 100644
--- a/usr.bin/touch/touch.1
+++ b/usr.bin/touch/touch.1
@@ -31,7 +31,7 @@
 .\"     @(#)touch.1	8.3 (Berkeley) 4/28/95
 .\" $FreeBSD$
 .\"
-.Dd February 4, 2012
+.Dd June 10, 2012
 .Dt TOUCH 1
 .Os
 .Sh NAME
@@ -43,6 +43,7 @@
 .Op Fl achm
 .Op Fl r Ar file
 .Op Fl t Ar [[CC]YY]MMDDhhmm[.SS]
+.Op Fl d Ar YYYY-MM-DDThh:mm:SS[.frac][tz]
 .Ar
 .Sh DESCRIPTION
 The
@@ -61,8 +62,10 @@ individually.
 Selecting both is equivalent to the default.
 By default, the timestamps are set to the current time.
 The
+.Fl d
+and
 .Fl t
-flag explicitly specifies a different time, and the
+flags explicitly specify a different time, and the
 .Fl r
 flag specifies to set the times those of the specified file.
 The
@@ -109,6 +112,41 @@ The
 .Nm
 utility does not treat this as an error.
 No error messages are displayed and the exit value is not affected.
+.It Fl d
+Change the access and modification times to the specified time instead
+of the current time of day.
+The argument is of the form
+.Dq YYYY-MM-DDThh:mm:SS[.frac][tz]
+where the letters represent the following:
+.Bl -tag -width Ds -compact -offset indent
+.It Ar YYYY
+The year.
+.It Ar MM
+The month of the year, from 01 to 12.
+.It Ar DD
+The day of the month, from 01 to 31.
+.It Ar T
+The letter
+.Li T
+or a space.
+.It Ar hh
+The hour of the day, from 00 to 23.
+.It Ar mm
+The minute of the hour, from 00 to 59.
+.It Ar SS
+The second of the minute, from 00 to 61.
+.It Ar .frac
+An optional fraction,
+consisting of a period or a comma followed by one or more digits.
+The number of significant digits depends on the kernel configuration and
+the filesystem, and may be zero.
+.It Ar tz
+An optional letter
+.Li Z
+indicating the time is in
+.Tn UTC .
+Otherwise, the time is assumed to be in local time.
+.El
 .It Fl h
 If the file is a symbolic link, change the times of the link
 itself rather than the file that the link points to.