usr.bin/touch/touch.1

.\"	$NetBSD: touch.1,v 1.30 2024/03/17 21:37:53 andvar Exp $
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)touch.1	8.3 (Berkeley) 4/28/95
.\"
.Dd February 10, 2024
.Dt TOUCH 1
.Os
.Sh NAME
.Nm touch
.Nd change file access and modification times
.Sh SYNOPSIS
.Nm
.Op Fl acDfhm
.Op Fl d Ar posix-datetime|human-datetime
.Op Fl Fl \|date Ar posix-datetime|human-datetime
.Op Fl R Ar ref-file
.Op Fl r Ar ref-file
.Op Fl Fl \|reference Ar ref-file
.Op Fl t Ar datetime
.Ar file ...
.Sh DESCRIPTION
The
.Nm
utility changes either or both of the access and modification times of the
.Ar file Ns s
to the time specified by the options, described below,
or to the current time of day, if none of those options is present.
If the file doesn't exist, it is first created with default permissions.
.Pp
The following options are available:
.Bl -tag -compact -width Fl
.Pp
.It Fl a
Change the access time of the
.Ar file .
The modification time of the
.Ar file
is not changed unless the
.Fl m
flag is also specified.
.Pp
.It Fl c
Do not create the
.Ar file
if it does not exist.
The
.Nm
utility does not treat this as an error.
No error messages are displayed and the exit value is not affected.
.Pp
.It Fl D
Do not attempt to adjust a
.Ar file Ns 's
times if they are already set to the values specified.
.Pp
.It Fl d Ar posix-datetime
.It Fl d Ar human-datetime
.It Fl Fl \|date Ar posix-datetime
.It Fl Fl \|date Ar human-datetime
Attempt to parse the arg
.Ar posix-datetime
as a POSIX time string
.Dq CCYY\-MM\-DDThh:mm:ss[.frac][Z]
where the minus (or hyphen)
.Pq Sq \&\-
and colon
.Pq Sq \&:
characters are literals, and:
.Bl -bullet -compact
.It
.Cm CCYY
represents a 4 (or more) digit year number,
.It
.Cm MM
represents a 2 digit month number (1\-12),
.It
.Cm DD
represents a 2 digit day of the month (1\-31),
.It
.Cm T
represents either the character
.Sq T
or a single space character (in which case the
space, at least, may need to be quoted to the shell to
avoid the arg being split into two words),
.It
.Cm hh
represents a 2 digit hour of the day (00\-23),
.It
.Cm mm
represents a 2 digit minute of the hour (00\-59),
.It
.Cm ss
represents a 2 digit second of the minute (00\-60)
where 60 indicates the occurrence of a leap second,
which POSIX systems ignore, resulting in the following
second being generated instead (:00 of the next minute),
.It
.Cm .frac
represents optional factional seconds, where the
.Sq \&.
can be a period
.Pq Sq \&.
or a comma
.Pq Sq \&,
and
.Cm frac
gives one or more digits, interpreted as if
in a floating-point representation of the seconds,
so
.Dq \&.3
represents three tenths of a second, and
.Dq \&,17
represents seventeen hundredths of a second, etc.
Note that if the period or comma is given, there
must be at least one following digit.
If no fraction of a second is to be specified,
also omit the period (or comma).
If omitted, the fractional seconds are set to 0,
so specifying
.Dq \&.0
or
.Dq \&,0
is identical to omitting the
.Cm \&.frac
field entirely,
.It
.Cm Z
represents an optional literal
.Sq Z
character, indicating the the time given is to
be considered as a Co-ordinated Universal Time (UTC) value.
If omitted, the time is considered as being in the local
timezone, as specified by the
.Ev TZ
environment variable.
.El
.Pp
Note that parsing of this string is quite strict.
If successfully parsed, the time to set will be that
specified by this string.
.Pp
If the attempt to parse the string as a
.Ar posix-datetime
fails, then
.Nm
will attempt to parse it as a
.Ar human-datetime
using the human datetime parser
.Xr parsedate 3 ,
and use the result as the time to set.
.Pp
.It Fl f
This flag has no effect; it is accepted for compatibility reasons.
.Pp
.It Fl h
If a
.Ar file
is a symbolic link, the access and/or modification time of the link is changed.
This option implies
.Fl c .
.Pp
.It Fl m
Change the modification time of the
.Ar file .
The access time of the
.Ar file
is not changed unless the
.Fl a
flag is also specified.
.Pp
.It Fl R Ar ref-file
.It Fl r Ar ref-file
.It Fl Fl \|reference Ar ref-file
Use the access and modification times,
as appropriate for the operation being performed,
from
.Ar ref-file
instead of the current time of day.
If the
.Ar ref-file
is a symbolic link,
then if the
.Fl R
form of this option was used,
the times are taken from the symbolic link itself,
otherwise
the times are taken from the file referenced by it.
If
.Ar ref-file
is not a symbolic link, all three forms are identical.
.Pp
.It Fl t Ar datetime
Change the access and modification times of the
.Ar file Ns Pq s
to the specified
.Ar datetime.
The argument
.Ar datetime
should be in the form
.Dq [[CC]YY]MMDDhhmm[.ss]
where each pair of letters represents exactly 2 decimal digits,
with the following interpretations:
.Pp
.Bl -tag -width Ds -compact -offset indent
.It Ar CC
The first two digits of the year (the century).
.It Ar YY
The second two digits of the year.
If
.Dq YY
is specified, but
.Dq CC
is not, a value for
.Dq YY
between 69 and 99 (inclusive) results in a
.Dq CC
value of 19.
Otherwise, a
.Dq CC
value of 20 is used.
.It Ar MM
The month of the year, from 1 to 12.
.It Ar DD
The day of the month, from 1 to 31.
.It Ar hh
The hour of the day, from 0 to 23.
.It Ar mm
The minute of the hour, from 0 to 59.
.It Ar ss
The second of the minute, from 0 to 60 (permitting leap seconds).
If
.Ar ss
is 60 and the resulting time,
as affected by the
.Ev TZ
environment variable,
does not refer to a leap second,
the resulting time is one second after a time where
.Ar ss
is 59.
If
.Ar ss
is not given a value, it is assumed to be zero, and the
preceding period
.Pq Sq \&.
must be omitted.
.El
.Pp
If the
.Dq CC
and
.Dq YY
letter pairs are not specified, the values default to the current
year.
If the
.Dq ss
letter pair
.Pq and the preceding period
is not specified, the value defaults to 0.
As an extension to the standard, any of the
.Dq MM ,
.Dq DD ,
and
.Dq hh
fields may also be omitted, defaulting to the current
time of day,
but once any one of these letter pairs is given, all
the following ones
.Pq except Dq \&.ss
are required.
Fields must always be specified as 2 digits, even when
the value is less than 10.
Leading zeroes do not cause the value to be treated as octal,
all conversions use decimal numbers.
.El
.Pp
The
.Fl d ,
.Fl R ,
.Fl r ,
and
.Fl t
options are (nominally) mutually exclusive.
If more than one of these options is present,
each will be evaluated, and may cause an error,
then the result from the last one specified is used.
.Pp
The options which specify any part of the time
.Pq Fl d , Fl R, Fl r , Fl t
apply to both the access and modification times
(with
.Fl r
and
.Fl R
obtaining those values independently from the
.Ar ref-file ) ,
though which is actually applied depends upon
the
.Fl a
and
.Fl m
options.
.Sh ENVIRONMENT
.Bl -tag -width -iTZ
.It Ev TZ
The time zone to be used for interpreting the
.Ar datetime
argument of the
.Fl t
option, and the default zone for the
.Ar posix-datetime
or
.Ar human-datetime
argument of the
.Fl d
option.
.El
.Sh EXAMPLES
.Dl touch -h -r path path
.Pp
If
.Ar path
is a symbolic link, this will set the symbolic link's
access and modify timestamps identical to those of the
file to which it refers.
If
.Ar path
is not a symbolic link,
this will simply update the
.Dq inode changed
time
.Pq Dq ctime
of the
.Ar path
file to the current time of day.
.Pp
.Dl touch -Dh -d human-datetime -t CCYYMMDDhhmm.ss -R file file
.Pp
Provided
.Ar file
exists, this parses the
.Ar human-datetime
and
.Ar CCYYMMDDhhmm.ss
arguments,
verifying that they would be suitable for use with
.Nm ,
then does nothing, as the final time specification
.Pq Fl R
specifies to take the times from
.Ar file
and apply them to
.Ar file
itself, changing nothing, which the
.Fl D
option then prevents from actually occurring.
That is, this merely tests that the
.Ar human-datetime
and
.Ar datetime
arguments to
.Fl d
and
.Fl t
respectively are valid, and could be used to specify a time.
Use of both
.Fl h
and
.Fl R
means this works if
.Ar file
is a symbolic link,
even one which does not reference an existing file,
as well as if it is some other file type.
Use of
.Fl R
requires that
.Ar file
exists,
though if it does not, and an error is generated for that reason,
the
.Fl d
and
.Fl t
arguments would have already been successfully processed.
.Pp
.Dl touch -m -d '-1 day' somefile
.Pp
Set the modify time for
.Ar somefile
to one day (24 hours) earlier than the current time.
.Sh EXIT STATUS
.Ex -std
.Sh COMPATIBILITY
The obsolescent form of
.Nm ,
where a time format is specified as the first argument, is supported.
When none of the time setting options is specified,
there are at least two arguments,
and the first argument is a string of digits
which is either eight or ten characters in length,
the first argument is interpreted as a time specification of the form
.Dq MMDDhhmm[YY]
and applied to the remaining arguments interpreted as path names.
.Pp
The
.Dq MM ,
.Dq DD ,
.Dq hh
and
.Dq mm
letter pairs are treated as their counterparts specified to the
.Fl t
option, except that none of these are optional.
If the
.Dq YY
letter pair is present,
it is interpret the same as
.Dq YY
in the
.Fl t
option with no
.Dq CC
specified, however here it appears last, rather than first.
There are no equivalents to the
.Dq CC
or
.Dq ss
fields of
.Fl t
and the fractional seconds field is always set to zero.
.Sh SEE ALSO
.Xr utimes 2 ,
.Xr parsedate 3
.Sh "FUTURE PLANNING"
Sometime in the middle of the 21st century, the default
.Dq CC
used in formats where that information is not present, or
where those digits are not given, will be altered to
make low year numbers represent the 22nd century, and high
years the 21st century.
The boundary between low and high is also expected to change.
To avoid issues, always use formats which include the
.Dq CC
field, and always use it when
.Dq YY
is given.
.Sh STANDARDS
The
.Nm
utility is expected to be a superset of the
.St -p1003.2
and
.St -p1003.1-2008
specifications.
.Sh HISTORY
A
.Nm
utility appeared in
.At v7 .