[unix-history] / usr.bin / touch / touch.1

.\" Copyright (c) 1991 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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	6.5 (Berkeley) 3/6/93
.\"
.Dd March 6, 1993
.Dt TOUCH 1
.Os
.Sh NAME
.Nm touch
.Nd change file access and modification times
.Sh SYNOPSIS
.Nm touch
.Op Fl acfm
.Op Fl r Ar file
.Op Fl t [[CC]YY]MMDDhhmm[.SS]
.Op Fl T seconds
.Ar file ...
.Sh DESCRIPTION
The
.Nm touch
utility sets the modification and access times of files to the
current time of day.
If the file doesn't exist, it is created with default permissions.
.Pp
The following options are available:
.Bl -tag -width Ds
.It Fl a
Change the access time of the file.
The modification time of the file is not changed unless the
.Fl m
flag is also specified.
.It Fl c
Do not create the file if it does not exist.
The
.Nm touch
utility does not treat this as an error.
No error messages are displayed and the exit value is not affected.
.It Fl f
Attempt to force the update, even if the file permissions do not
currently permit it.
.It Fl m
Change the modification time of the file.
The access time of the file is not changed unless the
.Fl a
flag is also specified.
.It Fl r
Use the access and modifications times from the specified file
instead of the current time of day.
.It Fl T
Change the access and modification times to the specified time.
The time is seconds since the start of the epoch. (The same value returned
by time(3).)
.It Fl t
Change the access and modification times to the specified time.
The argument should be in the form
.Dq [[CC]YY]MMDDhhmm[.SS]
where each pair of letters represents the following:
.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 results in a
.Dq YY
value of 19.
Otherwise, a
.Dq YY
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 61.
.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 is not specified, the value defaults to 0.
.El
.Pp
The
.Nm touch
utility exits 0 on success, and >0 if an error occurs.
.Sh SEE ALSO
.Xr utimes 2 ,
.Xr time 3
.Sh COMPATIBILITY
The obsolescent form of
.Nm touch ,
where a time format is specified as the first argument, is supported.
When no
.Fl r
or
.Fl t
option is specified, there are at least two arguments, and the first
argument is a string of digits either eight or ten characters in length,
the first argument is interprested as a time specification of the form
.Dq MMDDhhmm[YY] .
.Pp
The
.Dq MM ,
.Dq DD ,
.Dq hh
and
.Dq mm
letter pairs are treated as their counterparts specified to the
.Fl t
option.
If the
.Dq YY
letter pair is in the range 69 to 99, the year is set to 1969 to 1999,
otherwise, the year is set in the 21st century.
.Sh HISTORY
A
.Nm touch
command appeared in
.At v7 .
.Sh STANDARDS
The
.Nm touch
function is expected to be a superset of the
.St -p1003.2
specification.
Commit	Line	Data
15637ed4 RG	1	.\" Copyright (c) 1991 Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" the Institute of Electrical and Electronics Engineers, Inc.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
78ed81a3	35	.\" @(#)touch.1 6.5 (Berkeley) 3/6/93
15637ed4	36	.\"
78ed81a3	37	.Dd March 6, 1993
15637ed4 RG	38	.Dt TOUCH 1
	39	.Os
	40	.Sh NAME
	41	.Nm touch
78ed81a3	42	.Nd change file access and modification times
15637ed4 RG	43	.Sh SYNOPSIS
15637ed4 RG	44	.Nm touch
78ed81a3	45	.Op Fl acfm
	46	.Op Fl r Ar file
	47	.Op Fl t [[CC]YY]MMDDhhmm[.SS]
	48	.Op Fl T seconds
15637ed4 RG	49	.Ar file ...
	50	.Sh DESCRIPTION
	51	The
	52	.Nm touch
78ed81a3	53	utility sets the modification and access times of files to the
	54	current time of day.
	55	If the file doesn't exist, it is created with default permissions.
15637ed4	56	.Pp
78ed81a3	57	The following options are available:
15637ed4	58	.Bl -tag -width Ds
78ed81a3	59	.It Fl a
	60	Change the access time of the file.
	61	The modification time of the file is not changed unless the
	62	.Fl m
	63	flag is also specified.
15637ed4	64	.It Fl c
78ed81a3	65	Do not create the file if it does not exist.
	66	The
	67	.Nm touch
	68	utility does not treat this as an error.
	69	No error messages are displayed and the exit value is not affected.
15637ed4	70	.It Fl f
78ed81a3	71	Attempt to force the update, even if the file permissions do not
	72	currently permit it.
	73	.It Fl m
	74	Change the modification time of the file.
	75	The access time of the file is not changed unless the
	76	.Fl a
	77	flag is also specified.
	78	.It Fl r
	79	Use the access and modifications times from the specified file
	80	instead of the current time of day.
	81	.It Fl T
	82	Change the access and modification times to the specified time.
	83	The time is seconds since the start of the epoch. (The same value returned
	84	by time(3).)
	85	.It Fl t
	86	Change the access and modification times to the specified time.
	87	The argument should be in the form
	88	.Dq [[CC]YY]MMDDhhmm[.SS]
	89	where each pair of letters represents the following:
	90	.Pp
	91	.Bl -tag -width Ds -compact -offset indent
	92	.It Ar CC
	93	The first two digits of the year (the century).
	94	.It Ar YY
	95	The second two digits of the year.
	96	If
	97	.Dq YY
	98	is specified, but
	99	.Dq CC
	100	is not, a value for
	101	.Dq YY
	102	between 69 and 99 results in a
	103	.Dq YY
	104	value of 19.
	105	Otherwise, a
	106	.Dq YY
	107	value of 20 is used.
	108	.It Ar MM
	109	The month of the year, from 1 to 12.
	110	.It Ar DD
	111	the day of the month, from 1 to 31.
	112	.It Ar hh
	113	The hour of the day, from 0 to 23.
	114	.It Ar mm
	115	The minute of the hour, from 0 to 59.
	116	.It Ar SS
	117	The second of the minute, from 0 to 61.
	118	.El
	119	.Pp
	120	If the
	121	.Dq CC
	122	and
	123	.Dq YY
	124	letter pairs are not specified, the values default to the current
	125	year.
	126	If the
	127	.Dq SS
	128	letter pair is not specified, the value defaults to 0.
	129	.El
	130	.Pp
	131	The
15637ed4	132	.Nm touch
78ed81a3	133	utility exits 0 on success, and >0 if an error occurs.
15637ed4	134	.Sh SEE ALSO
78ed81a3	135	.Xr utimes 2 ,
	136	.Xr time 3
	137	.Sh COMPATIBILITY
	138	The obsolescent form of
	139	.Nm touch ,
	140	where a time format is specified as the first argument, is supported.
	141	When no
	142	.Fl r
	143	or
	144	.Fl t
	145	option is specified, there are at least two arguments, and the first
	146	argument is a string of digits either eight or ten characters in length,
	147	the first argument is interprested as a time specification of the form
	148	.Dq MMDDhhmm[YY] .
	149	.Pp
	150	The
	151	.Dq MM ,
	152	.Dq DD ,
	153	.Dq hh
	154	and
	155	.Dq mm
	156	letter pairs are treated as their counterparts specified to the
	157	.Fl t
	158	option.
	159	If the
	160	.Dq YY
	161	letter pair is in the range 69 to 99, the year is set to 1969 to 1999,
	162	otherwise, the year is set in the 21st century.
15637ed4 RG	163	.Sh HISTORY
15637ed4 RG	164	A
78ed81a3	165	.Nm touch
15637ed4 RG	166	command appeared in
15637ed4 RG	167	.At v7 .
78ed81a3	168	.Sh STANDARDS
	169	The
	170	.Nm touch
	171	function is expected to be a superset of the
	172	.St -p1003.2
	173	specification.