TOUCH(1)                   POSIX Programmer's Manual                  TOUCH(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       touch -- change file access and modification times

SSYYNNOOPPSSIISS
       touch [[-acm]] [[-r _r_e_f___f_i_l_e|-t _t_i_m_e|-d _d_a_t_e___t_i_m_e]] _f_i_l_e...

DDEESSCCRRIIPPTTIIOONN
       The _t_o_u_c_h utility shall change the last data modification timestamps,
       the last data access timestamps, or both.

       The time used can be specified by the --tt _t_i_m_e option-argument, the
       corresponding _t_i_m_e fields of the file referenced by the --rr _r_e_f___f_i_l_e
       option-argument, or the --dd _d_a_t_e___t_i_m_e option-argument, as specified in
       the following sections. If none of these are specified, _t_o_u_c_h shall use
       the current time.

       For each _f_i_l_e operand, _t_o_u_c_h shall perform actions equivalent to the
       following functions defined in the System Interfaces volume of
       POSIX.1-2008:

        1. If _f_i_l_e does not exist:

            a. The _c_r_e_a_t() function is called with the following arguments:

               --  The _f_i_l_e operand is used as the _p_a_t_h argument.

               --  The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR,
                   S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the _m_o_d_e
                   argument.

            b. The _f_u_t_i_m_e_n_s() function is called with the following arguments:

               --  The file descriptor opened in step 1a.

               --  The access time and the modification time, set as described
                   in the OPTIONS section, are used as the first and second
                   elements of the _t_i_m_e_s array argument, respectively.

        2. If _f_i_l_e exists, the _u_t_i_m_e_n_s_a_t() function is called with the
           following arguments:

            a. The AT_FDCWD special value is used as the _f_d argument.

            b. The _f_i_l_e operand is used as the _p_a_t_h argument.

            c. The access time and the modification time, set as described in
               the OPTIONS section, are used as the first and second elements
               of the _t_i_m_e_s array argument, respectively.

            d. The _f_l_a_g argument is set to zero.

OOPPTTIIOONNSS
       The _t_o_u_c_h utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

       --aa        Change the access time of _f_i_l_e.  Do not change the
                 modification time unless --mm is also specified.

       --cc        Do not create a specified _f_i_l_e if it does not exist. Do not
                 write any diagnostic messages concerning this condition.

       --dd _d_a_t_e___t_i_m_e
                 Use the specified _d_a_t_e___t_i_m_e instead of the current time. The
                 option-argument shall be a string of the form:

                     _Y_Y_Y_Y-_M_M-_D_DT_h_h:_m_m:_S_S[[._f_r_a_c]][[_t_z]]

                 or:

                     _Y_Y_Y_Y-_M_M-_D_DT_h_h:_m_m:_S_S[[,_f_r_a_c]][[_t_z]]

                 where:

                  *  _Y_Y_Y_Y are at least four decimal digits giving the year.

                  *  _M_M, _D_D, _h_h, _m_m, and _S_S are as with --tt _t_i_m_e.

                  *  T is the time designator, and can be replaced by a single
                     <space>.

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

                  *  [_t_z] is either empty, signifying local time, or the
                     letter ''ZZ'', signifying UTC. If [_t_z] is empty, the
                     resulting time shall be affected by the value of the _T_Z
                     environment variable.

                 If the resulting time precedes the Epoch, the behavior is
                 implementation-defined. If the time cannot be represented as
                 the file's timestamp, _t_o_u_c_h shall exit immediately with an
                 error status.

       --mm        Change the modification time of _f_i_l_e.  Do not change the
                 access time unless --aa is also specified.

       --rr _r_e_f___f_i_l_e
                 Use the corresponding time of the file named by the pathname
                 _r_e_f___f_i_l_e instead of the current time.

       --tt _t_i_m_e   Use the specified _t_i_m_e instead of the current time. The
                 option-argument shall be a decimal number of the form:

                     [[[[_C_C]]_Y_Y]]_M_M_D_D_h_h_m_m[[._S_S]]

                 where each two digits represents the following:

                 _M_M      The month of the year [01,12].

                 _D_D      The day of the month [01,31].

                 _h_h      The hour of the day [00,23].

                 _m_m      The minute of the hour [00,59].

                 _C_C      The first two digits of the year (the century).

                 _Y_Y      The second two digits of the year.

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

                 Both _C_C and _Y_Y shall be optional. If neither is given, the
                 current year shall be assumed. If _Y_Y is specified, but _C_C is
                 not, _C_C shall be derived as follows:

                                   +----------+-------------+
                                   |IIff _Y_Y iiss:: | _C_C bbeeccoommeess:: |
                                   +----------+-------------+
                                   | [69,99]  |     19      |
                                   | [00,68]  |     20      |
                                   +----------+-------------+
                 NNoottee::     It is expected that in a future version of this
                           standard 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 _T_Z
                 environment variable. If the resulting time value precedes
                 the Epoch, the behavior is implementation-defined. If the
                 time is out of range for the file's timestamp, _t_o_u_c_h 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 ssiiggnneedd iinntt as a time
                 holder.

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

       If neither the --aa nor --mm options were specified, _t_o_u_c_h shall behave as
       if both the --aa and --mm options were specified.

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _f_i_l_e      A pathname of a file whose times shall be modified.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of
       _t_o_u_c_h:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       _T_Z        Determine the timezone to be used for interpreting the _t_i_m_e
                 option-argument. If _T_Z is unset or null, an unspecified
                 default timezone shall be used.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       Not used.

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

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

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

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The interpretation of time is taken to be _s_e_c_o_n_d_s _s_i_n_c_e _t_h_e _E_p_o_c_h (see
       the Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _4_._1_5, _S_e_c_o_n_d_s
       _S_i_n_c_e _t_h_e _E_p_o_c_h).  It should be noted that implementations conforming
       to the System Interfaces volume of POSIX.1-2008 do not take leap
       seconds into account when computing seconds since the Epoch. When _S_S=60
       is used, the resulting time always refers to 1 plus _s_e_c_o_n_d_s _s_i_n_c_e _t_h_e
       _E_p_o_c_h for a time when _S_S=59.

       Although the --tt _t_i_m_e 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 _T_Z when _t_o_u_c_h 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 --tt _t_i_m_e is not specified, --rr _r_e_f___f_i_l_e
       is not specified, and the first operand is an eight or ten-digit
       decimal number. A portable script can avoid this problem by using:

           ttoouucchh ---- ffiillee

       or:

           ttoouucchh ..//ffiillee

       in this case.

       If the _T time designator is replaced by a <space> for the --dd _d_a_t_e___t_i_m_e
       option-argument, the <space> must be quoted to prevent the shell from
       splitting the argument.

EEXXAAMMPPLLEESS
       Create or update a file called ddwwcc; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:30 local time:

           ttoouucchh --dd 22000077--1111--1122TT1100::1155::3300 ddwwcc

       Create or update a file called nniicckk; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:30 UTC:

           ttoouucchh --dd 22000077--1111--1122TT1100::1155::3300ZZ nniicckk

       Create or update a file called ggwwcc; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:30 local time with a fractional second timestamp of
       .002 seconds:

           ttoouucchh --dd 22000077--1111--1122TT1100::1155::3300,,000022 ggwwcc

       Create or update a file called aajjoosseeyy; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:30 UTC with a fractional second timestamp of .002
       seconds:

           ttoouucchh --dd ""22000077--1111--1122 1100::1155::3300..000022ZZ"" aajjoosseeyy

       Create or update a file called ccaatthhyy; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:00 local time:

           ttoouucchh --tt 220000771111112211001155 ccaatthhyy

       Create or update a file called ddrreeppppeerr; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:30 local time:

           ttoouucchh --tt 220000771111112211001155..3300 ddrreeppppeerr

       Create or update a file called eebbbb99; the resulting file has both the
       last data modification and last data access timestamps set to November
       12, 2007 at 10:15:30 local time:

           ttoouucchh --tt 00771111112211001155..3300 eebbbb99

       Create or update a file called eeggggeerrtt; the resulting file has the last
       data access timestamp set to the corresponding time of the file named
       mmaarrkk instead of the current time. If the file exists, the last data
       modification time is not changed:

           ttoouucchh --aa --rr mmaarrkk eeggggeerrtt

RRAATTIIOONNAALLEE
       The functionality of _t_o_u_c_h is described almost entirely through
       references to functions in the System Interfaces volume of
       POSIX.1-2008. 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 _t_o_u_c_h utility in
       this volume of POSIX.1-2008 and those in System V and BSD systems. They
       are upwards-compatible for historical applications from both
       implementations:

        1. 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 _t_i_m_e value is allowed; files may only be _t_o_u_c_hed to the current
           time. The --tt _t_i_m_e construct solves these problems for future
           conforming applications (note that the --tt option is not historical
           practice).

        2. The inclusion of the century digits, _C_C, is also new. Note that a
           ten-digit _t_i_m_e value is treated as if _Y_Y, and not _C_C, 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 ssiiggnneedd
           iinntt as a time holder.

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

       At least one historical implementation of _t_o_u_c_h incremented the exit
       code if --cc was specified and the file did not exist. This volume of
       POSIX.1-2008 requires exit status zero if no errors occur.

       In previous version of the standard, if at least two operands are
       specified, and the first operand is an eight or ten-digit decimal
       integer, the first operand was assumed to be a _d_a_t_e___t_i_m_e operand. This
       usage was removed in this version of the standard since it had been
       marked obsolescent previously.

       The --dd _d_a_t_e___t_i_m_e format is an ISO 8601:2004 standard complete
       representation of date and time extended format with an optional
       decimal point or <comma> followed by a string of digits following the
       seconds portion to specify fractions of a second. It is not necessary
       to recognize ""[[++//--]]hhhh::mmmm"" and ""[[++//--]]hhhh"" to specify timezones other than
       local time and UTC. The _T time designator in the ISO 8601:2004 standard
       extended format may be replaced by <space>.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _d_a_t_e

       The Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _4_._1_5, _S_e_c_o_n_d_s
       _S_i_n_c_e _t_h_e _E_p_o_c_h, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2,
       _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, <<ssyyss__ssttaatt..hh>>

       The System Interfaces volume of POSIX.1-2008, _c_r_e_a_t(), _f_u_t_i_m_e_n_s(),
       _t_i_m_e(), _u_t_i_m_e()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                             TOUCH(1)
