svn commit: r334501 - head/usr.bin/touch

[Conrad Meyer]

Author: cem
Date: Fri Jun  1 22:34:59 2018
New Revision: 334501
URL: https://svnweb.freebsd.org/changeset/base/334501

Log:
  touch.1: Update to conform to POSIX 2004
  
  POSIX borrowed the "double leap second" bug from C89.  Double leap seconds can
  never happen.  This mistake was present in at least POSIX 1997 and fixed by
  POSIX 2004.  I can't find a copy of 2001 online to determine if the bug was
  present in that revision.
  
  While here, remove duplicate language between -d and -t.  A few other minor
  enhancements and an igor (lint) bugfix.
  
  Further reading:
  
  2018 POSIX (documents -d):
  http://pubs.opengroup.org/onlinepubs/9699919799/utilities/touch.html
  
  2004 POSIX (documents SS from 0-60):
  http://pubs.opengroup.org/onlinepubs/009695399/utilities/touch.html
  
  1997 POSIX/SUSv2 (historical interest, 0-61):
  http://pubs.opengroup.org/onlinepubs/007908799/xcu/touch.html
  
  More on this subject (start at "Unix system time and the POSIX standard")
  https://www.ucolick.org/~sla/leapsecs/onlinebib.html
  
  And: https://marc.info/?l=openbsd-tech&m=92682843416159&w=2
  
  Reported by:	Vishal Sahu <vsahu AT isilon.com>
  Sponsored by:	Dell EMC Isilon

Modified:
  head/usr.bin/touch/touch.1

Modified: head/usr.bin/touch/touch.1
==============================================================================
--- head/usr.bin/touch/touch.1	Fri Jun  1 22:09:27 2018	(r334500)
+++ head/usr.bin/touch/touch.1	Fri Jun  1 22:34:59 2018	(r334501)
@@ -31,7 +31,7 @@
 .\"     @(#)touch.1	8.3 (Berkeley) 4/28/95
 .\" $FreeBSD$
 .\"
-.Dd March 8, 2015
+.Dd June 1, 2018
 .Dt TOUCH 1
 .Os
 .Sh NAME
@@ -53,7 +53,8 @@ If any file does not exist, it is created with default
 .Pp
 By default,
 .Nm
-changes both modification and access times.  The
+changes both modification and access times.
+The
 .Fl a
 and
 .Fl m
@@ -113,39 +114,36 @@ The
 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
+Change the access and modification times to the specified date 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.
+At least four decimal digits representing the year.
+.It Ar MM , Ar DD , Ar hh , Ar mm , Ar SS
+As with
+.Fl t
+time.
 .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.
+or a space is the time designator.
 .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.
+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.
+Local time is affected by the value of the
+.Ev TZ
+environment variable.
 .El
 .It Fl h
 If the file is a symbolic link, change the times of the link
@@ -196,7 +194,7 @@ 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.
+The second of the minute, from 00 to 60.
 .El
 .Pp
 If the