From 14a5bc69504838d858fbb9981c9171d9fd625f10 Mon Sep 17 00:00:00 2001
From: patacongo Last Updated: October 30, 2012 Last Updated: December 17, 2012
+ 1The
@@ -141,7 +141,7 @@ struct binary_s
{
/* Information provided to the loader to load and bind a module */
- FAR const char *filename; /* Full path to the binary to be loaded */
+ FAR const char *filename; /* Full path to the binary to be loaded1 */
FAR const char **argv; /* Argument list */
FAR const struct symtab_s *exports; /* Table of exported symbols */
int nexports; /* The number of symbols in exports[] */
@@ -164,6 +164,14 @@ struct binary_s
};
+
NuttX Binary Loader
-
+
+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:
register_binfmt()
unregister_binfmt()
unregister_binfmt()
+load_module()
unload_module()
exec_module()
exec()
exec()
PATH
traversal logic:
+exepath_init()
exepath_next()
exepath_release()
+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()
.
+
+ NULL
relpath 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
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.