]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified by Michael Haardt <michael@moria.de> | |
26 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
27 | .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl> | |
c11b1abf | 28 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
29 | .\" Modified 2004-10-10 by Andries Brouwer <aeb@cwi.nl> |
30 | .\" | |
4b8c67d9 | 31 | .TH UTIME 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 32 | .SH NAME |
c18c0141 | 33 | utime, utimes \- change file last access and modification times |
fea681da MK |
34 | .SH SYNOPSIS |
35 | .nf | |
36 | .B #include <sys/types.h> | |
fea681da | 37 | .B #include <utime.h> |
68e4db0a | 38 | .PP |
42ab9eb9 | 39 | .BI "int utime(const char *" filename ", const struct utimbuf *" times ); |
68e4db0a | 40 | .PP |
fea681da | 41 | .B #include <sys/time.h> |
68e4db0a | 42 | .PP |
69b7b9e5 | 43 | .BI "int utimes(const char *" filename ", const struct timeval " times [2]); |
fea681da MK |
44 | .fi |
45 | .SH DESCRIPTION | |
bdc80a72 MK |
46 | .B Note: |
47 | modern applications may prefer to use the interfaces described in | |
48 | .BR utimensat (2). | |
efeece04 | 49 | .PP |
42ab9eb9 | 50 | The |
e511ffb6 | 51 | .BR utime () |
42ab9eb9 | 52 | system call |
fea681da MK |
53 | changes the access and modification times of the inode specified by |
54 | .I filename | |
55 | to the | |
56 | .IR actime " and " modtime | |
c13182ef | 57 | fields of |
04527fe5 | 58 | .I times |
fea681da | 59 | respectively. |
efeece04 | 60 | .PP |
fea681da | 61 | If |
42ab9eb9 | 62 | .I times |
fea681da MK |
63 | is NULL, then the access and modification times of the file are set |
64 | to the current time. | |
efeece04 | 65 | .PP |
c18c0141 | 66 | Changing timestamps is permitted when: either |
42ab9eb9 MK |
67 | the process has appropriate privileges, |
68 | or the effective user ID equals the user ID | |
fea681da | 69 | of the file, or |
42ab9eb9 MK |
70 | .I times |
71 | is NULL and the process has write permission for the file. | |
efeece04 | 72 | .PP |
fea681da MK |
73 | The |
74 | .I utimbuf | |
75 | structure is: | |
efeece04 | 76 | .PP |
bd191423 | 77 | .in +4n |
b8302363 | 78 | .EX |
fea681da | 79 | struct utimbuf { |
69b7b9e5 MK |
80 | time_t actime; /* access time */ |
81 | time_t modtime; /* modification time */ | |
fea681da | 82 | }; |
b8302363 | 83 | .EE |
bd191423 | 84 | .in |
efeece04 | 85 | .PP |
42ab9eb9 | 86 | The |
e511ffb6 | 87 | .BR utime () |
42ab9eb9 | 88 | system call |
c18c0141 | 89 | allows specification of timestamps with a resolution of 1 second. |
efeece04 | 90 | .PP |
42ab9eb9 | 91 | The |
e511ffb6 | 92 | .BR utimes () |
42ab9eb9 | 93 | system call |
3995da14 MK |
94 | is similar, but the |
95 | .I times | |
8846324a MK |
96 | argument refers to an array rather than a structure. |
97 | The elements of this array are | |
98 | .I timeval | |
99 | structures, which allow a precision of 1 microsecond for specifying timestamps. | |
fea681da MK |
100 | The |
101 | .I timeval | |
102 | structure is: | |
efeece04 | 103 | .PP |
bd191423 | 104 | .in +4n |
b8302363 | 105 | .EX |
fea681da | 106 | struct timeval { |
69b7b9e5 MK |
107 | long tv_sec; /* seconds */ |
108 | long tv_usec; /* microseconds */ | |
fea681da | 109 | }; |
b8302363 | 110 | .EE |
bd191423 | 111 | .in |
3995da14 MK |
112 | .PP |
113 | .IR times [0] | |
114 | specifies the new access time, and | |
115 | .IR times [1] | |
116 | specifies the new modification time. | |
117 | If | |
118 | .I times | |
119 | is NULL, then analogously to | |
120 | .BR utime (), | |
121 | the access and modification times of the file are | |
122 | set to the current time. | |
47297adb | 123 | .SH RETURN VALUE |
c13182ef MK |
124 | On success, zero is returned. |
125 | On error, \-1 is returned, and | |
fea681da MK |
126 | .I errno |
127 | is set appropriately. | |
128 | .SH ERRORS | |
129 | .TP | |
130 | .B EACCES | |
131 | Search permission is denied for one of the directories in | |
132 | the path prefix of | |
133 | .I path | |
134 | (see also | |
42ab9eb9 MK |
135 | .BR path_resolution (7)). |
136 | .TP | |
137 | .B EACCES | |
138 | .I times | |
139 | is NULL, | |
140 | the caller's effective user ID does not match the owner of the file, | |
141 | the caller does not have write access to the file, | |
142 | and the caller is not privileged | |
143 | (Linux: does not have either the | |
144 | .B CAP_DAC_OVERRIDE | |
145 | or the | |
146 | .B CAP_FOWNER | |
147 | capability). | |
fea681da MK |
148 | .TP |
149 | .B ENOENT | |
150 | .I filename | |
151 | does not exist. | |
152 | .TP | |
153 | .B EPERM | |
42ab9eb9 MK |
154 | .I times |
155 | is not NULL, | |
156 | the caller's effective UID does not match the owner of the file, | |
157 | and the caller is not privileged | |
158 | (Linux: does not have the | |
159 | .B CAP_FOWNER | |
160 | capability). | |
fea681da MK |
161 | .TP |
162 | .B EROFS | |
163 | .I path | |
9ee4a2b6 | 164 | resides on a read-only filesystem. |
47297adb | 165 | .SH CONFORMING TO |
2dd578fd MK |
166 | .BR utime (): |
167 | SVr4, POSIX.1-2001. | |
0524a4fc MK |
168 | POSIX.1-2008 marks |
169 | .BR utime () | |
170 | as obsolete. | |
ebbb532e | 171 | .PP |
2dd578fd | 172 | .BR utimes (): |
302ea013 | 173 | 4.3BSD, POSIX.1-2001. |
fea681da | 174 | .SH NOTES |
c18c0141 MK |
175 | Linux does not allow changing the timestamps on an immutable file, |
176 | or setting the timestamps to something other than the current time | |
fea681da | 177 | on an append-only file. |
ef4f4031 | 178 | .\" |
47709e55 MK |
179 | .\" In libc4 and libc5, |
180 | .\" .BR utimes () | |
181 | .\" is just a wrapper for | |
182 | .\" .BR utime () | |
183 | .\" and hence does not allow a subsecond resolution. | |
47297adb | 184 | .SH SEE ALSO |
fea681da | 185 | .BR chattr (1), |
2e3cf491 | 186 | .BR touch (1), |
22e3b8b1 | 187 | .BR futimesat (2), |
51fa356e | 188 | .BR stat (2), |
f09c8e98 | 189 | .BR utimensat (2), |
3e5c319e | 190 | .BR futimens (3), |
e6fc1596 MK |
191 | .BR futimes (3), |
192 | .BR inode (7) |