futimesat(2)

1utimes(2)                        System Calls                        utimes(2)
2
3
4

NAME

6       utimes, futimesat - set file access and modification times
7

SYNOPSIS

9       #include <sys/time.h>
10
11       int utimes(const char *path, const struct timeval times[2]);
12
13
14       int futimesat(int fildes, const char *path,
15            const struct timeval times[2]);
16
17

DESCRIPTION

19       The  utimes()  function  sets  the access and modification times of the
20       file pointed to by the path argument to the value of  the  times  argu‐
21       ment. It allows time specifications accurate to the microsecond.
22
23
24       The  futimesat() function also sets access and modification times.  See
25       fsattr(5). If path  is  a  relative  path  name,  however,  futimesat()
26       resolves  the path relative to the fildes argument rather than the cur‐
27       rent working directory.  If fildes  is  set  to  AT_FDCWD,  defined  in
28       <fcntl.h>,  futimesat() resolves the path relative to the current work‐
29       ing directory.  If path is a null pointer, futimesat() sets the  access
30       and  modification  times  on  the file referenced by fildes. The fildes
31       argument is ignored even when futimesat() is provided with an  absolute
32       path.
33
34
35       The  times  argument is an array of timeval structures. The first array
36       member represents the date and time of last access, and the second mem‐
37       ber  represents  the  date and time of last modification.  The times in
38       the timeval structure are measured in seconds  and  microseconds  since
39       the Epoch, although rounding toward the nearest second may occur.
40
41
42       If  the  times  argument is a null pointer, the access and modification
43       times of the file are set to the current time.  The effective  user  ID
44       of  the process must be the same as the owner of the file, or must have
45       write access to the file or the {PRIV_FILE_OWNER} privilege to use this
46       call  in  this  manner. Upon completion, utimes() will mark the time of
47       the last file status change, st_ctime, for update.
48

RETURN VALUES

50       Upon successful completion, 0 is returned.  Otherwise, −1 is  returned,
51       errno  is  set  to  indicate  the error, and the file times will not be
52       affected.
53

ERRORS

55       The utimes() and futimesat() functions will fail if:
56
57       EACCES          Search permission is denied by a component of the  path
58                       prefix; or the times argument is a null pointer and the
59                       effective user ID of the process  does  not  match  the
60                       owner of the file and write access is denied.
61
62
63       EFAULT          The  path  or  times  argument  points  to  an  illegal
64                       address. For futimesat(), path  might  have  the  value
65                       NULL if the fildes argument refers to a valid open file
66                       descriptor.
67
68
69       EINTR           A  signal  was  caught  during  the  execution  of  the
70                       utimes() function.
71
72
73       EINVAL          The  number of microseconds specified in one or both of
74                       the timeval structures pointed to by times was  greater
75                       than or equal to 1,000,000 or less than 0.
76
77
78       EIO             An  I/O error occurred while reading from or writing to
79                       the file system.
80
81
82       ELOOP           Too many symbolic links were encountered  in  resolving
83                       path.
84
85
86       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX} or a
87                       pathname component is longer than {NAME_MAX}.
88
89
90       ENOLINK         The path argument points to a remote  machine  and  the
91                       link to that machine is no longer active.
92
93
94       ENOENT          A  component  of path does not name an existing file or
95                       path is an empty string.
96
97
98       ENOTDIR         A component of the path prefix is not  a  directory  or
99                       the  path  argument is relative and the fildes argument
100                       is not AT_FDCWD or does not refer to a valid directory.
101
102
103       EPERM           The times argument is not a null pointer and the  call‐
104                       ing process's effective user ID has write access to the
105                       file but does not match the owner of the file  and  the
106                       calling  process  does  not have the appropriate privi‐
107                       leges.
108
109
110       EROFS           The file system containing the file is read-only.
111
112
113
114       The utimes() and futimesat() functions may fail if:
115
116       ENAMETOOLONG    Path name resolution of a  symbolic  link  produced  an
117                       intermediate result whose length exceeds {PATH_MAX}.
118
119

ATTRIBUTES

121       See attributes(5) for descriptions of the following attributes:
122
123
124
125
126       ┌─────────────────────────────┬─────────────────────────────┐
127       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
128       ├─────────────────────────────┼─────────────────────────────┤
129       │Interface Stability          │Committed                    │
130       ├─────────────────────────────┼─────────────────────────────┤
131       │Standard                     │See below.                   │
132       └─────────────────────────────┴─────────────────────────────┘
133
134
135       For utimes(), see standards(5).
136

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO