man2/futimesat.2

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