User's Manual
by
Gregory Nutt
-
Last Updated: January 7, 2013
+Last Updated: January 8, 2013
@@ -651,7 +651,134 @@ pid_t vfork(void);+ Function Prototype: +
++#include <unistd.h> +#ifdef CONFIG_LIBC_EXECFUNCS +int execv(FAR const char *path, FAR char *const argv[]); +#endif ++
+ 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:
+
binfmt function exec(), and then
+ exit(0).
+
+ 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:
+
CONFIG_LIBC_EXECFUNCS:
+ Enable execv() and execl() support
+ CONFIG_EXECFUNCS_SYMTAB:
+ Symbol table used by execv() or execl().
+ CONFIG_EXECFUNCS_NSYMBOLS:
+ Number of symbols in the symbol table
+
+ 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: +
+path:
+ 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.
+
+
+ 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. +
++ Function Prototype: +
++#include <unistd.h> +#ifdef CONFIG_LIBC_EXECFUNCS +int execl(FAR const char *path, ...); +#endif ++
+ 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: +
+path:
+ 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.
+ ...:
+ A list of the string arguments to be recevied by the program.
+ Zero indicates the end of the list.
+
+
+ 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(). +