<sup>1</sup>The <code>filename</code> must be the full, absolute path to the file to be executed unless <code>CONFIG_BINFMT_EXEPATH</code> is defined.
In that case, <code>filename</code> may be a relative path;
a set of candidate absolute paths will be generated using the <code>PATH</code> environment variable and <ahref="#load_module"><code>load_module()</code></a> will attempt to load each file that is found at those absolute paths.
</small></p></ul>
</p>
<p>
Where the types <code>binfmt_ctor_t</code> and <code>binfmt_dtor_t</code> define the type of one C++ constructor or destructor:
</p>
@ -175,15 +183,31 @@ typedef FAR void (*binfmt_dtor_t)(void);
@@ -175,15 +183,31 @@ typedef FAR void (*binfmt_dtor_t)(void);
<h2>2.3 <aname="binfmtfuncif">Binary Loader Function Interfaces</a></h2>
@ -224,7 +248,15 @@ int load_module(FAR struct binary_s *bin);
@@ -224,7 +248,15 @@ int load_module(FAR struct binary_s *bin);
</pre></ul>
<p><b>Description:</b></p>
<ul>
Load a module into memory, bind it to an exported symbol take, and prep the module for execution.
<p>
Load a module into memory, bind it to an exported symbol take, and prep the module for execution.
</p>
<p>
<code>load_module()</code> will use the <code>filename</code> field in the <ahref="#binfmtdata"><code>struct binary_s</code></a> in order to locate the module to be loaded from the file system.
The <code>filename</code> must be the full, absolute path to the file to be executed unless <code>CONFIG_BINFMT_EXEPATH</code> is defined.
In that case, <code>filename</code> may be a relative path;
a set of candidate absolute paths will be generated using the <code>PATH</code> environment variable and <code>load_module()</code> will attempt to load each file that is found at those absolute paths.
</p>
</ul>
<p><b>Returned Value:</b></p>
<ul>
@ -281,21 +313,110 @@ int exec(FAR const char *filename, FAR const char **argv,
@@ -281,21 +313,110 @@ int exec(FAR const char *filename, FAR const char **argv,
</pre></ul>
<p><b>Description:</b></p>
<ul>
This is a convenience function that wraps <code>load_</code> and <code>exec_module()</code> into one call.
This is a convenience function that wraps <code>load_</code> and <code>exec_module()</code> into one call.
</ul>
<p><b>Input Parameters:</b></p>
<ul>
<li><code>filename</code>: Fulll path to the binary to be loaded.</li>
<li><code>filename</code>: Full path to the binary to be loaded.</li>
<li><code>argv</code>: Argument list.</li>
<li><code>exports</code>: Table of exported symbols.</li>
<li><code>exports</code>: The number of symbols in exports.</li>
</ul>
<p><b>Returned Value:</b></p>
<ul>
This is an end-user function, so it follows the normal convention:
Returns 0 (<code>OK</code>) on success.
On failure, it returns -1 (<code>ERROR</code>) with <code>errno</code> set appropriately.
This is an end-user function, so it follows the normal convention:
Returns 0 (<code>OK</code>) on success.
On failure, it returns -1 (<code>ERROR</code>) with <code>errno</code> set appropriately.
Initialize for the traversal of each value in the <code>PATH</code> variable.
The usage is sequence is as follows:
</p>
<ol>
<li>
Call <code>exepath_init()</code> to initialize for the traversal.
<code>exepath_init()</code> will return an opaque handle that can then be provided to <code>exepath_next()</code> and <code>exepath_release()</code>.
</li>
<li>
Call <code>exepath_next()</code> repeatedly to examine every file that lies in the directories of the <code>PATH</code> variable.
</li>
<li>
Call <code>exepath_release()</code> to free resources set aside by <code>exepath_init()</code>.
</li>
</ol>
</ul>
<p><b>Input Parameters:</b><i>None</i></p>
<p><b>Returned Value:</b></p>
<ul>
On success, <code>exepath_init()</code> return a non-<code>NULL</code>, opaque handle that may subsequently be used in calls to <code>exepath_next()</code> and <code>exepath_release()</code>.
On error, a <code>NULL</code> handle value will be returned.
The most likely cause of an error would be that the there is no value associated with the <code>PATH</code> variable.
FAR char *exepath_next(EXEPATH_HANDLE handle, FAR const char *relpath);
#endif
</pre></ul>
<p><b>Description:</b></p>
<ul>
Traverse all possible values in the <code>PATH</code> variable in attempt to find the full path to an executable file when only a relative path is provided.
</ul>
<p><b>Input Parameters:</b></p>
<ul>
<li><code>handle</code>: The handle value returned by <code>exepath_init()</code>.</li>
<li><code>relpath</code>: The relative path to the file to be found.</li>
</ul>
<p><b>Returned Value:</b></p>
<ul>
<p>
On success, a non-<code>NULL</code> 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).
</p>
<p>
NOTE: The string pointer return in the success case points to allocated memory.
This memory must be freed by the called by calling <code>kfree()</code>.
</p>
<p>
<code>NULL</code is returned if no path is found to any file with the provided <code>relpath</colde> from any absolute path in the <code>PATH</code> variable.
In this case, there is no point in calling <code>exepath_next()</code> further; <code>exepath_release()</code> must be called to release resources set aside by <code>expath_init()</code>.
Release all resources set aside by <code>exepath_init</code> when the handle value was created.
The handle value is invalid on return from this function.
Attempts to all <code>exepath_next()</code> or <code>exepath_release()</code> with such a <i>stale</i> handle will result in undefined (i.e., not good) behavior.
</ul>
<p><b>Input Parameters:</b></p>
<ul>
<li><code>handle</code>: The handle value returned by <code>exepath_init()</code>.</li>
<code>CONFIG_BINFMT_DISABLE</code>: By default, support for loadable binary formats is built.
This logic may be suppressed be defining this setting.
</li>
<li>
<code>CONFIG_BINFMT_EXEPATH</code>: Use the contents of the <code>PATH</code> environment variable to locate executable files. Default: n
</li>
<li>
<code>CONFIG_PATH_INITIAL</code>: The initial value of the <code>PATH</code> variable. This is the colon-separated list of absolute paths. E.g., <code>"/bin:/usr/bin:/sbin"</code>
</li>
<li>
<code>CONFIG_BINFMT_CONSTRUCTORS</code>: Build in support for C++ constructors in loaded modules.
patacongo
12 years ago