[apple/xnu.git] / bsd / man / man2 / utimensat.2

.\"	$NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
.\"
.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\" Copyright (c) 2012, Jilles Tjoelker
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)utimes.2	8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd January 17, 2016
.Dt UTIMENSAT 2
.Os
.Sh NAME
.Nm futimens ,
.Nm utimensat
.Nd set file access and modification times
.Sh SYNOPSIS
.In sys/stat.h
.Ft int
.Fn futimens "int fd" "const struct timespec times[2]"
.Ft int
.Fo utimensat
.Fa "int fd"
.Fa "const char *path"
.Fa "const struct timespec times[2]"
.Fa "int flag"
.Fc
.Sh DESCRIPTION
The access and modification times of the file named by
.Fa path
or referenced by
.Fa fd
are changed as specified by the argument
.Fa times .
The inode-change-time of the file is set to the current time.
.Pp
If
.Fa path
specifies a relative path,
it is relative to the current working directory if
.Fa fd
is
.Dv AT_FDCWD
and otherwise relative to the directory associated with the file descriptor
.Fa fd .
.Pp
The
.Va tv_nsec
field of a
.Vt timespec
structure
can be set to the special value
.Dv UTIME_NOW
to set the current time, or to
.Dv UTIME_OMIT
to leave the time unchanged.
In either case, the
.Va tv_sec
field is ignored.
.Pp
If
.Fa times
is
.No non- Ns Dv NULL ,
it is assumed to point to an array of two timespec structures.
The access time is set to the value of the first element, and the
modification time is set to the value of the second element.
If
.Fa times
is
.Dv NULL ,
this is equivalent to passing
a pointer to an array of two timespec structures
with both
.Va tv_nsec
fields set to
.Dv UTIME_NOW .
.Pp
If both
.Va tv_nsec
fields are
.Dv UTIME_OMIT ,
the timestamps remain unchanged and
no permissions are needed for the file itself,
although search permissions may be required for the path prefix.
The call may or may not succeed if the named file does not exist.
.Pp
If both
.Va tv_nsec
fields are
.Dv UTIME_NOW ,
the caller must be the owner of the file, have permission to
write the file, or be the super-user.
.Pp
For all other values of the timestamps,
the caller must be the owner of the file or be the super-user.
.Pp
The values for the
.Fa flag
argument of the
.Fn utimensat
system call
are constructed by a bitwise-inclusive OR of flags from the following list,
defined in
.In fcntl.h :
.Bl -tag -width indent
.It Dv AT_SYMLINK_NOFOLLOW
If
.Fa path
names a symbolic link, the symbolic link's times are changed.
By default,
.Fn utimensat
changes the times of the file referenced by the symbolic link.
.El
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
These system calls will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
The
.Fa times
argument is
.Dv NULL ,
or both
.Va tv_nsec
values are
.Dv UTIME_NOW ,
and the effective user ID of the process does not
match the owner of the file, and is not the super-user, and write
access is denied.
.It Bq Er EINVAL
The
.Va tv_nsec
component of at least one of the values specified by the
.Fa times
argument has a value less than 0 or greater than 999999999 and is not equal to
.Dv UTIME_NOW
or
.Dv UTIME_OMIT .
.It Bq Er EIO
An I/O error occurred while reading or writing the affected inode.
.It Bq Er EPERM
The
.Fa times
argument is not
.Dv NULL
nor are both
.Va tv_nsec
values
.Dv UTIME_NOW ,
nor are both
.Va tv_nsec
values
.Dv UTIME_OMIT
and the calling process's effective user ID
does not match the owner of the file and is not the super-user.
.It Bq Er EPERM
The named file has its immutable or append-only flag set, see the
.Xr chflags 2
manual page for more information.
.It Bq Er EROFS
The file system containing the file is mounted read-only.
.El
.Pp
The
.Fn futimens
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa fd
argument
does not refer to a valid descriptor.
.El
.Pp
The
.Fn utimensat
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
.It Bq Er EBADF
The
.Fa path
argument does not specify an absolute path and the
.Fa fd
argument is neither
.Dv AT_FDCWD
nor a valid file descriptor.
.It Bq Er EFAULT
The
.Fa path
argument
points outside the process's allocated address space.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv NAME_MAX
characters, or an entire path name exceeded
.Dv PATH_MAX
characters.
.It Bq Er ENOENT
The named file does not exist.
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er ENOTDIR
The
.Fa path
argument is not an absolute path and
.Fa fd
is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.El
.Sh SEE ALSO
.Xr chflags 2 ,
.Xr stat 2 ,
.Xr symlink 2 ,
.Xr utimes 2 ,
.Xr utime 3 ,
.Xr symlink 7
.Sh STANDARDS
The
.Fn futimens
and
.Fn utimensat
system calls are expected to conform to
.St -p1003.1-2008 .
Commit	Line	Data
5ba3f43e A	1	.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
	2	.\"
	3	.\" Copyright (c) 1990, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\" Copyright (c) 2012, Jilles Tjoelker
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. Neither the name of the University nor the names of its contributors
	16	.\" may be used to endorse or promote products derived from this software
	17	.\" without specific prior written permission.
	18	.\"
	19	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	20	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	21	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	22	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	23	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	24	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	25	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	26	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	27	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	28	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	29	.\" SUCH DAMAGE.
	30	.\"
	31	.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93
	32	.\" $FreeBSD$
	33	.\"
	34	.Dd January 17, 2016
	35	.Dt UTIMENSAT 2
	36	.Os
	37	.Sh NAME
	38	.Nm futimens ,
	39	.Nm utimensat
	40	.Nd set file access and modification times
	41	.Sh SYNOPSIS
	42	.In sys/stat.h
	43	.Ft int
	44	.Fn futimens "int fd" "const struct timespec times[2]"
	45	.Ft int
	46	.Fo utimensat
	47	.Fa "int fd"
	48	.Fa "const char *path"
	49	.Fa "const struct timespec times[2]"
	50	.Fa "int flag"
	51	.Fc
	52	.Sh DESCRIPTION
	53	The access and modification times of the file named by
	54	.Fa path
	55	or referenced by
	56	.Fa fd
	57	are changed as specified by the argument
	58	.Fa times .
	59	The inode-change-time of the file is set to the current time.
	60	.Pp
	61	If
	62	.Fa path
	63	specifies a relative path,
	64	it is relative to the current working directory if
65	.Fa fd
66	is
67	.Dv AT_FDCWD
68	and otherwise relative to the directory associated with the file descriptor
69	.Fa fd .
70	.Pp
71	The
72	.Va tv_nsec
73	field of a
74	.Vt timespec
75	structure
76	can be set to the special value
77	.Dv UTIME_NOW
78	to set the current time, or to
79	.Dv UTIME_OMIT
80	to leave the time unchanged.
81	In either case, the
82	.Va tv_sec
83	field is ignored.
84	.Pp
85	If
86	.Fa times
87	is
88	.No non- Ns Dv NULL ,
89	it is assumed to point to an array of two timespec structures.
90	The access time is set to the value of the first element, and the
91	modification time is set to the value of the second element.
92	If
93	.Fa times
94	is
95	.Dv NULL ,
96	this is equivalent to passing
97	a pointer to an array of two timespec structures
98	with both
99	.Va tv_nsec
100	fields set to
101	.Dv UTIME_NOW .
102	.Pp
103	If both
104	.Va tv_nsec
105	fields are
106	.Dv UTIME_OMIT ,
107	the timestamps remain unchanged and
108	no permissions are needed for the file itself,
109	although search permissions may be required for the path prefix.
110	The call may or may not succeed if the named file does not exist.
111	.Pp
112	If both
113	.Va tv_nsec
114	fields are
115	.Dv UTIME_NOW ,
116	the caller must be the owner of the file, have permission to
117	write the file, or be the super-user.
118	.Pp
119	For all other values of the timestamps,
120	the caller must be the owner of the file or be the super-user.
121	.Pp
122	The values for the
123	.Fa flag
124	argument of the
125	.Fn utimensat
126	system call
127	are constructed by a bitwise-inclusive OR of flags from the following list,
128	defined in
129	.In fcntl.h :
130	.Bl -tag -width indent
131	.It Dv AT_SYMLINK_NOFOLLOW
132	If
133	.Fa path
134	names a symbolic link, the symbolic link's times are changed.
135	By default,
136	.Fn utimensat
137	changes the times of the file referenced by the symbolic link.
138	.El
139	.Sh RETURN VALUES
140	.Rv -std
141	.Sh ERRORS
142	These system calls will fail if:
143	.Bl -tag -width Er
144	.It Bq Er EACCES
145	The
146	.Fa times
147	argument is
148	.Dv NULL ,
149	or both
150	.Va tv_nsec
151	values are
152	.Dv UTIME_NOW ,
153	and the effective user ID of the process does not
154	match the owner of the file, and is not the super-user, and write
155	access is denied.
156	.It Bq Er EINVAL
157	The
158	.Va tv_nsec
159	component of at least one of the values specified by the
160	.Fa times
161	argument has a value less than 0 or greater than 999999999 and is not equal to
162	.Dv UTIME_NOW
163	or
164	.Dv UTIME_OMIT .
165	.It Bq Er EIO
166	An I/O error occurred while reading or writing the affected inode.
167	.It Bq Er EPERM
168	The
169	.Fa times
170	argument is not
171	.Dv NULL
172	nor are both
173	.Va tv_nsec
174	values
175	.Dv UTIME_NOW ,
176	nor are both
177	.Va tv_nsec
178	values
179	.Dv UTIME_OMIT
180	and the calling process's effective user ID
181	does not match the owner of the file and is not the super-user.
182	.It Bq Er EPERM
183	The named file has its immutable or append-only flag set, see the
184	.Xr chflags 2
185	manual page for more information.
186	.It Bq Er EROFS
187	The file system containing the file is mounted read-only.
188	.El
189	.Pp
190	The
191	.Fn futimens
192	system call
193	will fail if:
194	.Bl -tag -width Er
195	.It Bq Er EBADF
196	The
197	.Fa fd
198	argument
199	does not refer to a valid descriptor.
200	.El
201	.Pp
202	The
203	.Fn utimensat
204	system call
205	will fail if:
206	.Bl -tag -width Er
207	.It Bq Er EACCES
208	Search permission is denied for a component of the path prefix.
209	.It Bq Er EBADF
210	The
211	.Fa path
212	argument does not specify an absolute path and the
213	.Fa fd
214	argument is neither
215	.Dv AT_FDCWD
216	nor a valid file descriptor.
217	.It Bq Er EFAULT
218	The
219	.Fa path
220	argument
221	points outside the process's allocated address space.
222	.It Bq Er ELOOP
223	Too many symbolic links were encountered in translating the pathname.
224	.It Bq Er ENAMETOOLONG
225	A component of a pathname exceeded
226	.Dv NAME_MAX
227	characters, or an entire path name exceeded
228	.Dv PATH_MAX
229	characters.
230	.It Bq Er ENOENT
231	The named file does not exist.
232	.It Bq Er ENOTDIR
233	A component of the path prefix is not a directory.
234	.It Bq Er ENOTDIR
235	The
236	.Fa path
237	argument is not an absolute path and
238	.Fa fd
239	is neither
240	.Dv AT_FDCWD
241	nor a file descriptor associated with a directory.
242	.El
243	.Sh SEE ALSO
244	.Xr chflags 2 ,
245	.Xr stat 2 ,
246	.Xr symlink 2 ,
247	.Xr utimes 2 ,
248	.Xr utime 3 ,
249	.Xr symlink 7
250	.Sh STANDARDS
251	The
252	.Fn futimens
253	and
254	.Fn utimensat
255	system calls are expected to conform to
256	.St -p1003.1-2008 .