Skip to content

Commit

Permalink
Documentation and comments updated to further enshrine exec() as an o…
Browse files Browse the repository at this point in the history 
…fficial NuttX interface.
  • Loading branch information
@gregory-nutt
gregory-nutt committed Oct 3, 2017
1 parent 8e96654 commit 5c4d45a
Show file tree
Hide file tree
Showing 3 changed files with 167 additions and 19 deletions.
85 changes: 80 additions & 5 deletions Documentation/NuttxUserGuide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></font></big></h1>
<p><small>by</small></p>
<p>Gregory Nutt<p>
<p>Last Updated: February 16, 2017</p>
<p>Last Updated: October 2, 2017</p>
</td>
</tr>
</table>
Expand Down Expand Up @@ -224,8 +224,9 @@ <h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></fo
</p>
<ul>
<li><a href="#vfork">2.1.11 vfork</a></li>
<li><a href="#execv">2.1.12 execv</a></li>
<li><a href="#execl">2.1.13 execl</a></li>
<li><a href="#exec">2.1.12 exec</a></li>
<li><a href="#execv">2.1.13 execv</a></li>
<li><a href="#execl">2.1.14 execl</a></li>
</ul>
<p>
Standard <code>posix_spawn</code> interfaces:
Expand Down Expand Up @@ -835,7 +836,80 @@ <H3><a name="vfork">2.1.11 vfork</a></H3>
Compatible with the Unix interface of the same name.
</p>

<H3><a name="execv">2.1.12 execv</a></H3>
<H3><a name="exec">2.1.12 exec</a></H3>
<p>
<b>Function Prototype:</b>
</p>
<ul><pre>
#include &lt;nuttx/binfmt/binfmt.h&gt;
#ifndef CONFIG_BUILD_KERNEL
int exec(FAR const char *filename, FAR char * const *argv,
FAR const struct symtab_s *exports, int nexports);
#endif
</pre></ul>
<p>
<b>Description:</b>
This non-standard, NuttX function is similar to <code>execv()</code> and <code>posix_spawn()</code> but differs in the following ways;
</p>
<ul>
<li>
Unlike <code>execv()</code> and <code>posix_spawn()</code> this function accepts symbol table information as input parameters.
This means that the symbol table used to link the application prior to execution is provided by the caller, not by the system.
</li>
<li>
Unlike <code>execv()</code>, this function always returns.
</li>
</ul>
<p>
This non-standard interface is included as a official NuttX API only because it is needed in certain build modes: <code>exec()</code> is probably the only want to load programs in the PROTECTED mode. Other file execution APIs rely on a symbol table provided by the OS. In the PROTECTED build mode, the OS cannot provide any meaningful symbolic information for execution of code in the user-space blob so that is the <code>exec()</code> function is really needed in that build case
</p>
The interface is available in the FLAT build mode although it is not really necessary in that case. It is currently used by some example code under the <code>apps/</code> that that generate their own symbol tables for linking test programs. So althought it is not necessary, it can still be useful.
</p>
<p>
The interface would be completely useless and will not be supported in the KERNEL build mode where the contrary is true: An application process cannot provide any meaning symbolic information for use in linking a different process.
</p>
<p>
<b>NOTE</b>:
This function is flawed and useless without <code>CONFIG_SCHED_ONEXIT</code> and <code>CONFIG_SCHED_HAVE_PARENT</code> because without those features there is then no mechanism to unload the module once it exits.
</p>
</p>
<b>Input Parameters:</b>
</p>
<ul>
<li>
<code>filename</code>:
The path to the program to be executed.
If <code>CONFIG_BINFMT_EXEPATH</code> is defined in the configuration, then this may be a relative path from the current working directory.
Otherwise, <code>path</code> must be the absolute path to the program.
</li>
<li>
<code>argv</code>:
A pointer to an array of string arguments. The end of the array is indicated with a NULL entry.
</li>
<li>
<code>exports</code>:
The address of the start of the caller-provided symbol table.
This symbol table contains the addresses of symbols exported by the caller and made available for linking the module into the system.
</li>
<li>
<code>nexports</code>:
The number of symbols in the <code>exports</code> table.
</li>
</ul>
<p>
<b>Returned Value:</b>
Zero (OK) is returned on success;
On any failure, <code>exec()</code> will return -1 (<code>ERROR</code>) and will set the <code>errno</code> value appropriately.
<p>
<b>Assumptions/Limitations:</b>
</p>
<p>
<b>POSIX Compatibility:</b>
This is a non-standard inteface unique to NuttX.
Motivation for inclusion of this non-standard interface in certain build modes is discussed above.
</p>

<H3><a name="execv">2.1.13 execv</a></H3>
<p>
<b>Function Prototype:</b>
</p>
Expand Down Expand Up @@ -921,7 +995,7 @@ <H3><a name="execv">2.1.12 execv</a></H3>
There are, however, several compatibility issues as detailed in the description above.
</p>

<H3><a name="execl">2.1.13 execl</a></H3>
<H3><a name="execl">2.1.14 execl</a></H3>
<p>
<b>Function Prototype:</b>
</p>
Expand Down Expand Up @@ -10408,6 +10482,7 @@ <H3>3.4.8 struct sigevent</H3>
<li><a href="#drvrunistdops">dup2</a></li>
<li><a href="#execl">execl</a></li>
<li><a href="#mmapxip">eXecute In Place (XIP)</a></li>
<li><a href="#exec">exec</a></li>
<li><a href="#execv">execv</a></li>
<li><a href="#exit">exit</a></li>
<li><a href="#fatsupport">FAT File System Support</a></li>
Expand Down
50 changes: 43 additions & 7 deletions binfmt/binfmt_exec.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,15 +63,51 @@
* also defined, this function will automatically call schedule_unload()
* to unload the module when task exits.
*
* This non-standard, NuttX function is similar to execv() and
* posix_spawn() but differs in the following ways;
*
* - Unlike execv() and posix_spawn() this function accepts symbol table
* information as input parameters. This means that the symbol table
* used to link the application prior to execution is provided by the
* caller, not by the system.
* - Unlike execv(), this function always returns.
*
* This non-standard interface is included as a official NuttX API only
* because it is needed in certain build modes: exec() is probably the
* only want to load programs in the PROTECTED mode. Other file execution
* APIs rely on a symbol table provided by the OS. In the PROTECTED build
* mode, the OS cannot provide any meaningful symbolic information for
* execution of code in the user-space blob so that is the exec() function
* is really needed in that build case
*
* The interface is available in the FLAT build mode although it is not
* really necessary in that case. It is currently used by some example
* code under the apps/ that that generate their own symbol tables for
* linking test programs. So althought it is not necessary, it can still
* be useful.
*
* The interface would be completely useless and will not be supported in
* in the KERNEL build mode where the contrary is true: An application
* process cannot provide any meaning symbolic information for use in
* linking a different process.
*
* NOTE: This function is flawed and useless without CONFIG_SCHED_ONEXIT
* and CONFIG_SCHED_HAVE_PARENT because there is then no mechanism to
* unload the module once it exits.
* and CONFIG_SCHED_HAVE_PARENT because without those features there is
* then no mechanism to unload the module once it exits.
*
* Input Parameter:
* filename - Full path to the binary to be loaded
* argv - Argument list
* exports - Table of exported symbols
* nexports - The number of symbols in exports
* Input Parameters:
* filename - The path to the program to be executed. If
* CONFIG_BINFMT_EXEPATH is defined in the configuration, then
* this may be a relative path from the current working
* directory. Otherwise, path must be the absolute path to the
* program.
* argv - A pointer to an array of string arguments. The end of the
* array is indicated with a NULL entry.
* exports - The address of the start of the caller-provided symbol
* table. This symbol table contains the addresses of symbols
* exported by the caller and made available for linking the
* module into the system.
* nexports - The number of symbols in the exports table.
*
* Returned Value:
* This is an end-user function, so it follows the normal convention:
Expand Down
51 changes: 44 additions & 7 deletions include/nuttx/binfmt/binfmt.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@
/****************************************************************************
* Public Types
****************************************************************************/

/* EXEPATH_HANDLE is an opaque handle used to traverse the absolute paths
* assigned to the PATH environment variable.
*/
Expand Down Expand Up @@ -295,15 +296,51 @@ int schedule_unload(pid_t pid, FAR struct binary_s *bin);
* also defined, this function will automatically call schedule_unload()
* to unload the module when task exits.
*
* This non-standard, NuttX function is similar to execv() and
* posix_spawn() but differs in the following ways;
*
* - Unlike execv() and posix_spawn() this function accepts symbol table
* information as input parameters. This means that the symbol table
* used to link the application prior to execution is provided by the
* caller, not by the system.
* - Unlike execv(), this function always returns.
*
* This non-standard interface is included as a official NuttX API only
* because it is needed in certain build modes: exec() is probably the
* only want to load programs in the PROTECTED mode. Other file execution
* APIs rely on a symbol table provided by the OS. In the PROTECTED build
* mode, the OS cannot provide any meaningful symbolic information for
* execution of code in the user-space blob so that is the exec() function
* is really needed in that build case
*
* The interface is available in the FLAT build mode although it is not
* really necessary in that case. It is currently used by some example
* code under the apps/ that that generate their own symbol tables for
* linking test programs. So althought it is not necessary, it can still
* be useful.
*
* The interface would be completely useless and will not be supported in
* in the KERNEL build mode where the contrary is true: An application
* process cannot provide any meaning symbolic information for use in
* linking a different process.
*
* NOTE: This function is flawed and useless without CONFIG_SCHED_ONEXIT
* and CONFIG_SCHED_HAVE_PARENT because there is then no mechanism to
* unload the module once it exits.
* and CONFIG_SCHED_HAVE_PARENT because without those features there is
* then no mechanism to unload the module once it exits.
*
* Input Parameter:
* filename - Fulll path to the binary to be loaded
* argv - Argument list
* exports - Table of exported symbols
* nexports - The number of symbols in exports
* Input Parameters:
* filename - The path to the program to be executed. If
* CONFIG_BINFMT_EXEPATH is defined in the configuration, then
* this may be a relative path from the current working
* directory. Otherwise, path must be the absolute path to the
* program.
* argv - A pointer to an array of string arguments. The end of the
* array is indicated with a NULL entry.
* exports - The address of the start of the caller-provided symbol
* table. This symbol table contains the addresses of symbols
* exported by the caller and made available for linking the
* module into the system.
* nexports - The number of symbols in the exports table.
*
* Returned Value:
* This is an end-user function, so it follows the normal convention:
Expand Down

0 comments on commit 5c4d45a

Please sign in to comment.