UTIMES(2) System Calls UTIMES(2) NNAAMMEE utimes, futimesat - set file access and modification times SSYYNNOOPPSSIISS #include iinntt uuttiimmeess(ccoonnsstt cchhaarr **_p_a_t_h, ccoonnsstt ssttrruucctt ttiimmeevvaall _t_i_m_e_s[2]); iinntt ffuuttiimmeessaatt(iinntt _f_i_l_d_e_s, ccoonnsstt cchhaarr **_p_a_t_h, ccoonnsstt ssttrruucctt ttiimmeevvaall _t_i_m_e_s[2]); #include iinntt ffuuttiimmeennss(iinntt _f_i_l_e_d_e_s, ccoonnsstt ttiimmeessppeecc__tt _n_s_t_i_m_e_s_[_2_]); iinntt uuttiimmeennssaatt(iinntt _f_i_l_e_d_e_s, ccoonnsstt cchhaarr **_p_a_t_h, ccoonnsstt ttiimmeessppeecc__tt _n_s_t_i_m_e_s_[_2_], iinntt _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The uuttiimmeess(()) function sets the access and modification times of the file pointed to by the _p_a_t_h argument to the value of the _t_i_m_e_s argument. It allows time specifications accurate to the microsecond. The ffuuttiimmeessaatt(()) function also sets access and modification times. See ffssaattttrr(5). If _p_a_t_h is a relative path name, however, ffuuttiimmeessaatt(()) resolves the path relative to the _f_i_l_d_e_s argument rather than the current working directory. If _f_i_l_d_e_s is set to AATT__FFDDCCWWDD, defined in , ffuuttiimmeessaatt(()) resolves the path relative to the current working directory. If _p_a_t_h is a null pointer, ffuuttiimmeessaatt(()) sets the access and modification times on the file referenced by _f_i_l_d_e_s. The _f_i_l_d_e_s argument is ignored even when ffuuttiimmeessaatt(()) is provided with an absolute path. The _t_i_m_e_s argument is an array of ttiimmeevvaall 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 ttiimmeevvaall structure are measured in seconds and microseconds since the Epoch, although rounding toward the nearest second may occur. If the _t_i_m_e_s argument is a null pointer, the access and modification times of the file are set to the current time. The effective user IIDD of the process must be the same as the owner of the file, or must have write access to the file or the {PPRRIIVV__FFIILLEE__OOWWNNEERR} privilege to use this call in this manner. Upon completion, uuttiimmeess(()) will mark the time of the last file status change, sstt__ccttiimmee, for update. The ffuuttiimmeennss(()) and uuttiimmeennssaatt(()) functions also set access and modification times; however, instead of taking ssttrruucctt ttiimmeevvaall, they take ttiimmeessppeecc__tt which allows for nanosecond granularity. The ffuuttiimmeennss(()) function sets the access and modification times on the file descriptor referenced by _f_i_l_e_d_e_s. The uuttiimmeennssaatt(()) function determines the file to set the access and modification times in an similar way to ffuutteemmssaatt(()). If the argument _p_a_t_h is an absolute path, then the argument _f_i_l_e_d_e_s is ignored; otherwise, _p_a_t_h is interpreted as a path relative to the directory specified by _f_i_l_e_d_e_s. If _f_i_l_e_d_e_s is set to AATT__FFDDCCWWDD, then _p_a_t_h is resolved relative to the current working directory. The behavior when encountering symbolic links may be controlled by the value of the _f_l_a_g argument. If the value of flag is the constant AATT__SSYYMMLLIINNKK__NNOOFFOOLLLLOOWW, then when a symbolic link is encountered while resolving a path, it will not be followed. Otherwise, the value of _f_l_a_g should be 00. RREETTUURRNN VVAALLUUEESS Upon successful completion, 00 is returned. Otherwise, --11 is returned, eerrrrnnoo is set to indicate the error, and the file times will not be affected. EERRRROORRSS The uuttiimmeess(()), ffuuttiimmeessaatt(()), ffuuttiimmeennss(()), and uuttiimmeennssaatt(()) functions will fail if: EEAACCCCEESS Search permission is denied by a component of the path prefix; or the _t_i_m_e_s argument is a null pointer and the effective user IIDD of the process does not match the owner of the file and write access is denied. EEFFAAUULLTT The _p_a_t_h or _t_i_m_e_s argument points to an illegal address. For ffuuttiimmeessaatt(()), _p_a_t_h might have the value _N_U_L_L if the _f_i_l_d_e_s argument refers to a valid open file descriptor. EEIINNTTRR A signal was caught during the execution of the uuttiimmeess(()), ffuuttiimmeessaatt(()), ffuuttiimmeennss(()), or uuttiimmeennssaatt(()) functions. EEIINNVVAALL The number of microseconds specified in one or both of the ttiimmeevvaall structures pointed to by _t_i_m_e_s was greater than or equal to 1,000,000 or less than 0. The number of nanoseconds specified in one or both of the ttiimmeessppeecc__tt structures pointed to by _n_s_t_i_m_e_s was greater than or equal to 1,000,000,000 or less than 0. EEIIOO An I/O error occurred while reading from or writing to the file system. EELLOOOOPP Too many symbolic links were encountered in resolving _p_a_t_h. EENNAAMMEETTOOOOLLOONNGG The length of the _p_a_t_h argument exceeds {_P_A_T_H___M_A_X} or a pathname component is longer than {_N_A_M_E___M_A_X}. EENNOOLLIINNKK The _p_a_t_h argument points to a remote machine and the link to that machine is no longer active. 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 is not a directory or the _p_a_t_h argument is relative and the _f_i_l_d_e_s argument is not AATT__FFDDCCWWDD or does not refer to a valid directory. EEPPEERRMM The _t_i_m_e_s argument is not a null pointer and the calling process's effective user IIDD has write access to the file but does not match the owner of the file and the calling process does not have the appropriate privileges. EERROOFFSS The file system containing the file is read-only. The uuttiimmeess(()), ffuuttiimmeessaatt(()), and uuttiimmeennssaatt(()) functions may fail if: EENNAAMMEETTOOOOLLOONNGG Path name resolution of a symbolic link produced an intermediate result whose length exceeds {_P_A_T_H___M_A_X}. AATTTTRRIIBBUUTTEESS See aattttrriibbuutteess(5) for descriptions of the following attributes: +--------------------+-----------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------+ |Interface Stability | Committed | +--------------------+-----------------+ |Standard | See below. | +--------------------+-----------------+ For uuttiimmeess(()), uuttiimmeennssaatt(()) and ffuuttiimmeennssaatt(()), see ssttaannddaarrddss(5). SSEEEE AALLSSOO ffuuttiimmeennss(2), ssttaatt(2), uuttiimmee(2), aattttrriibbuutteess(5), ffssaattttrr(5), ssttaannddaarrddss(5) December 20, 2014 UTIMES(2)