<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="exec">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>exec</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">nosh</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>exec</refname>
<refpurpose>chain</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>exec</command>
<arg choice='opt'>--login</arg>
<arg choice='opt'>--clear</arg>
<arg choice='opt'>--arg0 <replaceable>string</replaceable></arg>
<arg choice='req'><replaceable>next-prog</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Note</title>

<para>
Most shells have a built-in <command>exec</command> command that replaces the shell process itself.
See the manual for each individual shell for its built-in command.
This command will be an external command to most shells.
It is a built-in command for <citerefentry><refentrytitle>nosh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>

</refsection><refsection><title>Description</title>

<para>
<command>exec</command> is a chain-loading utility that simply chain loads to <replaceable>next-prog</replaceable> with the <citerefentry><refentrytitle>execvp</refentrytitle><manvolnum>3</manvolnum></citerefentry> function.
</para>

<para>
<replaceable>next-prog</replaceable> may contain its own command line options, which <command>exec</command> will ignore.
</para>

<para>
If the <arg choice='plain'>--clear</arg> command line option is used, <command>exec</command> will clear its environment before chaining.
Otherwise, it leaves its process state unchanged.
</para>
<caution>
This option is for compatibility with the built-in <citerefentry><refentrytitle>exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> command of shells.
Avoid its use.
Instead, use the built-in <citerefentry><refentrytitle>clearenv</refentrytitle><manvolnum>1</manvolnum></citerefentry> command.
</caution>

<para>
The <arg choice='plain'>--arg0</arg> command line option causes it to replace the first element of the argument list that it passes to <replaceable>next-prog</replaceable>, which is otherwise the name of the command in <replaceable>next-prog</replaceable>, with the supplied string.
If the <arg choice='plain'>--login</arg> command line option is used, then the first element of the argument list has a dash (<code>-</code>) prepended, which is the convention for signalling shells that they are being invoked directly by <citerefentry><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
This happens after any substitution because of <arg choice='plain'>--arg0</arg>.
</para>

</refsection><refsection><title>Built-in commands</title>

<para>
<command>exec</command> is in fact a multiple personality program, whose function varies according to what name it is invoked as.
The alternative names are:
<command>appendpath</command>,
<command>background</command>,
<command>cd</command>,
<command>chdir</command>,
<command>chdir-home</command>,
<command>chroot</command>,
<command>clearenv</command>,
<command>cyclog</command>,
<command>delegate-control-group-to</command>,
<command>envdir</command>,
<command>envgid</command>,
<command>envuidgid</command>,
<command>erase-machine-id</command>
<command>export-to-rsyslog</command>,
<command>false</command>,
<command>fdmove</command>,
<command>fdredir</command>,
<command>fifo-listen</command>,
<command>follow-log-directories</command>,
<command>foreground</command>,
<command>getuidgid</command>,
<command>hardlimit</command>,
<command>klog-read</command>
<command>line-banner</command>,
<command>local-datagram-socket-listen</command>,
<command>local-seqpacket-socket-accept</command>,
<command>local-seqpacket-socket-listen</command>,
<command>local-stream-socket-accept</command>,
<command>local-stream-socket-connect</command>,
<command>local-stream-socket-listen</command>,
<command>machineenv</command>,
<command>make-private-fs</command>,
<command>make-read-only-fs</command>,
<command>monitored-fsck</command>,
<command>create-control-group</command>,
<command>move-to-control-group</command>,
<command>netlink-datagram-socket-listen</command>,
<command>nosh</command>,
<command>oom-kill-protect</command>,
<command>pause</command>,
<command>pipe</command>,
<command>plug-and-play-event-handler</command>
<command>prependpath</command>,
<command>printenv</command>,
<command>read-conf</command>,
<command>recordio</command>,
<command>set-control-group-knob</command>,
<command>set-dynamic-hostname</command>,
<command>set-mount-object</command>
<command>setenv</command>,
<command>setgid-fromenv</command>,
<command>setlock</command>,
<command>setpgrp</command>,
<command>setsid</command>,
<command>setsid</command>,
<command>setuidgid-fromenv</command>,
<command>setuidgid</command>,
<command>setup-machine-id</command>
<command>softlimit</command>,
<command>syslog-read</command>
<command>tai64n</command>,
<command>tai64nlocal</command>,
<command>tcp-socket-accept</command>,
<command>tcp-socket-connect</command>,
<command>tcp-socket-listen</command>,
<command>tcpserver</command>
<command>true</command>,
<command>ucspi-socket-rules-check</command>,
<command>udp-socket-connect</command>,
<command>udp-socket-listen</command>,
<command>ulimit</command>,
<command>umask</command>,
<command>unsetenv</command>,
<command>unshare</command>,
<command>userenv</command>,
and
<command>userenv-fromenv</command>.
See their individual manual pages for details.
</para>

<para>
These other commands are also available as built-in commands, in <citerefentry><refentrytitle>exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> and in <citerefentry><refentrytitle>nosh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
If <replaceable>next-prog</replaceable> is such a command, it will be executed directly, without needing to ask the operating system to overlay the current process and reinitialize the runtime libraries.
(Built-in commands must be named simply, and may not have directory prefixes.
If invoked with prefixes, they will be run as ordinary overlaid programs via <citerefentry><refentrytitle>execv</refentrytitle><manvolnum>1</manvolnum></citerefentry>.)
</para>

<para>
The built-in command mechanism tries to ensure that the <code>COMM</code> and <code>ARGS</code> fields shown in a <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> listing reflect the changes when chain-loading through built-in commands.
</para>

</refsection><refsection><title>Security</title>

<para>
Having built-in commands, rather than forcing each individual command to be reloaded as a fresh process image by the operating system, exposes all built-in commands in a chain-loading chain to any weaknesses in one.
</para>

<para>
However, this is a reasonable trade-off.
Most of the built-in commands do very little, and most of their processing when executed as external commands is in fact devoted to the dynamic loader and initializing the runtime libraries.
(For example: <citerefentry><refentrytitle>chdir</refentrytitle><manvolnum>1</manvolnum></citerefentry> makes two system calls in the meat of the command.
On one Linux system, however, the dynamic loader and runtime libraries make 143 system calls just to load and start the program.
Other commands have similarly enormous ratios.)
Having built-in commands eliminates the repeated teardown and re-initialization overheads from the dynamic loader and runtime libraries, reducing the overhead of small commands that individually do little to the same order of magnitude as simple function calls.
</para>

<para>
And the commands themselves <replaceable>are</replaceable> short and readily amenable to security audit.
They are highly modular, with almost no coupling between commands; and usually simple.
</para>

<para>
And you can always run the commands as external commands, as aforementioned.
</para>

</refsection><refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
