man2/execveat.2

   1 .\" Copyright (c) 2014 Google, Inc., written by David Drysdale
   2 .\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH EXECVEAT 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   7 .SH NAME
   8 execveat \- execute program relative to a directory file descriptor
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
  15 .B #include <unistd.h>
  16 .PP
  17 .BI "int execveat(int " dirfd ", const char *" pathname ,
  18 .BI "             const char *const " argv "[], const char *const " envp [],
  19 .BI "             int " flags );
  20 .fi
  21 .SH DESCRIPTION
  22 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
  23 The
  24 .BR execveat ()
  25 system call executes the program referred to by the combination of
  26 .I dirfd
  27 and
  28 .IR pathname .
  29 It operates in exactly the same way as
  30 .BR execve (2),
  31 except for the differences described in this manual page.
  32 .PP
  33 If the pathname given in
  34 .I pathname
  35 is relative, then it is interpreted relative to the directory
  36 referred to by the file descriptor
  37 .I dirfd
  38 (rather than relative to the current working directory of
  39 the calling process, as is done by
  40 .BR execve (2)
  41 for a relative pathname).
  42 .PP
  43 If
  44 .I pathname
  45 is relative and
  46 .I dirfd
  47 is the special value
  48 .BR AT_FDCWD ,
  49 then
  50 .I pathname
  51 is interpreted relative to the current working
  52 directory of the calling process (like
  53 .BR execve (2)).
  54 .PP
  55 If
  56 .I pathname
  57 is absolute, then
  58 .I dirfd
  59 is ignored.
  60 .PP
  61 If
  62 .I pathname
  63 is an empty string and the
  64 .B AT_EMPTY_PATH
  65 flag is specified, then the file descriptor
  66 .I dirfd
  67 specifies the file to be executed (i.e.,
  68 .I dirfd
  69 refers to an executable file, rather than a directory).
  70 .PP
  71 The
  72 .I flags
  73 argument is a bit mask that can include zero or more of the following flags:
  74 .TP
  75 .B AT_EMPTY_PATH
  76 If
  77 .I pathname
  78 is an empty string, operate on the file referred to by
  79 .I dirfd
  80 (which may have been obtained using the
  81 .BR open (2)
  82 .B O_PATH
  83 flag).
  84 .TP
  85 .B AT_SYMLINK_NOFOLLOW
  86 If the file identified by
  87 .I dirfd
  88 and a non-NULL
  89 .I pathname
  90 is a symbolic link, then the call fails with the error
  91 .BR ELOOP .
  92 .SH RETURN VALUE
  93 On success,
  94 .BR execveat ()
  95 does not return.
  96 On error, \-1 is returned, and
  97 .I errno
  98 is set to indicate the error.
  99 .SH ERRORS
 100 The same errors that occur for
 101 .BR execve (2)
 102 can also occur for
 103 .BR execveat ().
 104 The following additional errors can occur for
 105 .BR execveat ():
 106 .TP
 107 .I pathname
 108 is relative but
 109 .I dirfd
 110 is neither
 111 .B AT_FDCWD
 112 nor a valid file descriptor.
 113 .TP
 114 .B EINVAL
 115 Invalid flag specified in
 116 .IR flags .
 117 .TP
 118 .B ELOOP
 119 .I flags
 120 includes
 121 .B AT_SYMLINK_NOFOLLOW
 122 and the file identified by
 123 .I dirfd
 124 and a non-NULL
 125 .I pathname
 126 is a symbolic link.
 127 .TP
 128 .B ENOENT
 129 The program identified by
 130 .I dirfd
 131 and
 132 .I pathname
 133 requires the use of an interpreter program
 134 (such as a script starting with "#!"), but the file descriptor
 135 .I dirfd
 136 was opened with the
 137 .B O_CLOEXEC
 138 flag, with the result that
 139 the program file is inaccessible to the launched interpreter.
 140 See BUGS.
 141 .TP
 142 .B ENOTDIR
 143 .I pathname
 144 is relative and
 145 .I dirfd
 146 is a file descriptor referring to a file other than a directory.
 147 .SH VERSIONS
 148 .BR execveat ()
 149 was added to Linux in kernel 3.19.
 150 Library support was added to glibc in version 2.34.
 151 .SH STANDARDS
 152 The
 153 .BR execveat ()
 154 system call is Linux-specific.
 155 .SH NOTES
 156 In addition to the reasons explained in
 157 .BR openat (2),
 158 the
 159 .BR execveat ()
 160 system call is also needed to allow
 161 .BR fexecve (3)
 162 to be implemented on systems that do not have the
 163 .I /proc
 164 filesystem mounted.
 165 .PP
 166 When asked to execute a script file, the
 167 .I argv[0]
 168 that is passed to the script interpreter is a string of the form
 169 .I /dev/fd/N
 170 or
 171 .IR /dev/fd/N/P ,
 172 where
 173 .I N
 174 is the number of the file descriptor passed via the
 175 .I dirfd
 176 argument.
 177 A string of the first form occurs when
 178 .B AT_EMPTY_PATH
 179 is employed.
 180 A string of the second form occurs when the script is specified via both
 181 .I dirfd
 182 and
 183 .IR pathname ;
 184 in this case,
 185 .I P
 186 is the value given in
 187 .IR pathname .
 188 .PP
 189 For the same reasons described in
 190 .BR fexecve (3),
 191 the natural idiom when using
 192 .BR execveat ()
 193 is to set the close-on-exec flag on
 194 .IR dirfd .
 195 (But see BUGS.)
 196 .SH BUGS
 197 The
 198 .B ENOENT
 199 error described above means that it is not possible to set the
 200 close-on-exec flag on the file descriptor given to a call of the form:
 201 .PP
 202 .in +4n
 203 .EX
 204 execveat(fd, "", argv, envp, AT_EMPTY_PATH);
 205 .EE
 206 .in
 207 .PP
 208 However, the inability to set the close-on-exec flag means that a file
 209 descriptor referring to the script leaks through to the script itself.
 210 As well as wasting a file descriptor,
 211 this leakage can lead to file-descriptor exhaustion in scenarios
 212 where scripts recursively employ
 213 .BR execveat ().
 214 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
 215 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
 216 .\"
 217 .\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
 218 .\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
 219 .SH SEE ALSO
 220 .BR execve (2),
 221 .BR openat (2),
 222 .BR fexecve (3)