Debian Codegraph @

upstream/debian-unstable/man2/utime.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH utime 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 utime, utimes \- change file last access and modification times
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <utime.h>
15 .P
16 .BI "int utime(const char *" path ,
17 .BI " const struct utimbuf *_Nullable " times );
18 .P
19 .B #include <sys/time.h>
20 .P
21 .BI "int utimes(const char *" path ,
22 .BI " const struct timeval " times "[_Nullable 2]);"
23 .fi
24 .SH DESCRIPTION
25 .B Note:
26 modern applications may prefer to use the interfaces described in
27 .BR utimensat (2).
28 .P
29 The
30 .BR utime ()
31 system call
32 changes the access and modification times of the inode specified by
33 .I path
34 to the
35 .IR actime " and " modtime
36 fields of
37 .I times
38 respectively.
39 The status change time (ctime) will be set to the current time, even if the
40 other time stamps don't actually change.
41 .P
42 If
43 .I times
44 is NULL, then the access and modification times of the file are set
45 to the current time.
46 .P
47 Changing timestamps is permitted when: either
48 the process has appropriate privileges,
49 or the effective user ID equals the user ID
50 of the file, or
51 .I times
52 is NULL and the process has write permission for the file.
53 .P
54 The
55 .I utimbuf
56 structure is:
57 .P
58 .in +4n
59 .EX
60 struct utimbuf {
61 time_t actime; /* access time */
62 time_t modtime; /* modification time */
63 };
64 .EE
65 .in
66 .P
67 The
68 .BR utime ()
69 system call
70 allows specification of timestamps with a resolution of 1 second.
71 .P
72 The
73 .BR utimes ()
74 system call
75 is similar, but the
76 .I times
77 argument refers to an array rather than a structure.
78 The elements of this array are
79 .I timeval
80 structures, which allow a precision of 1 microsecond for specifying timestamps.
81 The
82 .I timeval
83 structure is:
84 .P
85 .in +4n
86 .EX
87 struct timeval {
88 long tv_sec; /* seconds */
89 long tv_usec; /* microseconds */
90 };
91 .EE
92 .in
93 .P
94 .I times[0]
95 specifies the new access time, and
96 .I times[1]
97 specifies the new modification time.
98 If
99 .I times
100 is NULL, then analogously to
101 .BR utime (),
102 the access and modification times of the file are
103 set to the current time.
104 .SH RETURN VALUE
105 On success, zero is returned.
106 On error, \-1 is returned, and
107 .I errno
108 is set to indicate the error.
109 .SH ERRORS
110 .TP
111 .B EACCES
112 Search permission is denied for one of the directories in
113 the path prefix of
114 .I path
115 (see also
116 .BR path_resolution (7)).
117 .TP
118 .B EACCES
119 .I times
120 is NULL,
121 the caller's effective user ID does not match the owner of the file,
122 the caller does not have write access to the file,
123 and the caller is not privileged
124 (Linux: does not have either the
125 .B CAP_DAC_OVERRIDE
126 or the
127 .B CAP_FOWNER
128 capability).
129 .TP
130 .B EFAULT
131 .I path
132 points to an invalid address.
133 .TP
134 .B ENOENT
135 .I path
136 does not exist.
137 .TP
138 .B EPERM
139 .I times
140 is not NULL,
141 the caller's effective UID does not match the owner of the file,
142 and the caller is not privileged
143 (Linux: does not have the
144 .B CAP_FOWNER
145 capability).
146 .TP
147 .B EROFS
148 .I path
149 resides on a read-only filesystem.
150 .SH STANDARDS
151 .TP
152 .BR utime ()
153 None.
154 .TP
155 .BR utimes ()
156 POSIX.1-2024.
157 .SH HISTORY
158 .TP
159 .BR utime ()
160 SVr4, POSIX.1-2001.
161 Obsoleted in POSIX.1-2008.
162 Removed in POSIX.1-2024.
163 .TP
164 .BR utimes ()
165 4.3BSD, POSIX.1-2001.
166 .SH NOTES
167 Linux does not allow changing the timestamps on an immutable file,
168 or setting the timestamps to something other than the current time
169 on an append-only file.
170 .\"
171 .\" In libc4 and libc5,
172 .\" .BR utimes ()
173 .\" is just a wrapper for
174 .\" .BR utime ()
175 .\" and hence does not allow a subsecond resolution.
176 .SH SEE ALSO
177 .BR chattr (1),
178 .BR touch (1),
179 .BR futimesat (2),
180 .BR stat (2),
181 .BR utimensat (2),
182 .BR futimens (3),
183 .BR futimes (3),
184 .BR inode (7)