execv.html

IEEE 1003.1-2003, Single Unix Specification v3

<li>
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
Interval timers <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
</li>
</ul>

<p>All other process attributes defined in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 shall be the same in the new and old
process images. The inheritance of process attributes not defined by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 is
implementation-defined.</p>

<p>A call to any <i>exec</i> function from a process with more than one thread shall result in all threads being terminated and the
new executable image being loaded and executed. No destructor functions shall be called.</p>

<p>Upon successful completion, the <i>exec</i> functions shall mark for update the <i>st_atime</i> field of the file. If an
<i>exec</i> function failed but was able to locate the process image file, whether the <i>st_atime</i> field is marked for update
is unspecified. Should the <i>exec</i> function succeed, the process image file shall be considered to have been opened with <a
href="../functions/open.html"><i>open</i>()</a>. The corresponding <a href="../functions/close.html"><i>close</i>()</a> shall be
considered to occur at a time after this open, but before process termination or successful completion of a subsequent call to one
of the <i>exec</i> functions, <a href="../functions/posix_spawn.html"><i>posix_spawn</i>()</a>, or <a href=
"../functions/posix_spawnp.html"><i>posix_spawnp</i>()</a>. The <i>argv</i>[] and <i>envp</i>[] arrays of pointers and the strings
to which those arrays point shall not be modified by a call to one of the <i>exec</i> functions, except as a consequence of
replacing the process image.</p>

<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The saved resource limits in the new process image are set to be a copy of the process' corresponding hard and soft limits. <img
src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
</blockquote>

<h4><a name="tag_03_130_04"></a>RETURN VALUE</h4>

<blockquote>
<p>If one of the <i>exec</i> functions returns to the calling process image, an error has occurred; the return value shall be -1,
and <i>errno</i> shall be set to indicate the error.</p>
</blockquote>

<h4><a name="tag_03_130_05"></a>ERRORS</h4>

<blockquote>
<p>The <i>exec</i> functions shall fail if:</p>

<dl compact>
<dt>[E2BIG]</dt>

<dd>The number of bytes used by the new process image's argument list and environment list is greater than the system-imposed limit
of {ARG_MAX} bytes.</dd>

<dt>[EACCES]</dt>

<dd>Search permission is denied for a directory listed in the new process image file's path prefix, or the new process image file
denies execution permission, or the new process image file is not a regular file and the implementation does not support execution
of files of its type.</dd>

<dt>[EINVAL]</dt>

<dd>The new process image file has the appropriate permission and has a recognized executable binary format, but the system does
not support execution of a file with this format.</dd>

<dt>[ELOOP]</dt>

<dd>A loop exists in symbolic links encountered during resolution of the <i>path</i> or <i>file</i> argument.</dd>

<dt>[ENAMETOOLONG]</dt>

<dd>
The length of the <i>path</i> or <i>file</i> arguments exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.</dd>

<dt>[ENOENT]</dt>

<dd>A component of <i>path</i> or <i>file</i> does not name an existing file or <i>path</i> or <i>file</i> is an empty string.</dd>

<dt>[ENOTDIR]</dt>

<dd>A component of the new process image file's path prefix is not a directory.</dd>
</dl>

<p>The <i>exec</i> functions, except for <i>execlp</i>() and <i>execvp</i>(), shall fail if:</p>

<dl compact>
<dt>[ENOEXEC]</dt>

<dd>The new process image file has the appropriate access permission but has an unrecognized format.</dd>
</dl>

<p>The <i>exec</i> functions may fail if:</p>

<dl compact>
<dt>[ELOOP]</dt>

<dd>More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the <i>path</i> or <i>file</i> argument.</dd>

<dt>[ENAMETOOLONG]</dt>

<dd>
As a result of encountering a symbolic link in resolution of the <i>path</i> argument, the length of the substituted pathname
string exceeded {PATH_MAX}.</dd>

<dt>[ENOMEM]</dt>

<dd>The new process image requires more memory than is allowed by the hardware or system-imposed memory management
constraints.</dd>

<dt>[ETXTBSY]</dt>

<dd>The new process image file is a pure procedure (shared text) file that is currently open for writing by some process.</dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_130_06"></a>EXAMPLES</h4>

<blockquote>
<h5><a name="tag_03_130_06_01"></a>Using execl()</h5>

<p>The following example executes the <a href="../utilities/ls.html"><i>ls</i></a> command, specifying the pathname of the
executable ( <b>/bin/ls</b>) and using arguments supplied directly to the command to produce single-column output.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
<br>
int ret;
...
ret = execl ("/bin/ls", "ls", "-1", (char *)0);
</tt>
</pre>

<h5><a name="tag_03_130_06_02"></a>Using execle()</h5>

<p>The following example is similar to <a href="#tag_03_130_06_01">Using execl()</a> . In addition, it specifies the environment
for the new process image using the <i>env</i> argument.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
<br>
int ret;
char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
...
ret = execle ("/bin/ls", "ls", "-l", (char *)0, env);
</tt>
</pre>

<h5><a name="tag_03_130_06_03"></a>Using execlp()</h5>

<p>The following example searches for the location of the <a href="../utilities/ls.html"><i>ls</i></a> command among the
directories specified by the <i>PATH</i> environment variable.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
<br>
int ret;
...
ret = execlp ("ls", "ls", "-l", (char *)0);
</tt>
</pre>

<h5><a name="tag_03_130_06_04"></a>Using execv()</h5>

<p>The following example passes arguments to the <a href="../utilities/ls.html"><i>ls</i></a> command in the <i>cmd</i> array.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
<br>
int ret;
char *cmd[] = { "ls", "-l", (char *)0 };
...
ret = execv ("/bin/ls", cmd);
</tt>
</pre>

<h5><a name="tag_03_130_06_05"></a>Using execve()</h5>

<p>The following example passes arguments to the <a href="../utilities/ls.html"><i>ls</i></a> command in the <i>cmd</i> array, and
specifies the environment for the new process image using the <i>env</i> argument.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
<br>
int ret;
char *cmd[] = { "ls", "-l", (char *)0 };
char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
...
ret = execve ("/bin/ls", cmd, env);
</tt>
</pre>

<h5><a name="tag_03_130_06_06"></a>Using execvp()</h5>

<p>The following example searches for the location of the <a href="../utilities/ls.html"><i>ls</i></a> command among the
directories specified by the <i>PATH</i> environment variable, and passes arguments to the <a href=
"../utilities/ls.html"><i>ls</i></a> command in the <i>cmd</i> array.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
<br>
int ret;
char *cmd[] = { "ls", "-l", (char *)0 };
...
ret = execvp ("ls", cmd);
</tt>
</pre>
</blockquote>

<h4><a name="tag_03_130_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>As the state of conversion descriptors and message catalog descriptors in the new process image is undefined, conforming
applications should not rely on their use and should close them prior to calling one of the <i>exec</i> functions.</p>

<p>Applications that require other than the default POSIX locale should call <a href=
"../functions/setlocale.html"><i>setlocale</i>()</a> with the appropriate parameters to establish the locale of the new
process.</p>

<p>The <i>environ</i> array should not be accessed directly by the application.</p>

<p>Applications should not depend on file descriptors 0, 1, and 2 being closed after an <i>exec</i>. A future version may allow
these file descriptors to be automatically opened for any process.</p>
</blockquote>

<h4><a name="tag_03_130_08"></a>RATIONALE</h4>

<blockquote>
<p>Early proposals required that the value of <i>argc</i> passed to <i>main</i>() be &quot;one or greater&quot;. This was driven by the
same requirement in drafts of the ISO&nbsp;C standard. In fact, historical implementations have passed a value of zero when no
arguments are supplied to the caller of the <i>exec</i> functions. This requirement was removed from the ISO&nbsp;C standard and
subsequently removed from this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 as well. The wording, in particular the use of the word
<i>should</i>, requires a Strictly Conforming POSIX Application to pass at least one argument to the <i>exec</i> function, thus
guaranteeing that <i>argc</i> be one or greater when invoked by such an application. In fact, this is good practice, since many
existing applications reference <i>argv</i>[0] without first checking the value of <i>argc</i>.</p>

<p>The requirement on a Strictly Conforming POSIX Application also states that the value passed as the first argument be a filename
associated with the process being started. Although some existing applications pass a pathname rather than a filename in some
circumstances, a filename is more generally useful, since the common usage of <i>argv</i>[0] is in printing diagnostics. In some
cases the filename passed is not the actual filename of the file; for example, many implementations of the <i>login</i> utility use
a convention of prefixing a hyphen ( <tt>'-'</tt> ) to the actual filename, which indicates to the command interpreter being
invoked that it is a &quot;login shell&quot;.</p>

<p>Historically there have been two ways that implementations can <i>exec</i> shell scripts.</p>

<p>One common historical implementation is that the <i>execl</i>(), <i>execv</i>(), <i>execle</i>(), and <i>execve</i>() functions
return an [ENOEXEC] error for any file not recognizable as executable, including a shell script. When the <i>execlp</i>() and
<i>execvp</i>() functions encounter such a file, they assume the file to be a shell script and invoke a known command interpreter
to interpret such files. This is now required by IEEE&nbsp;Std&nbsp;1003.1-2001. These implementations of <i>execvp</i>() and
<i>execlp</i>() only give the [ENOEXEC] error in the rare case of a problem with the command interpreter's executable file. Because
of these implementations, the [ENOEXEC] error is not mentioned for <i>execlp</i>() or <i>execvp</i>(), although implementations can
still give it.</p>

<p>Another way that some historical implementations handle shell scripts is by recognizing the first two bytes of the file as the
character string <tt>"#!"</tt> and using the remainder of the first line of the file as the name of the command interpreter to
execute.</p>

<p>One potential source of confusion noted by the standard developers is over how the contents of a process image file affect the
behavior of the <i>exec</i> family of functions. The following is a description of the actions taken:</p>

<ol>
<li>
<p>If the process image file is a valid executable (in a format that is executable and valid and having appropriate permission) for
this system, then the system executes the file.</p>
</li>

<li>
<p>If the process image file has appropriate permission and is in a format that is executable but not valid for this system (such
as a recognized binary for another architecture), then this is an error and <i>errno</i> is set to [EINVAL] (see later RATIONALE on
[EINVAL]).</p>
</li>

<li>
<p>If the process image file has appropriate permission but is not otherwise recognized:</p>

<ol type="a">
<li>
<p>If this is a call to <i>execlp</i>() or <i>execvp</i>(), then they invoke a command interpreter assuming that the process image
file is a shell script.</p>
</li>

<li>
<p>If this is not a call to <i>execlp</i>() or <i>execvp</i>(), then an error occurs and <i>errno</i> is set to [ENOEXEC].</p>
</li>
</ol>
</li>
</ol>

<p>Applications that do not require to access their arguments may use the form:</p>

<pre>
<tt>main(void)
</tt>
</pre>

as specified in the ISO&nbsp;C standard. However, the implementation will always provide the two arguments <i>argc</i> and
<i>argv</i>, even if they are not used. 

<p>Some implementations provide a third argument to <i>main</i>() called <i>envp</i>. This is defined as a pointer to the
environment. The ISO&nbsp;C standard specifies invoking <i>main</i>() with two arguments, so implementations must support
applications written this way. Since this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 defines the global variable <i>environ</i>,
which is also provided by historical implementations and can be used anywhere that <i>envp</i> could be used, there is no
functional need for the <i>envp</i> argument. Applications should use the <a href="../functions/getenv.html"><i>getenv</i>()</a>
function rather than accessing the environment directly via either <i>envp</i> or <i>environ</i>. Implementations are required to
support the two-argument calling sequence, but this does not prohibit an implementation from supporting <i>envp</i> as an optional
third argument.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 specifies that signals set to SIG_IGN remain set to SIG_IGN, and that the process
signal mask be unchanged across an <i>exec</i>. This is consistent with historical implementations, and it permits some useful
functionality, such as the <a href="../utilities/nohup.html"><i>nohup</i></a> command. However, it should be noted that many
existing applications wrongly assume that they start with certain signals set to the default action and/or unblocked. In
particular, applications written with a simpler signal model that does not include blocking of signals, such as the one in the
ISO&nbsp;C standard, may not behave properly if invoked with some signals blocked. Therefore, it is best not to block or ignore
signals across <i>exec</i>s without explicit reason to do so, and especially not to block signals across <i>exec</i>s of arbitrary
(not closely co-operating) programs.</p>

<p>The <i>exec</i> functions always save the value of the effective user ID and effective group ID of the process at the completion
of the <i>exec</i>, whether or not the set-user-ID or the set-group-ID bit of the process image file is set.</p>

<p>The statement about <i>argv</i>[] and <i>envp</i>[] being constants is included to make explicit to future writers of language
bindings that these objects are completely constant. Due to a limitation of the ISO&nbsp;C standard, it is not possible to state
that idea in standard C. Specifying two levels of <i>const</i>- <i>qualification</i> for the <i>argv</i>[] and <i>envp</i>[]
parameters for the <i>exec</i> functions may seem to be the natural choice, given that these functions do not modify either the
array of pointers or the characters to which the function points, but this would disallow existing correct code. Instead, only the