original/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 2015-01-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 execveat \- execute program relative to a directory file descriptor
  29 .SH SYNOPSIS
  30 .B #include <unistd.h>
  31 .sp
  32 .BI "int execveat(int " dirfd ", const char *" pathname ","
  33 .br
  34 .BI "             char *const " argv "[], char *const " envp "[],"
  35 .br
  36 .BI "             int " flags );
  37 .SH DESCRIPTION
  38 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
  39 The
  40 .BR execveat ()
  41 system call executes the program referred to by the combination of
  42 .I dirfd
  43 and
  44 .IR pathname .
  45 It operates in exactly the same way as
  46 .BR execve (2),
  47 except for the differences described in this manual page.
  48
  49 If the pathname given in
  50 .I pathname
  51 is relative, then it is interpreted relative to the directory
  52 referred to by the file descriptor
  53 .I dirfd
  54 (rather than relative to the current working directory of
  55 the calling process, as is done by
  56 .BR execve (2)
  57 for a relative pathname).
  58
  59 If
  60 .I pathname
  61 is relative and
  62 .I dirfd
  63 is the special value
  64 .BR AT_FDCWD ,
  65 then
  66 .I pathname
  67 is interpreted relative to the current working
  68 directory of the calling process (like
  69 .BR execve (2)).
  70
  71 If
  72 .I pathname
  73 is absolute, then
  74 .I dirfd
  75 is ignored.
  76
  77 If
  78 .I pathname
  79 is an empty string and the
  80 .BR AT_EMPTY_PATH
  81 flag is specified, then the file descriptor
  82 .I dirfd
  83 specifies the file to be executed (i.e.,
  84 .IR dirfd
  85 refers to an executable file, rather than a directory).
  86
  87 The
  88 .I flags
  89 argument is a bit mask that can include zero or more of the following flags:
  90 .TP
  91 .BR AT_EMPTY_PATH
  92 If
  93 .I pathname
  94 is an empty string, operate on the file referred to by
  95 .IR dirfd
  96 (which may have been obtained using the
  97 .BR open (2)
  98 .B O_PATH
  99 flag).
 100 .TP
 101 .B AT_SYMLINK_NOFOLLOW
 102 If the file identified by
 103 .I dirfd
 104 and a non-NULL
 105 .I pathname
 106 is a symbolic link, then the call fails with the error
 107 .BR ELOOP .
 108 .SH "RETURN VALUE"
 109 On success,
 110 .BR execveat ()
 111 does not return.
 112 On error, \-1 is returned, and
 113 .I errno
 114 is set appropriately.
 115 .SH ERRORS
 116 The same errors that occur for
 117 .BR execve (2)
 118 can also occur for
 119 .BR execveat ().
 120 The following additional errors can occur for
 121 .BR execveat ():
 122 .TP
 123 .B EBADF
 124 .I dirfd
 125 is not a valid file descriptor.
 126 .TP
 127 .B EINVAL
 128 Invalid flag specified in
 129 .IR flags .
 130 .TP
 131 .B ELOOP
 132 .I flags
 133 includes
 134 .BR AT_SYMLINK_NOFOLLOW
 135 and the file identified by
 136 .I dirfd
 137 and a non-NULL
 138 .I pathname
 139 is a symbolic link.
 140 .TP
 141 .B ENOENT
 142 The program identified by
 143 .I dirfd
 144 and
 145 .I pathname
 146 requires the use of an interpreter program
 147 (such as a script starting with "#!"), but the file descriptor
 148 .I dirfd
 149 was opened with the
 150 .B O_CLOEXEC
 151 flag, with the result that
 152 the program file is inaccessible to the launched interpreter.
 153 See BUGS.
 154 .TP
 155 .B ENOTDIR
 156 .I pathname
 157 is relative and
 158 .I dirfd
 159 is a file descriptor referring to a file other than a directory.
 160 .SH VERSIONS
 161 .BR execveat ()
 162 was added to Linux in kernel 3.19.
 163 GNU C library support is pending.
 164 .\" FIXME . check for glibc support in a future release
 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
 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
 203 For the same reasons described in
 204 .BR fexecve (3),
 205 the natural idiom when using
 206 .BR execveat (2)
 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
 216     execveat(fd, "", argv, envp, AT_EMPTY_PATH);
 217
 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)
 233 .SH COLOPHON
 234 This page is part of release 3.78 of the Linux
 235 .I man-pages
 236 project.
 237 A description of the project,
 238 information about reporting bugs,
 239 and the latest version of this page,
 240 can be found at
 241 \%http://www.kernel.org/doc/man\-pages/.