FUTIMENS(3)                POSIX Programmer's Manual               FUTIMENS(3)



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
       futimens, utimensat, utimes -- set file access and modification times

SSYYNNOOPPSSIISS
       #include <sys/stat.h>

       int futimens(int _f_d, const struct timespec _t_i_m_e_s[2]);

       #include <fcntl.h>

       int utimensat(int _f_d, const char *_p_a_t_h, const struct timespec _t_i_m_e_s[2],
           int _f_l_a_g);

       #include <sys/time.h>

       int utimes(const char *_p_a_t_h, const struct timeval _t_i_m_e_s[2]);

DDEESSCCRRIIPPTTIIOONN
       The _f_u_t_i_m_e_n_s() and _u_t_i_m_e_n_s_a_t() functions shall set the access and
       modification times of a file to the values of the _t_i_m_e_s argument. The
       _f_u_t_i_m_e_n_s() function changes the times of the file associated with the
       file descriptor _f_d.  The _u_t_i_m_e_n_s_a_t() function changes the times of the
       file pointed to by the _p_a_t_h argument, relative to the directory
       associated with the file descriptor _f_d.  Both functions allow time
       specifications accurate to the nanosecond.

       For _f_u_t_i_m_e_n_s() and _u_t_i_m_e_n_s_a_t(), the _t_i_m_e_s argument is an array of two
       ttiimmeessppeecc structures. The first array member represents the date and
       time of last access, and the second member represents the date and time
       of last modification. The times in the ttiimmeessppeecc structure are measured
       in seconds and nanoseconds since the Epoch. The file's relevant
       timestamp shall be set to the greatest value supported by the file
       system that is not greater than the specified time.

       If the _t_v___n_s_e_c field of a ttiimmeessppeecc structure has the special value
       UTIME_NOW, the file's relevant timestamp shall be set to the greatest
       value supported by the file system that is not greater than the current
       time. If the _t_v___n_s_e_c field has the special value UTIME_OMIT, the file's
       relevant timestamp shall not be changed. In either case, the _t_v___s_e_c
       field shall be ignored.

       If the _t_i_m_e_s argument is a null pointer, both the access and
       modification timestamps shall be set to the greatest value supported by
       the file system that is not greater than the current time. If
       _u_t_i_m_e_n_s_a_t() is passed a relative path in the _p_a_t_h argument, the file to
       be used shall be relative to the directory associated with the file
       descriptor _f_d instead of the current working directory. If the access
       mode of the open file description associated with the file descriptor
       is not O_SEARCH, the function shall check whether directory searches
       are permitted using the current permissions of the directory underlying
       the file descriptor. If the access mode is O_SEARCH, the function shall
       not perform the check.

       If _u_t_i_m_e_n_s_a_t() is passed the special value AT_FDCWD in the _f_d
       parameter, the current working directory shall be used.

       Only a process with the effective user ID equal to the user ID of the
       file, or with write access to the file, or with appropriate privileges
       may use _f_u_t_i_m_e_n_s() or _u_t_i_m_e_n_s_a_t() with a null pointer as the _t_i_m_e_s
       argument or with both _t_v___n_s_e_c fields set to the special value
       UTIME_NOW. Only a process with the effective user ID equal to the user
       ID of the file or with appropriate privileges may use _f_u_t_i_m_e_n_s() or
       _u_t_i_m_e_n_s_a_t() with a non-null _t_i_m_e_s argument that does not have both
       _t_v___n_s_e_c fields set to UTIME_NOW and does not have both _t_v___n_s_e_c fields
       set to UTIME_OMIT. If both _t_v___n_s_e_c fields are set to UTIME_OMIT, no
       ownership or permissions check shall be performed for the file, but
       other error conditions may still be detected (including [[EEAACCCCEESS]] errors
       related to the path prefix).

       Values for the _f_l_a_g argument of _u_t_i_m_e_n_s_a_t() are constructed by a
       bitwise-inclusive OR of flags from the following list, defined in
       _<_f_c_n_t_l_._h_>:

       AT_SYMLINK_NOFOLLOW
             If _p_a_t_h names a symbolic link, then the access and modification
             times of the symbolic link are changed.

       Upon successful completion, _f_u_t_i_m_e_n_s() and _u_t_i_m_e_n_s_a_t() shall mark the
       last file status change timestamp for update, with the exception that
       if both _t_v___n_s_e_c fields are set to UTIME_OMIT, the file status change
       timestamp need not be marked for update.

       The _u_t_i_m_e_s() function shall be equivalent to the _u_t_i_m_e_n_s_a_t() function
       with the special value AT_FDCWD as the _f_d argument and the _f_l_a_g
       argument set to zero, except that the _t_i_m_e_s argument is a ttiimmeevvaall
       structure rather than a ttiimmeessppeecc structure, and accuracy is only to the
       microsecond, not nanosecond, and rounding towards the nearest second
       may occur.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, these functions shall return 0.  Otherwise,
       these functions shall return -1 and set _e_r_r_n_o to indicate the error. If
       -1 is returned, the file times shall not be affected.

EERRRROORRSS
       These functions shall fail if:

       EEAACCCCEESS The _t_i_m_e_s argument is a null pointer, or both _t_v___n_s_e_c values are
              UTIME_NOW, and the effective user ID of the process does not
              match the owner of the file and write access is denied.

       EEIINNVVAALL Either of the _t_i_m_e_s argument structures specified a _t_v___n_s_e_c
              value that was neither UTIME_NOW nor UTIME_OMIT, and was a value
              less than zero or greater than or equal to 1000 million.

       EEIINNVVAALL A new file timestamp would be a value whose _t_v___s_e_c component is
              not a value supported by the file system.

       EEPPEERRMM  The _t_i_m_e_s argument is not a null pointer, does not have both
              _t_v___n_s_e_c fields set to UTIME_NOW, does not have both _t_v___n_s_e_c
              fields set to UTIME_OMIT, the calling process' effective user ID
              does not match the owner of the file, and the calling process
              does not have appropriate privileges.

       EERROOFFSS  The file system containing the file is read-only.

       The _f_u_t_i_m_e_n_s() function shall fail if:

       EEBBAADDFF  The _f_d argument is not a valid file descriptor.

       The _u_t_i_m_e_n_s_a_t() function shall fail if:

       EEAACCCCEESS The access mode of the open file description associated with _f_d
              is not O_SEARCH and the permissions of the directory underlying
              _f_d do not permit directory searches.

       EEBBAADDFF  The _p_a_t_h argument does not specify an absolute path and the _f_d
              argument is neither AT_FDCWD nor a valid file descriptor open
              for reading or searching.

       EENNOOTTDDIIRR
              The _p_a_t_h argument is not an absolute path and _f_d is a file
              descriptor associated with a non-directory file.

       The _u_t_i_m_e_n_s_a_t() and _u_t_i_m_e_s() functions shall fail if:

       EEAACCCCEESS Search permission is denied by a component of the path prefix.

       EELLOOOOPP  A loop exists in symbolic links encountered during resolution of
              the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a component of a pathname is longer than
              {NAME_MAX}.

       EENNOOEENNTT A component of _p_a_t_h does not name an existing file or _p_a_t_h is an
              empty string.

       EENNOOTTDDIIRR
              A component of the path prefix names an existing file that is
              neither a directory nor a symbolic link to a directory, or the
              _p_a_t_h argument contains at least one non-<slash> character and
              ends with one or more trailing <slash> characters and the last
              pathname component names an existing file that is neither a
              directory nor a symbolic link to a directory.

       The _u_t_i_m_e_n_s_a_t() and _u_t_i_m_e_s() functions may fail if:

       EELLOOOOPP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              The length of a pathname exceeds {PATH_MAX}, or pathname
              resolution of a symbolic link produced an intermediate result
              with a length that exceeds {PATH_MAX}.

       The _u_t_i_m_e_n_s_a_t() function may fail if:

       EEIINNVVAALL The value of the _f_l_a_g argument is not valid.

       _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_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       The purpose of the _u_t_i_m_e_n_s_a_t() function is to set the access and
       modification time of files in directories other than the current
       working directory without exposure to race conditions. Any part of the
       path of a file could be changed in parallel to a call to _u_t_i_m_e_s(),
       resulting in unspecified behavior. By opening a file descriptor for the
       target directory and using the _u_t_i_m_e_n_s_a_t() function it can be
       guaranteed that the changed file is located relative to the desired
       directory.

       The standard developers considered including a special case for the
       permissions required by _u_t_i_m_e_n_s_a_t() when one _t_v___n_s_e_c field is UTIME_NOW
       and the other is UTIME_OMIT. One possibility would be to include this
       case in with the cases where _t_i_m_e_s is a null pointer or both fields are
       UTIME_NOW, where the call is allowed if the process has write
       permission for the file. However, associating write permission with an
       update to just the last data access timestamp (which is normally
       updated by _r_e_a_d()) did not seem appropriate. The other possibility
       would be to specify that this one case is allowed if the process has
       read permission, but this was felt to be too great a departure from the
       _u_t_i_m_e() and _u_t_i_m_e_s() functions on which _u_t_i_m_e_n_s_a_t() is based. If an
       application needs to set the last data access timestamp to the current
       time for a file on which it has read permission but is not the owner,
       it can do so by opening the file, reading one or more bytes (or reading
       a directory entry, if the file is a directory), and then closing it.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _r_e_a_d(), _u_t_i_m_e()

       The Base Definitions volume of POSIX.1-2017, <<ffccnnttll..hh>>, <<ssyyss__ssttaatt..hh>>,
       <<ssyyss__ttiimmee..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute 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.opengroup.org/unix/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                  2017                          FUTIMENS(3)
