Add basic hooks to support a PATH variable (more is needed)

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

include/nuttx/binfmt/binfmt.h

@@ -54,6 +54,14 @@
 /****************************************************************************
  * Public Types
  ****************************************************************************/
+/* EXEPATH_HANDLE is an opaque handle used to traverse the absolute paths
+ * assigned to the PATH environment variable.
+ */
+
+#if !defined(CONFIG_BINFMT_DISABLE) && defined(CONFIG_BINFMT_EXEPATH)
+typedef FAR void *EXEPATH_HANDLE;
+#endif
+
 /* The type of one C++ constructor or destructor */
 
 typedef FAR void (*binfmt_ctor_t)(void);
@@ -100,12 +108,9 @@ struct binfmt_s
  * Public Data
  ****************************************************************************/
 
-#undef EXTERN
 #if defined(__cplusplus)
-#define EXTERN extern "C"
-extern "C" {
-#else
-#define EXTERN extern
+extern "C"
+{
 #endif
 
 /****************************************************************************
@@ -125,7 +130,7 @@ extern "C" {
  *
  ****************************************************************************/
 
-EXTERN int register_binfmt(FAR struct binfmt_s *binfmt);
+int register_binfmt(FAR struct binfmt_s *binfmt);
 
 /****************************************************************************
  * Name: unregister_binfmt
@@ -140,7 +145,7 @@ EXTERN int register_binfmt(FAR struct binfmt_s *binfmt);
  *
  ****************************************************************************/
 
-EXTERN int unregister_binfmt(FAR struct binfmt_s *binfmt);
+int unregister_binfmt(FAR struct binfmt_s *binfmt);
 
 /****************************************************************************
  * Name: load_module
@@ -156,7 +161,7 @@ EXTERN int unregister_binfmt(FAR struct binfmt_s *binfmt);
  *
  ****************************************************************************/
 
-EXTERN int load_module(FAR struct binary_s *bin);
+int load_module(FAR struct binary_s *bin);
 
 /****************************************************************************
  * Name: unload_module
@@ -177,7 +182,7 @@ EXTERN int load_module(FAR struct binary_s *bin);
  *
  ****************************************************************************/
 
-EXTERN int unload_module(FAR const struct binary_s *bin);
+int unload_module(FAR const struct binary_s *bin);
 
 /****************************************************************************
  * Name: exec_module
@@ -192,7 +197,7 @@ EXTERN int unload_module(FAR const struct binary_s *bin);
  *
  ****************************************************************************/
 
-EXTERN int exec_module(FAR const struct binary_s *bin, int priority);
+int exec_module(FAR const struct binary_s *bin, int priority);
 
 /****************************************************************************
  * Name: exec
@@ -214,8 +219,91 @@ EXTERN int exec_module(FAR const struct binary_s *bin, int priority);
  *
  ****************************************************************************/
 
-EXTERN int exec(FAR const char *filename, FAR const char **argv,
-                FAR const struct symtab_s *exports, int nexports);
+int exec(FAR const char *filename, FAR const char **argv,
+         FAR const struct symtab_s *exports, int nexports);
+
+/****************************************************************************
+ * Name: exepath_init
+ *
+ * Description:
+ *   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()
+ *      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
+ *      in the directories of the PATH variable
+ *   3) Call exepath_release() to free resources set aside by exepath_init().
+ *
+ * Input Parameters:
+ *   None
+ *
+ * Returned Value:
+ *   On success, 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.
+ *
+ ****************************************************************************/
+
+#if !defined(CONFIG_BINFMT_DISABLE) && defined(CONFIG_BINFMT_EXEPATH)
+EXEPATH_HANDLE exepath_init(void);
+#endif
+
+ /****************************************************************************
+ * Name: exepath_next
+ *
+ * Description:
+ *   Traverse all possible values in the 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 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,
+ *   there is no point in calling exepath_next() further; exepath_release()
+ *   must be called to release resources set aside by expath_init().
+ *
+ ****************************************************************************/
+
+#if !defined(CONFIG_BINFMT_DISABLE) && defined(CONFIG_BINFMT_EXEPATH)
+FAR char *exepath_next(EXEPATH_HANDLE handle, FAR const char *relpath);
+#endif
+
+/****************************************************************************
+ * Name: exepath_release
+ *
+ * Description:
+ *   Release all resources set aside by exepath_release 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
+ *
+ ****************************************************************************/
+
+#if !defined(CONFIG_BINFMT_DISABLE) && defined(CONFIG_BINFMT_EXEPATH)
+void exepath_release(EXEPATH_HANDLE handle);
+#endif
 
 #undef EXTERN
 #if defined(__cplusplus)