path: root/usr/src/man/man1/touch.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Portions Copyright (c) 2009, Sun Mricrosystems, Inc. All Rights Reserved
.\"
.TH TOUCH 1 "Sep 9, 2009"
.SH NAME
touch, settime \- change file access and modification times
.SH SYNOPSIS
.LP
.nf
\fBtouch\fR [\fB-acm\fR] [\fB-r\fR \fIref_file\fR | \fB-t\fR \fItime\fR | \fB-d\fR \fIdate_time\fR] \fIfile\fR...
.fi

.LP
.nf
\fBtouch\fR [\fB-acm\fR] [\fItime_spec\fR] \fIfile\fR...
.fi

.LP
.nf
\fBsettime\fR [\fB-f\fR \fIref_file\fR] [\fItime_spec\fR] \fIfile\fR...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBtouch\fR utility sets the access and modification times of each file.
The \fIfile\fR operand is created if it does not already exist.
.sp
.LP
The time used can be specified by \fB-t\fR \fItime\fR, by \fB-d\fR
\fIdate_time\fR, by the corresponding time fields of the file referenced by
\fB-r\fR \fIref_file\fR, or by the \fItime_spec\fR operand. If none of these
are specified, \fBtouch\fR uses the current time.
.sp
.LP
If neither the \fB-a\fR nor \fB-m\fR options are specified, \fBtouch\fR updates
both the modification and access times.
.sp
.LP
A user with write access to a file, but who is not the owner of the file or a
super-user, can change the modification and access times of that file only to
the current time. Attempts to set a specific time with \fBtouch\fR results in
an error.
.sp
.LP
The \fBsettime\fR utility is equivalent to \fBtouch\fR \fB-c\fR
[\fItime_spec\fR] \fIfile\fR.
.SH OPTIONS
.sp
.LP
The following options are supported in the \fBtouch\fR and \fBsettime\fR
utilities:
.SS "touch"
.sp
.LP
The following options are supported for the \fBtouch\fR utility:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
Changes the access time of \fIfile\fR. Does not change the modification time
unless \fB-m\fR is also specified.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.sp .6
.RS 4n
Does not create a specified \fIfile\fR if it does not exist. Does not write any
diagnostic messages concerning this condition.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdate_time\fR\fR
.ad
.sp .6
.RS 4n
Uses the specified date_time instead of the current time. The option-argument
must be a string of the form:
.sp
.in +2
.nf
\fIYYYY\fR-\fIMM\fR-\fIDDThh\fR:\fImm\fR:\fISS\fR[.\fIfrac\fR][\fItz\fR]
.fi
.in -2
.sp

or
.sp
.in +2
.nf
\fIYYYY\fR-\fIMM\fR-\fIDDThh\fR:\fImm\fR:\fISS\fR[,\fIfrac\fR][\fItz\fR]
.fi
.in -2
.sp

where
.RS +4
.TP
.ie t \(bu
.el o
\fIYYYY\fR is at least four decimal digits giving the year
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIMM\fR, \fIDD\fR, \fIhh\fR, \fImm\fR, and \fISS\fR are as with \fB-t\fR
\fItime\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIT\fR is either the letter \fBT\fR or a single SPACE character
.RE
.RS +4
.TP
.ie t \(bu
.el o
[\fI\&.frac\fR] and [\fI,frac\fR] are either empty, or a period (\fB\&.\fR) or
a comma (\fB,\fR) respectively, followed by one or more decimal digits,
specifying a fractional second
.RE
.RS +4
.TP
.ie t \(bu
.el o
[\fItz\fR] is either empty, signifying local time, or the letter \fBZ\fR,
signifying UTC. If [\fItz\fR] is empty, the resulting time is affected by the
value of the \fBTZ\fR environment variable
.RE
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.sp .6
.RS 4n
Changes the modification time of \fIfile\fR. Does not change the access time
unless \fB-a\fR is also specified.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIref_file\fR\fR
.ad
.sp .6
.RS 4n
Uses the corresponding times of the file named by \fIref_file\fR instead of the
current time.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItime\fR\fR
.ad
.sp .6
.RS 4n
Uses the specified \fItime\fR instead of the current time. \fItime\fR is a
decimal number of the form:
.sp
.in +2
.nf
[[\fICC\fR]\fIYY\fR]\fIMMDDhhmm\fR[\fI\&.SS\fR]
.fi
.in -2
.sp

where each two digits represent the following:
.sp
.ne 2
.na
\fB\fIMM\fR\fR
.ad
.sp .6
.RS 4n
The month of the year [01-12].
.RE

.sp
.ne 2
.na
\fB\fIDD\fR\fR
.ad
.sp .6
.RS 4n
The day of the month [01-31].
.RE

.sp
.ne 2
.na
\fB\fIhh\fR\fR
.ad
.sp .6
.RS 4n
The hour of the day [00-23].
.RE

.sp
.ne 2
.na
\fB\fImm\fR\fR
.ad
.sp .6
.RS 4n
The minute of the hour [00-59].
.RE

.sp
.ne 2
.na
\fB\fICC\fR\fR
.ad
.sp .6
.RS 4n
The first two digits of the year.
.RE

.sp
.ne 2
.na
\fB\fIYY\fR\fR
.ad
.sp .6
.RS 4n
The second two digits of the year.
.RE

.sp
.ne 2
.na
\fB\fISS\fR\fR
.ad
.sp .6
.RS 4n
The second of the minute [00-61].
.RE

Both \fICC\fR and \fIYY\fR are optional. If neither is given, the current year
is assumed. If \fIYY\fR is specified, but \fICC\fR is not, \fICC\fR is derived
as follows:
.sp

.sp
.TS
box;
c c
l l .
If YY is:	CC becomes:
_
69-99	19
00-38	20
39-68	ERROR
.TE

The resulting time is affected by the value of the \fBTZ\fR environment
variable. If the resulting time value precedes the Epoch, \fBtouch\fR exits
immediately with an error status. The range of valid times is the Epoch to
January 18, 2038.
.sp
The range for \fISS\fR is [00-61] rather than [00-59] because of leap seconds.
If \fISS\fR is 60 or 61, and the resulting time, as affected by the \fBTZ\fR
environment variable, does not refer to a leap second, the resulting time is
one or two seconds after a time where \fISS\fR is 59. If \fISS\fR is not given,
it is assumed to be 0.
.RE

.SS "settime"
.sp
.LP
The following option is supported for the \fBsettime\fR utility:
.sp
.ne 2
.na
\fB\fB-f\fR \fIref_file\fR\fR
.ad
.sp .6
.RS 4n
Uses the corresponding times of the file named by \fIref_file\fR instead of the
current time.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported for the \fBtouch\fR and \fBsettime\fR
utilities:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.sp .6
.RS 4n
A path name of a file whose times are to be modified.
.RE

.sp
.ne 2
.na
\fB\fItime_spec\fR\fR
.ad
.sp .6
.RS 4n
Uses the specified \fItime_spec\fR instead of the current time. This operand is
a decimal number of the form:
.sp
.in +2
.nf
\fIMMDDhhmm\fR[\fIYY\fR]
.fi
.in -2
.sp

where each two digits represent the following:
.sp
.ne 2
.na
\fB\fIMM\fR\fR
.ad
.sp .6
.RS 4n
The month of the year [01-12].
.RE

.sp
.ne 2
.na
\fB\fIDD\fR\fR
.ad
.sp .6
.RS 4n
The day of the month [01-31].
.RE

.sp
.ne 2
.na
\fB\fIhh\fR\fR
.ad
.sp .6
.RS 4n
The hour of the day [00-23].
.RE

.sp
.ne 2
.na
\fB\fImm\fR\fR
.ad
.sp .6
.RS 4n
The minute of the hour [00-59].
.RE

.sp
.ne 2
.na
\fB\fIYY\fR\fR
.ad
.sp .6
.RS 4n
The second two digits of the year.
.sp
\fIYY\fR is optional. If it is omitted, the current year is assumed. If
\fIYY\fR is specified, the year is derived as follows:
.RE

.sp

.sp
.TS
box;
c c
l l .
YY	Corresponding Year
69-99	1969-1999
00-38	2000-2038
39-68	ERROR
.TE

If no \fB-d\fR, \fB-r\fR, or \fB-t\fRoption is specified, at least two operands
are specified, and the first operand is an eight- or ten-digit decimal integer,
the first operand is assumed to be a \fItime_spec\fR operand. Otherwise, the
first operand is assumed to be a \fIfile\fR operand.
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBtouch\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBtouch\fR: \fBLANG\fR, \fBLC_ALL\fR, \fBLANG\fR,
\fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.sp
.ne 2
.na
\fB\fBTZ\fR\fR
.ad
.sp .6
.RS 4n
Determine the timezone to be used for interpreting the \fItime\fR or
\fIdate_time\fR option-argument or the \fItime_spec\fR operand.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
The \fBtouch\fR utility executed successfully and all requested changes were
made.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.sp .6
.RS 4n
An error occurred. The \fBtouch\fR utility returned the number of files for
which the times could not be successfully modified.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBfutimens\fR(2), \fBstat\fR(2), \fBattributes\fR(5), \fBenviron\fR(5),
\fBlargefile\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
Users familiar with the BSD environment find that for the \fBtouch\fR utility,
the \fB-f\fR option is accepted but ignored. The \fB-f\fR option is unnecessary
because \fBtouch\fR succeeds for all files owned by the user regardless of the
permissions on the files.