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