xref: /dragonfly/lib/libc/sys/utimensat.2 (revision 0720b42f) 
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.\" 4. 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 May 26, 2015
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 LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/stat.h
45.Ft int
46.Fn futimens "int fd" "const struct timespec times[2]"
47.Ft int
48.Fo utimensat
49.Fa "int fd"
50.Fa "const char *path"
51.Fa "const struct timespec times[2]"
52.Fa "int flags"
53.Fc
54.Sh DESCRIPTION
55The access and modification times of the file named by
56.Fa path
57or referenced by
58.Fa fd
59are changed as specified by the argument
60.Fa times .
61The inode-change-time of the file is set to the current time.
62.Pp
63If
64.Fa path
65specifies a relative path,
66it is relative to the current working directory if
67.Fa fd
68is
69.Dv AT_FDCWD
70and otherwise relative to the directory associated with the file descriptor
71.Fa fd .
72.Pp
73The
74.Va tv_nsec
75field of a
76.Vt timespec
77structure
78can be set to the special value
79.Dv UTIME_NOW
80to set the current time, or to
81.Dv UTIME_OMIT
82to leave the time unchanged.
83In either case, the
84.Va tv_sec
85field is ignored.
86.Pp
87If
88.Fa times
89is
90.No non- Ns Dv NULL ,
91it is assumed to point to an array of two timespec structures.
92The access time is set to the value of the first element, and the
93modification time is set to the value of the second element.
94If
95.Fa times
96is
97.Dv NULL ,
98this is equivalent to passing
99a pointer to an array of two timespec structures
100with both
101.Va tv_nsec
102fields set to
103.Dv UTIME_NOW .
104.Pp
105If both
106.Va tv_nsec
107fields are
108.Dv UTIME_OMIT ,
109the timestamps remain unchanged and
110no permissions are needed for the file itself,
111although search permissions may be required for the path prefix.
112The call may or may not succeed if the named file does not exist.
113.Pp
114If both
115.Va tv_nsec
116fields are
117.Dv UTIME_NOW ,
118the caller must be the owner of the file, have permission to
119write the file, or be the super-user.
120.Pp
121For all other values of the timestamps,
122the caller must be the owner of the file or be the super-user.
123.Pp
124The values for the
125.Fa flag
126argument of the
127.Fn utimensat
128system call
129are constructed by a bitwise-inclusive OR of flags from the following list,
130defined in
131.In fcntl.h :
132.Bl -tag -width indent
133.It Dv AT_SYMLINK_NOFOLLOW
134If
135.Fa path
136names a symbolic link, the symbolic link's times are changed.
137By default,
138.Fn utimensat
139changes the times of the file referenced by the symbolic link.
140.El
141.Sh RETURN VALUES
142.Rv -std
143.Sh ERRORS
144These system calls will fail if:
145.Bl -tag -width Er
146.It Bq Er EACCES
147The
148.Fa times
149argument is
150.Dv NULL ,
151or both
152.Va tv_nsec
153values are
154.Dv UTIME_NOW ,
155and the effective user ID of the process does not
156match the owner of the file, and is not the super-user, and write
157access is denied.
158.It Bq Er EFAULT
159The
160.Fa times
161argument
162points outside the process's allocated address space.
163.It Bq Er EINVAL
164The
165.Va tv_usec
166component of at least one of the values specified by the
167.Fa times
168argument has a value less than 0 or greater than 999999.
169.It Bq Er EIO
170An I/O error occurred while reading or writing the affected inode.
171.It Bq Er EPERM
172The
173.Fa times
174argument is not
175.Dv NULL
176nor are both
177.Va tv_nsec
178values
179.Dv UTIME_NOW ,
180nor are both
181.Va tv_nsec
182values
183.Dv UTIME_OMIT
184and the calling process's effective user ID
185does not match the owner of the file and is not the super-user.
186.It Bq Er EPERM
187The named file has its immutable or append-only flag set, see the
188.Xr chflags 2
189manual page for more information.
190.It Bq Er EROFS
191The file system containing the file is mounted read-only.
192.El
193.Pp
194The
195.Fn futimens
196system call
197will fail if:
198.Bl -tag -width Er
199.It Bq Er EBADF
200The
201.Fa fd
202argument
203does not refer to a valid descriptor.
204.El
205.Pp
206The
207.Fn utimensat
208system call
209will fail if:
210.Bl -tag -width Er
211.It Bq Er EACCES
212Search permission is denied for a component of the path prefix.
213.It Bq Er EBADF
214The
215.Fa path
216argument does not specify an absolute path and the
217.Fa fd
218argument is neither
219.Dv AT_FDCWD
220nor a valid file descriptor.
221.It Bq Er EFAULT
222The
223.Fa path
224argument
225points outside the process's allocated address space.
226.It Bq Er ELOOP
227Too many symbolic links were encountered in translating the pathname.
228.It Bq Er ENAMETOOLONG
229A component of a pathname exceeded
230.Dv NAME_MAX
231characters, or an entire path name exceeded
232.Dv PATH_MAX
233characters.
234.It Bq Er ENOENT
235The named file does not exist.
236.It Bq Er ENOTDIR
237A component of the path prefix is not a directory.
238.It Bq Er ENOTDIR
239The
240.Fa path
241argument is not an absolute path and
242.Fa fd
243is neither
244.Dv AT_FDCWD
245nor a file descriptor associated with a directory.
246.It Bq Er ENOTSUP
247The running kernel does not support this system call and
248.Dv AT_SYMLINK_NOFOLLOW
249is used with a path relative to a file descriptor.
250.El
251.Sh SEE ALSO
252.Xr chflags 2 ,
253.Xr stat 2 ,
254.Xr symlink 2 ,
255.Xr utimes 2 ,
256.Xr utime 3 ,
257.Xr symlink 7
258.Sh STANDARDS
259The
260.Fn futimens
261and
262.Fn utimensat
263system calls are expected to conform to
264.St -p1003.1-2008 .
265.Sh HISTORY
266The
267.Fn futimens
268and
269.Fn utimensat
270system calls appeared in
271.Dx 4.1 .
272