man/man1/touch.1

         te
 Copyright (c) 1992, X/Open Company Limited All Rights Reserved
 Copyright 1989 AT&T
 Portions Copyright (c) 2009, Sun Mricrosystems, Inc. All Rights Reserved
 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 Sun OS 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]
 TOUCH 1 "Sep 9, 2009"
 NAME
touch, settime - change file access and modification times
 SYNOPSIS

touch [-acm] [-r ref_file | -t time | -d date_time] file...


touch [-acm] [time_spec] file...


settime [-f ref_file] [time_spec] file...


 DESCRIPTION

The touch utility sets the access and modification times of each file.
The file operand is created if it does not already exist.

The time used can be specified by -t time, by -d
date_time, by the corresponding time fields of the file referenced by
-r ref_file, or by the time_spec operand. If none of these
are specified, touch uses the current time.

If neither the -a nor -m options are specified, touch updates
both the modification and access times.

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 touch results in
an error.

The settime utility is equivalent to touch -c
[time_spec] file.
 OPTIONS

The following options are supported in the touch and settime
utilities:
 "touch"

The following options are supported for the touch utility:
-a

Changes the access time of file. Does not change the modification time
unless -m is also specified.


-c

Does not create a specified file if it does not exist. Does not write any
diagnostic messages concerning this condition.


-d date_time

Uses the specified date_time instead of the current time. The option-argument
must be a string of the form:
YYYY-MM-DDThh:mm:SS[.frac][tz]


or
YYYY-MM-DDThh:mm:SS[,frac][tz]


where


YYYY is at least four decimal digits giving the year


MM, DD, hh, mm, and SS are as with -t
time


T is either the letter T or a single SPACE character


[.frac] and [,frac] are either empty, or a period (.) or
a comma (,) respectively, followed by one or more decimal digits,
specifying a fractional second


[tz] is either empty, signifying local time, or the letter Z,
signifying UTC. If [tz] is empty, the resulting time is affected by the
value of the TZ environment variable


-m

Changes the modification time of file. Does not change the access time
unless -a is also specified.


-r ref_file

Uses the corresponding times of the file named by ref_file instead of the
current time.


-t time

Uses the specified time instead of the current time. time is a
decimal number of the form:
[[CC]YY]MMDDhhmm[.SS]


where each two digits represent the following:
MM

The month of the year [01-12].


DD

The day of the month [01-31].


hh

The hour of the day [00-23].


mm

The minute of the hour [00-59].


CC

The first two digits of the year.


YY

The second two digits of the year.


SS

The second of the minute [00-61].


Both CC and YY are optional. If neither is given, the current year
is assumed. If YY is specified, but CC is not, CC is derived
as follows:


If YY is: CC becomes:
69-99 19
00-38 20
39-68 ERROR


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


 "settime"

The following option is supported for the settime utility:
-f ref_file

Uses the corresponding times of the file named by ref_file instead of the
current time.


 OPERANDS

The following operands are supported for the touch and settime
utilities:
file

A path name of a file whose times are to be modified.


time_spec

Uses the specified time_spec instead of the current time. This operand is
a decimal number of the form:
MMDDhhmm[YY]


where each two digits represent the following:
MM

The month of the year [01-12].


DD

The day of the month [01-31].


hh

The hour of the day [00-23].


mm

The minute of the hour [00-59].


YY

The second two digits of the year.
YY is optional. If it is omitted, the current year is assumed. If
YY is specified, the year is derived as follows:


YY Corresponding Year
69-99 1969-1999
00-38 2000-2038
39-68 ERROR


If no -d, -r, or -toption 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 time_spec operand. Otherwise, the
first operand is assumed to be a file operand.


 USAGE

See largefile(5) for the description of the behavior of touch when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 ENVIRONMENT VARIABLES

See environ(5) for descriptions of the following environment variables
that affect the execution of touch: LANG, LC_ALL, LANG,
LC_ALL, LC_CTYPE, LC_MESSAGES, and NLSPATH.
TZ

Determine the timezone to be used for interpreting the time or
date_time option-argument or the time_spec operand.


 EXIT STATUS

The following exit values are returned:
0

The touch utility executed successfully and all requested changes were
made.


>0

An error occurred. The touch utility returned the number of files for
which the times could not be successfully modified.


 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:


ATTRIBUTE TYPE ATTRIBUTE VALUE
CSI Enabled
Interface Stability Committed
Standard See standards(5).


 SEE ALSO

futimens(2), stat(2), attributes(5), environ(5),
largefile(5), standards(5)
 NOTES

Users familiar with the BSD environment find that for the touch utility,
the -f option is accepted but ignored. The -f option is unnecessary
because touch succeeds for all files owned by the user regardless of the
permissions on the files.