touch(P)                                               touch(P)





NAME
       touch - change file access and modification times

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

DESCRIPTION
       The  touch  utility shall change the modification times,
       access times, or both of files.  The  modification  time
       shall  be equivalent to the value of the st_mtime member
       of the stat structure for a file, as  described  in  the
       System  Interfaces  volume  of IEEE Std 1003.1-2001; the
       access  time  shall  be  equivalent  to  the  value   of
       st_atime.

       The  time  used  can be specified by the -t time option-
       argument, the corresponding time fields of the file ref-
       erenced  by  the  -r  ref_file  option-argument,  or the
       date_time operand, as specified in  the  following  sec-
       tions.  If  none of these are specified, touch shall use
       the current time (the value returned by  the  equivalent
       of  the time() function defined in the System Interfaces
       volume of IEEE Std 1003.1-2001).

       For each  file  operand,  touch  shall  perform  actions
       equivalent  to  the  following  functions defined in the
       System Interfaces volume of IEEE Std 1003.1-2001:

       If file does not exist, a creat() function call is  made
       with  the file operand used as the path argument and the
       value of the bitwise-inclusive OR of  S_IRUSR,  S_IWUSR,
       S_IRGRP,  S_IWGRP, S_IROTH, and S_IWOTH used as the mode
       argument.

       The utime() function is called with the following  argu-
       ments: <ol type="a">

       The file operand is used as the path argument.

       The  utimbuf  structure  members  actime and modtime are
       determined as described in the OPTIONS section.

OPTIONS
       The touch utility shall conform to the Base  Definitions
       volume  of  IEEE Std 1003.1-2001,  Section 12.2, Utility
       Syntax Guidelines.

       The following options shall be supported:

       -a     Change the access time of file. Do not change the
              modification time unless -m is also specified.

       -c     Do  not  create  a  specified file if it does not
              exist. Do not write any diagnostic messages  con-
              cerning this condition.

       -m     Change  the  modification  time  of  file. Do not
              change the access time unless -a is  also  speci-
              fied.

       -r  ref_file
              Use  the  corresponding time of the file named by
              the pathname  ref_file  instead  of  the  current
              time.

       -t  time
              Use  the  specified  time  instead of the current
              time. The option-argument shall be a decimal num-
              ber of the form:


              [[CC]YY]MMDDhhmm[.SS]

       where each two digits represents 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 (the century).

       YY     The second two digits of the year.

       SS     The second of the minute [00,60].


       Both  CC  and YY shall be optional. If neither is given,
       the current year shall be assumed. If YY  is  specified,
       but CC is not, CC shall be derived as follows:
          If YY is:     CC becomes:
          [69,99]       19
          [00,68]       20

       Note:  It  is  expected  that  in  a  future  version of
              IEEE Std 1003.1-2001 the default century inferred
              from  a  2-digit  year  will  change. (This would
              apply to all commands accepting a 2-digit year as
              input.)


       The resulting time shall be affected by the value of the
       TZ environment variable. If  the  resulting  time  value
       precedes the Epoch, touch shall exit immediately with an
       error status.  The range of valid times past  the  Epoch
       is  implementation-defined,  but  it  shall extend to at
       least the time 0 hours, 0 minutes, 0 seconds, January 1,
       2038,  Coordinated  Universal Time. Some implementations
       may not be able to represent dates  beyond  January  18,
       2038, because they use signed int as a time holder.

       The  range for SS is [00,60] rather than [00,59] because
       of leap seconds. If SS is 60, and the resulting time, as
       affected  by the TZ environment variable, does not refer
       to a leap second, the resulting time shall be one second
       after a time where SS is 59. If SS is not given a value,
       it is assumed to be zero.


       If neither the -a nor -m options were  specified,  touch
       shall behave as if both the -a and -m options were spec-
       ified.

OPERANDS
       The following operands shall be supported:

       file   A pathname of a file whose times shall  be  modi-
              fied.


STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The  following  environment  variables  shall affect the
       execution of touch:

       LANG   Provide a default value for the internationaliza-
              tion  variables  that are unset or null. (See the
              Base Definitions volume of  IEEE Std 1003.1-2001,
              Section  8.2,  Internationalization Variables for
              the precedence of internationalization  variables
              used  to  determine  the  values  of locale cate-
              gories.)

       LC_ALL If set to a non-empty string value, override  the
              values  of  all  the  other  internationalization
              variables.

       LC_CTYPE
              Determine the locale for  the  interpretation  of
              sequences  of  bytes  of  text data as characters
              (for example, single-byte as  opposed  to  multi-
              byte characters in arguments).

       LC_MESSAGES
              Determine  the  locale  that  should  be  used to
              affect the format and contents of diagnostic mes-
              sages written to standard error.

       NLSPATH
              Determine  the  location  of message catalogs for
              the processing of LC_MESSAGES .

       TZ     Determine the timezone to be used for  interpret-
              ing  the  time option-argument. If TZ is unset or
              null, an unspecified default  timezone  shall  be
              used.


ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       The  standard  error  shall  be used only for diagnostic
       messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

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

       >0     An error occurred.


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The  interpretation of time is taken to be seconds since
       the  Epoch  (see  the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001,  Section  4.14,  Seconds Since the
       Epoch). It should be noted that implementations conform-
       ing    to    the    System    Interfaces    volume    of
       IEEE Std 1003.1-2001  do  not  take  leap  seconds  into
       account  when  computing  seconds  since the Epoch. When
       SS=60 is used, the resulting time  always  refers  to  1
       plus seconds since the Epoch for a time when SS=59.

       Although the -t time option-argument specifies values in
       1969, the access time and modification time  fields  are
       defined in terms of seconds since the Epoch (00:00:00 on
       1 January 1970 UTC). Therefore, depending on  the  value
       of  TZ when touch is run, there is never more than a few
       valid hours in 1969 and there  need  not  be  any  valid
       times in 1969.

       One  ambiguous situation occurs if -t time is not speci-
       fied, -r ref_file is not specified, and the first  oper-
       and  is an eight or ten-digit decimal number. A portable
       script can avoid this problem by using:


              touch -- file

       or:


              touch ./file

       in this case.

EXAMPLES
       None.

RATIONALE
       The functionality of touch is described almost  entirely
       through references to functions in the System Interfaces
       volume of IEEE Std 1003.1-2001. In this way, there is no
       duplication  of effort required for describing such side
       effects as the relationship of  user  IDs  to  the  user
       database, permissions, and so on.

       There are some significant differences between the touch
       utility in this volume of IEEE Std 1003.1-2001 and those
       in System V and BSD systems. They are upwards-compatible
       for historical applications from both implementations:

       In System V, an ambiguity exists when a pathname that is
       a  decimal number leads the operands; it is treated as a
       time value. In BSD, no time value is allowed; files  may
       only  be  touched  to the current time. The -t time con-
       struct  solves  these  problems  for  future  conforming
       applications  (note that the -t option is not historical
       practice).

       The inclusion of the century digits, CC,  is  also  new.
       Note  that  a  ten-digit time value is treated as if YY,
       and not CC, were specified. The caveat about  the  range
       of dates following the Epoch was included as recognition
       that some implementations  are  not  able  to  represent
       dates beyond 18 January 2038 because they use signed int
       as a time holder.

       The  -r  option  was  added  because  several   comments
       requested  this  capability. This option was named -f in
       an early proposal, but was changed because the -f option
       is  used  in  the  BSD version of touch with a different
       meaning.

       At least one historical implementation of  touch  incre-
       mented  the  exit  code if -c was specified and the file
       did  not  exist.  This  volume  of  IEEE Std 1003.1-2001
       requires exit status zero if no errors occur.

FUTURE DIRECTIONS
       Applications should use the -r or -t options.

SEE ALSO
       date    ,    the    System    Interfaces    volume    of
       IEEE Std 1003.1-2001, creat(), time(), utime(), the Base
       Definitions volume of IEEE Std 1003.1-2001, <sys/stat.h>

COPYRIGHT
       Portions of this text are reprinted  and  reproduced  in
       electronic  form  from  IEEE  Std  1003.1, 2003 Edition,
       Standard for Information Technology -- Portable  Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute  of  Electrical  and Electronics Engineers, Inc and
       The Open Group. In the event of any discrepancy  between
       this  version  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.open-
       group.org/unix/online.html .



POSIX                         2003                     touch(P)
