Integrate PATH traversal logic and binary format logic

git-svn-id: http://svn.code.sf.net/p/nuttx/code/trunk@5441 42af7a65-404d-4744-a932-0658087f49c3

nuttx/include/nuttx/binfmt/binfmt.h

@@ -67,14 +67,21 @@ typedef FAR void *EXEPATH_HANDLE;
 typedef FAR void (*binfmt_ctor_t)(void);
 typedef FAR void (*binfmt_dtor_t)(void);
 
-/* This describes the file to be loaded */
+/* This describes the file to be loaded.
+ *
+ * NOTE: 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.
+ */
 
 struct symtab_s;
 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 loaded (See NOTE above) */
   FAR const char **argv;               /* Argument list */
   FAR const struct symtab_s *exports;  /* Table of exported symbols */
   int nexports;                        /* The number of symbols in exports[] */
@@ -229,7 +236,7 @@ int exec(FAR const char *filename, FAR const char **argv,
  *   Initialize for the traversal of each value in the PATH variable.  The
  *   usage is sequence is as follows:
  *
- *   1) Call exepath_init() to initialze for the traversal.  exepath_init()
+ *   1) Call 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().
  *   2) Call exepath_next() repeatedly to examine every file that lies
@@ -252,7 +259,7 @@ int exec(FAR const char *filename, FAR const char **argv,
 EXEPATH_HANDLE exepath_init(void);
 #endif
 
- /****************************************************************************
+/****************************************************************************
  * Name: exepath_next
  *
  * Description:
@@ -274,7 +281,7 @@ EXEPATH_HANDLE exepath_init(void);
  *   memory.  This memory must be freed by the called by calling kfree().
  *
  *   NULL is returned if no path is found to any file with the provided
- *   'relpath' from any absolute path in the file variable.  In this case,
+ *   '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().
  *
@@ -288,7 +295,7 @@ FAR char *exepath_next(EXEPATH_HANDLE handle, FAR const char *relpath);
  * Name: exepath_release
  *
  * Description:
- *   Release all resources set aside by exepath_release when the handle value
+ *   Release all resources set aside by 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.