From fd45b36c041c0bbb1f9066592482d40790405812 Mon Sep 17 00:00:00 2001 From: patacongo Date: Tue, 8 Jan 2013 16:51:22 +0000 Subject: Documentation update git-svn-id: http://svn.code.sf.net/p/nuttx/code/trunk@5493 42af7a65-404d-4744-a932-0658087f49c3 --- nuttx/Documentation/NuttxUserGuide.html | 129 +++++++++++++++++++++++++++++++- nuttx/libc/unistd/lib_execl.c | 8 +- nuttx/libc/unistd/lib_execv.c | 6 +- 3 files changed, 135 insertions(+), 8 deletions(-) (limited to 'nuttx') 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 @@

NuttX Operating System

User's Manual

by

Gregory Nutt

-

Last Updated: January 7, 2013

+

Last Updated: January 8, 2013

@@ -651,7 +651,134 @@ pid_t vfork(void);

2.1.9 execv

+

+ Function Prototype: +

+ +

+ Description: + The standard exec 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 exec, because the calling process image is overlaid by the new process image. +

+

+ Simplified execl() and execv() 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: +

+
    +
  1. + Call the non-standard binfmt function exec(), and then +
    2. +
  2. + exit(0). +
    3. +
+

+ Note the inefficiency when execv() or execl() is called in the normal, two-step process: + (1) first call vfork() to create a new thread, then (2) call execv() or execl() to replace the new thread with a program from the file system. + Since the new thread will be terminated by the execv() or execl() call, it really served no purpose other than to support Unix compatility. +

+

+ The non-standard binfmt function exec() 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 exec() from execv() or execl() via NuttX configuration settings: +

+ +

+ As a result of the above, the current implementations of execl() and execv() 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 exec'ed task will not have the same task ID as the vfork'ed function. + So the parent function cannot know the ID of the exec'ed task.

+

+ Input Parameters: +

+ +

+ Returned Value: + This function does not return on success. + On failure, it will return -1 (ERROR) and will set the errno value appropriately. +

+ Assumptions/Limitations: +

+

+ POSIX Compatibility: + Similar with the Unix interface of the same name. + There are, however, several compatibility issues as detailed in the description above. +

+

2.1.10 execl

+

+ Function Prototype: +

+ +

+ Description: + execl() is functionally equivalent to execv(), differing only in the form of its input parameters. + See the decription of execv() for additional information. +

+

+ Input Parameters: +

+ +

+ Returned Value: + This function does not return on success. + On failure, it will return -1 (ERROR) and will set the errno value appropriately. +

+ Assumptions/Limitations: +

+

+ POSIX Compatibility: + Similar with the Unix interface of the same name. + There are, however, several compatibility issues as detailed in the description of execv(). +

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 -- cgit v1.2.3