man3/fexecve.3

   1 .\" Copyright (c) 2006, 2014, Michael Kerrisk
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH FEXECVE 3 2021-03-22 "Linux man-pages (unreleased)"
   6 .SH NAME
   7 fexecve \- execute program specified via file descriptor
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <unistd.h>
  14 .PP
  15 .BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []);
  16 .fi
  17 .PP
  18 .RS -4
  19 Feature Test Macro Requirements for glibc (see
  20 .BR feature_test_macros (7)):
  21 .RE
  22 .PP
  23 .BR fexecve ():
  24 .nf
  25     Since glibc 2.10:
  26         _POSIX_C_SOURCE >= 200809L
  27     Before glibc 2.10:
  28         _GNU_SOURCE
  29 .fi
  30 .SH DESCRIPTION
  31 .BR fexecve ()
  32 performs the same task as
  33 .BR execve (2),
  34 with the difference that the file to be executed
  35 is specified via a file descriptor,
  36 .IR fd ,
  37 rather than via a pathname.
  38 The file descriptor
  39 .I fd
  40 must be opened read-only
  41 .RB ( O_RDONLY )
  42 or with the
  43 .B O_PATH
  44 flag
  45 and the caller must have permission to execute the file that it refers to.
  46 .SH RETURN VALUE
  47 A successful call to
  48 .BR fexecve ()
  49 never returns.
  50 On error, the function does return, with a result value of \-1, and
  51 .I errno
  52 is set to indicate the error.
  53 .SH ERRORS
  54 Errors are as for
  55 .BR execve (2),
  56 with the following additions:
  57 .TP
  58 .B EINVAL
  59 .I fd
  60 is not a valid file descriptor, or
  61 .I argv
  62 is NULL, or
  63 .I envp
  64 is NULL.
  65 .TP
  66 .B ENOENT
  67 The close-on-exec flag is set on
  68 .IR fd ,
  69 and
  70 .I fd
  71 refers to a script.
  72 See BUGS.
  73 .TP
  74 .B ENOSYS
  75 The kernel does not provide the
  76 .BR execveat (2)
  77 system call, and the
  78 .I /proc
  79 filesystem could not be accessed.
  80 .SH VERSIONS
  81 .BR fexecve ()
  82 is implemented since glibc 2.3.2.
  83 .SH ATTRIBUTES
  84 For an explanation of the terms used in this section, see
  85 .BR attributes (7).
  86 .ad l
  87 .nh
  88 .TS
  89 allbox;
  90 lbx lb lb
  91 l l l.
  92 Interface       Attribute       Value
  93 T{
  94 .BR fexecve ()
  95 T}      Thread safety   MT-Safe
  96 .TE
  97 .hy
  98 .ad
  99 .sp 1
 100 .SH STANDARDS
 101 POSIX.1-2008.
 102 This function is not specified in POSIX.1-2001,
 103 and is not widely available on other systems.
 104 It is specified in POSIX.1-2008.
 105 .SH NOTES
 106 On Linux with glibc versions 2.26 and earlier,
 107 .BR fexecve ()
 108 is implemented using the
 109 .BR proc (5)
 110 filesystem, so
 111 .I /proc
 112 needs to be mounted and available at the time of the call.
 113 Since glibc 2.27,
 114 .\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60
 115 if the underlying kernel supports the
 116 .BR execveat (2)
 117 system call, then
 118 .BR fexecve ()
 119 is implemented using that system call, with the benefit that
 120 .I /proc
 121 does not need to be mounted.
 122 .PP
 123 The idea behind
 124 .BR fexecve ()
 125 is to allow the caller to verify (checksum) the contents of
 126 an executable before executing it.
 127 Simply opening the file, checksumming the contents, and then doing an
 128 .BR execve (2)
 129 would not suffice, since, between the two steps, the filename,
 130 or a directory prefix of the pathname, could have been exchanged
 131 (by, for example, modifying the target of a symbolic link).
 132 .BR fexecve ()
 133 does not mitigate the problem that the
 134 .I contents
 135 of a file could be changed between the checksumming and the call to
 136 .BR fexecve ();
 137 for that, the solution is to ensure that the permissions on the file
 138 prevent it from being modified by malicious users.
 139 .PP
 140 The natural idiom when using
 141 .BR fexecve ()
 142 is to set the close-on-exec flag on
 143 .IR fd ,
 144 so that the file descriptor does not leak through to the program
 145 that is executed.
 146 This approach is natural for two reasons.
 147 First, it prevents file descriptors being consumed unnecessarily.
 148 (The executed program normally has no need of a file descriptor
 149 that refers to the program itself.)
 150 Second, if
 151 .BR fexecve ()
 152 is used recursively,
 153 employing the close-on-exec flag prevents the file descriptor exhaustion
 154 that would result from the fact that each step in the recursion would
 155 cause one more file descriptor to be passed to the new program.
 156 (But see BUGS.)
 157 .SH BUGS
 158 If
 159 .I fd
 160 refers to a script (i.e., it is an executable text file that names
 161 a script interpreter with a first line that begins with the characters
 162 .IR #! )
 163 and the close-on-exec flag has been set for
 164 .IR fd ,
 165 then
 166 .BR fexecve ()
 167 fails with the error
 168 .BR ENOENT .
 169 This error occurs because,
 170 by the time the script interpreter is executed,
 171 .I fd
 172 has already been closed because of the close-on-exec flag.
 173 Thus, the close-on-exec flag can't be set on
 174 .I fd
 175 if it refers to a script, leading to the problems described in NOTES.
 176 .SH SEE ALSO
 177 .BR execve (2),
 178 .BR execveat (2)