diff options
author | patacongo <patacongo@42af7a65-404d-4744-a932-0658087f49c3> | 2013-01-08 16:51:22 +0000 |
---|---|---|
committer | patacongo <patacongo@42af7a65-404d-4744-a932-0658087f49c3> | 2013-01-08 16:51:22 +0000 |
commit | fd45b36c041c0bbb1f9066592482d40790405812 (patch) | |
tree | 4d8bfcb76706a7c789f59536b0dbe8c8c8ced7a0 /nuttx | |
parent | 14f72f7a210648fe6eaaac3359ec76cab62c7278 (diff) | |
download | px4-firmware-fd45b36c041c0bbb1f9066592482d40790405812.tar.gz px4-firmware-fd45b36c041c0bbb1f9066592482d40790405812.tar.bz2 px4-firmware-fd45b36c041c0bbb1f9066592482d40790405812.zip |
Documentation update
git-svn-id: http://svn.code.sf.net/p/nuttx/code/trunk@5493 42af7a65-404d-4744-a932-0658087f49c3
Diffstat (limited to 'nuttx')
-rw-r--r-- | nuttx/Documentation/NuttxUserGuide.html | 129 | ||||
-rw-r--r-- | nuttx/libc/unistd/lib_execl.c | 8 | ||||
-rw-r--r-- | nuttx/libc/unistd/lib_execv.c | 6 |
3 files changed, 135 insertions, 8 deletions
diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html index 918b69d0f..89bc08942 100644 --- a/nuttx/Documentation/NuttxUserGuide.html +++ b/nuttx/Documentation/NuttxUserGuide.html @@ -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: January 7, 2013</p> + <p>Last Updated: January 8, 2013</p> </td> </tr> </table> @@ -651,7 +651,134 @@ pid_t vfork(void); </p> <H3><a name="execv">2.1.9 execv</a></H3> +<p> + <b>Function Prototype:</b> +</p> + <ul><pre> +#include <unistd.h> +#ifdef CONFIG_LIBC_EXECFUNCS +int execv(FAR const char *path, FAR char *const argv[]); +#endif +</pre></ul> +<p> + <b>Description:</b> + The standard <code>exec</code> family of functions will replace the current process image with a new process image. + The new image will be constructed from a regular, executable file called the new process image file. + There will be no return from a successful <code>exec</code>, because the calling process image is overlaid by the new process image. +</p> +<p> + Simplified <code>execl()</code> and <code>execv()</code> functions are provided by NuttX for compatibility. + NuttX is a tiny embedded RTOS that does not support processes and hence the concept of overlaying a tasks process image with a new process image does not make any sense. + In NuttX, these functions are wrapper functions that: +</p> +<ol> + <li> + Call the non-standard <code>binfmt</code> function <code>exec()</code>, and then + </li> + <li> + <code>exit(0)</code>. + </li> +</ol> +<p> + Note the inefficiency when <code>execv()</code> or <code>execl()</code> is called in the normal, two-step process: + (1) first call <code>vfork()</code> to create a new thread, then (2) call <code>execv()</code> or <code>execl()</code> to replace the new thread with a program from the file system. + Since the new thread will be terminated by the <code>execv()</code> or <code>execl()</code> call, it really served no purpose other than to support Unix compatility. +</p> +<p> + The non-standard binfmt function <code>exec()</code> needs to have (1) a symbol table that provides the list of symbols exported by the base code, and (2) the number of symbols in that table. + This information is currently provided to <code>exec()</code> from <code>execv()</code> or <code>execl()</code> via NuttX configuration settings: +</p> +<ul> + <li> + <code>CONFIG_LIBC_EXECFUNCS</code>: + Enable <code>execv()</code> and <code>execl()</code> support + </li> + <li> + <code>CONFIG_EXECFUNCS_SYMTAB</code>: + Symbol table used by <code>execv()</code> or <code>execl()</code>. + </li> + <li> + <code>CONFIG_EXECFUNCS_NSYMBOLS</code>: + Number of symbols in the symbol table + </li> +</ul> +<p> + As a result of the above, the current implementations of <code>execl()</code> and <code>execv()</code> suffer from some incompatibilities that may or may not be addressed in a future version of NuttX. + Other than just being an inefficient use of MCU resource, the most serious of these is that + the <code>exec</code>'ed task will not have the same task ID as the <code>vfork</code>'ed function. + So the parent function cannot know the ID of the <code>exec</code>'ed task.<p> +<p> + <b>Input Parameters:</b> +</p> +<ul> + <li> + <code>path</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> +</ul> +<p> + <b>Returned Value:</b> + This function does not return on success. + On failure, it 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> + Similar with the Unix interface of the same name. + There are, however, several compatibility issues as detailed in the description above. +</p> + <H3><a name="execl">2.1.10 execl</a></H3> +<p> + <b>Function Prototype:</b> +</p> + <ul><pre> +#include <unistd.h> +#ifdef CONFIG_LIBC_EXECFUNCS +int execl(FAR const char *path, ...); +#endif +</pre></ul> +<p> + <b>Description:</b> + <code>execl()</code> is functionally equivalent to <a href="#execv">execv()</a>, differing only in the form of its input parameters. + See the decription of <a href="#execv">execv()</a> for additional information. +<p> +<p> + <b>Input Parameters:</b> +</p> +<ul> + <li> + <code>path</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>...</code>: + A list of the string arguments to be recevied by the program. + Zero indicates the end of the list. + </li> +</ul> +<p> + <b>Returned Value:</b> + This function does not return on success. + On failure, it 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> + Similar with the Unix interface of the same name. + There are, however, several compatibility issues as detailed in the description of <a href="#execv">execv()</a>. +</p> <table width ="100%"> <tr bgcolor="#e4e4e4"> diff --git a/nuttx/libc/unistd/lib_execl.c b/nuttx/libc/unistd/lib_execl.c index ac3147343..fa50c1429 100644 --- a/nuttx/libc/unistd/lib_execl.c +++ b/nuttx/libc/unistd/lib_execl.c @@ -83,7 +83,7 @@ * step process: (1) first call vfork() to create a new thread, then (2) * call 'exec[l|v]()' to replace the new thread with a program from the * file system. Since the new thread will be terminated by the - * 'exec[l|v]()' call, it really served no purpose other than to suport + * 'exec[l|v]()' call, it really served no purpose other than to support * Unix compatility. * * The non-standard binfmt function 'exec()' needs to have (1) a symbol @@ -91,9 +91,9 @@ * (2) the number of symbols in that table. This information is currently * provided to 'exec()' from 'exec[l|v]()' via NuttX configuration settings: * - * CONFIG_LIBC_EXECFUNCS : Enable exec[l|v] Support + * CONFIG_LIBC_EXECFUNCS : Enable exec[l|v] support * CONFIG_EXECFUNCS_SYMTAB : Symbol table used by exec[l|v] - * CONFIG_EXECFUNCS_NSYMBOLS : Number of Symbols in the Table + * CONFIG_EXECFUNCS_NSYMBOLS : Number of symbols in the table * * As a result of the above, the current implementations of 'execl()' and * 'execv()' suffer from some incompatibilities that may or may not be @@ -108,7 +108,7 @@ * 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. - * arg0,... - A list of the string arguments to be recevied by the + * ... - A list of the string arguments to be recevied by the * program. Zero indicates the end of the list. * * Returned Value: diff --git a/nuttx/libc/unistd/lib_execv.c b/nuttx/libc/unistd/lib_execv.c index cad8ee307..b0f4136f1 100644 --- a/nuttx/libc/unistd/lib_execv.c +++ b/nuttx/libc/unistd/lib_execv.c @@ -104,7 +104,7 @@ extern struct symtab_s CONFIG_EXECFUNCS_SYMTAB; * step process: (1) first call vfork() to create a new thread, then (2) * call 'exec[l|v]()' to replace the new thread with a program from the * file system. Since the new thread will be terminated by the - * 'exec[l|v]()' call, it really served no purpose other than to suport + * 'exec[l|v]()' call, it really served no purpose other than to support * Unix compatility. * * The non-standard binfmt function 'exec()' needs to have (1) a symbol @@ -112,9 +112,9 @@ extern struct symtab_s CONFIG_EXECFUNCS_SYMTAB; * (2) the number of symbols in that table. This information is currently * provided to 'exec()' from 'exec[l|v]()' via NuttX configuration settings: * - * CONFIG_LIBC_EXECFUNCS : Enable exec[l|v] Support + * CONFIG_LIBC_EXECFUNCS : Enable exec[l|v] support * CONFIG_EXECFUNCS_SYMTAB : Symbol table used by exec[l|v] - * CONFIG_EXECFUNCS_NSYMBOLS : Number of Symbols in the Table + * CONFIG_EXECFUNCS_NSYMBOLS : Number of symbols in the table * * As a result of the above, the current implementations of 'execl()' and * 'execv()' suffer from some incompatibilities that may or may not be |