usr.bin/touch/touch.1

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