Debian Codegraph @

upstream/debian-unstable/man2/futimesat.2

raw
1 .\" Copyright 2006, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH futimesat 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 futimesat \- change timestamps of a file relative to a \
9 directory file descriptor
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
16 .B #include <sys/time.h>
17 .P
18 .BI "[[deprecated]] int futimesat(int " dirfd ", const char *" path ,
19 .BI " const struct timeval " times [2]);
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR futimesat ():
28 .nf
29 _GNU_SOURCE
30 .fi
31 .SH DESCRIPTION
32 This system call is obsolete.
33 Use
34 .BR utimensat (2)
35 instead.
36 .P
37 The
38 .BR futimesat ()
39 system call operates in exactly the same way as
40 .BR utimes (2),
41 except for the differences described in this manual page.
42 .P
43 If
44 .I path
45 is relative, then it is interpreted relative to the directory
46 referred to by the file descriptor
47 .I dirfd
48 (rather than relative to the current working directory of
49 the calling process, as is done by
50 .BR utimes (2)
51 for a relative pathname).
52 .P
53 If
54 .I path
55 is relative and
56 .I dirfd
57 is the special value
58 .BR AT_FDCWD ,
59 then
60 .I path
61 is interpreted relative to the current working
62 directory of the calling process (like
63 .BR utimes (2)).
64 .P
65 If
66 .I path
67 is absolute, then
68 .I dirfd
69 is ignored.
70 (See
71 .BR openat (2)
72 for an explanation of why the
73 .I dirfd
74 argument is useful.)
75 .SH RETURN VALUE
76 On success,
77 .BR futimesat ()
78 returns a 0.
79 On error, \-1 is returned and
80 .I errno
81 is set to indicate the error.
82 .SH ERRORS
83 The same errors that occur for
84 .BR utimes (2)
85 can also occur for
86 .BR futimesat ().
87 The following additional errors can occur for
88 .BR futimesat ():
89 .TP
90 .B EBADF
91 .I path
92 is relative but
93 .I dirfd
94 is neither
95 .B AT_FDCWD
96 nor a valid file descriptor.
97 .TP
98 .B ENOTDIR
99 .I path
100 is relative and
101 .I dirfd
102 is a file descriptor referring to a file other than a directory.
103 .SH VERSIONS
104 .SS glibc
105 If
106 .I path
107 is NULL, then the glibc
108 .BR futimesat ()
109 wrapper function updates the times for the file referred to by
110 .IR dirfd .
111 .\" The Solaris futimesat() also has this strangeness.
112 .SH STANDARDS
113 None.
114 .SH HISTORY
115 Linux 2.6.16,
116 glibc 2.4.
117 .P
118 It was implemented from a specification that was proposed for POSIX.1,
119 but that specification was replaced by the one for
120 .BR utimensat (2).
121 .P
122 A similar system call exists on Solaris.
123 .SH NOTES
124 .SH SEE ALSO
125 .BR stat (2),
126 .BR utimensat (2),
127 .BR utimes (2),
128 .BR futimes (3),
129 .BR path_resolution (7)