coreutils: touch invocation

1 
1 13.4 ‘touch’: Change file timestamps
1 ====================================
1 
1 ‘touch’ changes the access and/or modification timestamps of the
1 specified files.  Synopsis:
1 
1      touch [OPTION]... FILE...
1 
1    Any FILE argument that does not exist is created empty, unless option
1 ‘--no-create’ (‘-c’) or ‘--no-dereference’ (‘-h’) was in effect.
1 
1    A FILE argument string of ‘-’ is handled specially and causes ‘touch’
1 to change the times of the file associated with standard output.
1 
1    By default, ‘touch’ sets file timestamps to the current time.
1 Because ‘touch’ acts on its operands left to right, the resulting
1 timestamps of earlier and later operands may disagree.
1 
1    When setting file timestamps to the current time, ‘touch’ can change
1 the timestamps for files that the user does not own but has write
1 permission for.  Otherwise, the user must own the files.  Some older
1 systems have a further restriction: the user must own the files unless
1 both the access and modification timestamps are being set to the current
1 time.
1 
1    The ‘touch’ command cannot set a file’s status change timestamp to a
1 user-specified value, and cannot change the file’s birth time (if
1 supported) at all.  Also, ‘touch’ has issues similar to those affecting
1 all programs that update file timestamps.  For example, ‘touch’ may set
1 a file’s timestamp to a value that differs slightly from the requested
1 time.  ⇒File timestamps.
1 
1    Timestamps assume the time zone rules specified by the ‘TZ’
1 environment variable, or by the system default rules if ‘TZ’ is not set.
1 ⇒Specifying the Time Zone with ‘TZ’ (libc)TZ Variable.  You can
1 avoid ambiguities during daylight saving transitions by using UTC
1 timestamps.
1 
11    The program accepts the following options.  Also see ⇒Common
 options.
1 
1 ‘-a’
1 ‘--time=atime’
1 ‘--time=access’
1 ‘--time=use’
1      Change the access timestamp only.  ⇒File timestamps.
1 
1 ‘-c’
1 ‘--no-create’
1      Do not warn about or create files that do not exist.
1 
1 ‘-d TIME’
1 ‘--date=TIME’
1      Use TIME instead of the current time.  It can contain month names,
1      time zones, ‘am’ and ‘pm’, ‘yesterday’, etc.  For example,
1      ‘--date="2004-02-27 14:19:13.489392193 +0530"’ specifies the
1      instant of time that is 489,392,193 nanoseconds after February 27,
1      2004 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes
1      east of UTC.  ⇒Date input formats.  File systems that do not
1      support high-resolution timestamps silently ignore any excess
1      precision here.
1 
1 ‘-f’
1      Ignored; for compatibility with BSD versions of ‘touch’.
1 
1 ‘-h’
1 ‘--no-dereference’
1      Attempt to change the timestamps of a symbolic link, rather than
1      what the link refers to.  When using this option, empty files are
1      not created, but option ‘-c’ must also be used to avoid warning
1      about files that do not exist.  Not all systems support changing
1      the timestamps of symlinks, since underlying system support for
1      this action was not required until POSIX 2008.  Also, on some
1      systems, the mere act of examining a symbolic link changes the
1      access timestamp, such that only changes to the modification
1      timestamp will persist long enough to be observable.  When coupled
1      with option ‘-r’, a reference timestamp is taken from a symbolic
1      link rather than the file it refers to.
1 
1 ‘-m’
1 ‘--time=mtime’
1 ‘--time=modify’
1      Change the modification timestamp only.
1 
1 ‘-r FILE’
1 ‘--reference=FILE’
1      Use the times of the reference FILE instead of the current time.
1      If this option is combined with the ‘--date=TIME’ (‘-d TIME’)
1      option, the reference FILE’s time is the origin for any relative
1      TIMEs given, but is otherwise ignored.  For example, ‘-r foo -d '-5
1      seconds'’ specifies a timestamp equal to five seconds before the
1      corresponding timestamp for ‘foo’.  If FILE is a symbolic link, the
1      reference timestamp is taken from the target of the symlink, unless
1      ‘-h’ was also in effect.
1 
1 ‘-t [[CC]YY]MMDDHHMM[.SS]’
1      Use the argument (optional four-digit or two-digit years, months,
1      days, hours, minutes, optional seconds) instead of the current
1      time.  If the year is specified with only two digits, then CC is 20
1      for years in the range 0 ... 68, and 19 for years in 69 ... 99.  If
1      no digits of the year are specified, the argument is interpreted as
1      a date in the current year.  On the atypical systems that support
1      leap seconds, SS may be ‘60’.
1 
1    On systems predating POSIX 1003.1-2001, ‘touch’ supports an obsolete
1 syntax, as follows.  If no timestamp is given with any of the ‘-d’,
1 ‘-r’, or ‘-t’ options, and if there are two or more FILEs and the first
1 FILE is of the form ‘MMDDHHMM[YY]’ and this would be a valid argument to
1 the ‘-t’ option (if the YY, if any, were moved to the front), and if the
1 represented year is in the range 1969–1999, that argument is interpreted
1 as the time for the other files instead of as a file name.  Although
1 this obsolete behavior can be controlled with the ‘_POSIX2_VERSION’
1 environment variable (⇒Standards conformance), portable scripts
1 should avoid commands whose behavior depends on this variable.  For
1 example, use ‘touch ./12312359 main.c’ or ‘touch -t 12312359 main.c’
1 rather than the ambiguous ‘touch 12312359 main.c’.
1 
1    An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1