Last Updated: October 30, 2012
+Last Updated: December 17, 2012
+ 1The filename must be the full, absolute path to the file to be executed unless CONFIG_BINFMT_EXEPATH is defined.
+ In that case, filename may be a relative path;
+ a set of candidate absolute paths will be generated using the PATH environment variable and load_module() will attempt to load each file that is found at those absolute paths.
+
Where the types binfmt_ctor_t and binfmt_dtor_t define the type of one C++ constructor or destructor:
PATH traversal logic:
+register_binfmt()Description:
+ Load a module into memory, bind it to an exported symbol take, and prep the module for execution. +
+
+ load_module() will use the filename field in the struct binary_s in order to locate the module to be loaded from the file system.
+ The filename must be the full, absolute path to the file to be executed unless CONFIG_BINFMT_EXEPATH is defined.
+ In that case, filename may be a relative path;
+ a set of candidate absolute paths will be generated using the PATH environment variable and load_module() will attempt to load each file that is found at those absolute paths.
+
Returned Value:
Description:
load_ and exec_module() into one call.
+ This is a convenience function that wraps load_ and exec_module() into one call.
Input Parameters:
filename: Fulll path to the binary to be loaded.filename: Full path to the binary to be loaded.argv: Argument list.exports: Table of exported symbols.exports: The number of symbols in exports.Returned Value:
OK) on success.
-On failure, it returns -1 (ERROR) with errno set appropriately.
+ This is an end-user function, so it follows the normal convention:
+ Returns 0 (OK) on success.
+ On failure, it returns -1 (ERROR) with errno set appropriately.
exepath_init()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +#ifdef CONFIG_BINFMT_EXEPATH +EXEPATH_HANDLE exepath_init(void); +#endif ++
Description:
+
+ Initialize for the traversal of each value in the PATH variable.
+ The usage is sequence is as follows:
+
exepath_init() to initialize for the traversal.
+ exepath_init() will return an opaque handle that can then be provided to exepath_next() and exepath_release().
+ exepath_next() repeatedly to examine every file that lies in the directories of the PATH variable.
+ exepath_release() to free resources set aside by exepath_init().
+ Input Parameters: None
+Returned Value:
+exepath_init() return a non-NULL, opaque handle that may subsequently be used in calls to exepath_next() and exepath_release().
+ On error, a NULL handle value will be returned.
+ The most likely cause of an error would be that the there is no value associated with the PATH variable.
+exepath_next()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +#ifdef CONFIG_BINFMT_EXEPATH +FAR char *exepath_next(EXEPATH_HANDLE handle, FAR const char *relpath); +#endif ++
Description:
+PATH variable in attempt to find the full path to an executable file when only a relative path is provided.
+Input Parameters:
+handle: The handle value returned by exepath_init().relpath: The relative path to the file to be found.Returned Value:
+
+ On success, a non-NULL pointer to a null-terminated string is provided.
+ This is the full path to a file that exists in the file system.
+ This function will verify that the file exists (but will not verify that it is marked executable).
+
+ NOTE: The string pointer return in the success case points to allocated memory.
+ This memory must be freed by the called by calling kfree().
+
+ NULLrelpath from any absolute path in the PATH variable.
+ In this case, there is no point in calling exepath_next() further; exepath_release() must be called to release resources set aside by expath_init().
+
exepath_release()Function Prototype:
++#include <:nuttx/binfmt/binfmt.h> +#ifdef CONFIG_BINFMT_EXEPATH +void exepath_release(EXEPATH_HANDLE handle); +#endif ++
Description:
+exepath_init when the handle value was created.
+ The handle value is invalid on return from this function.
+ Attempts to all exepath_next() or exepath_release() with such a stale handle will result in undefined (i.e., not good) behavior.
+Input Parameters:
+handle: The handle value returned by exepath_init().Returned Value: None
+
diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html
index 0ed46cba166..5361a28665e 100644
--- a/Documentation/NuttxPortingGuide.html
+++ b/Documentation/NuttxPortingGuide.html
@@ -12,7 +12,7 @@
NuttX RTOS Porting Guide-Last Updated: December 11, 2012 +Last Updated: December 17, 2012 |
CONFIG_BINFMT_DISABLE: By default, support for loadable binary formats is built.
This logic may be suppressed be defining this setting.
+ CONFIG_BINFMT_EXEPATH: Use the contents of the PATH environment variable to locate executable files. Default: n
+ CONFIG_PATH_INITIAL: The initial value of the PATH variable. This is the colon-separated list of absolute paths. E.g., "/bin:/usr/bin:/sbin"
+ CONFIG_BINFMT_CONSTRUCTORS: Build in support for C++ constructors in loaded modules.