Documentation update

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

TODO

@@ -866,7 +866,17 @@ o File system / Generic drivers (fs/, drivers/)
   Title:       dup AND dup2 WILL NOT WORK ON FILES IN A MOUNTED VOLUME
   Description: The current implementation of dup() and dup2() will only
                work with open device drivers and sockets.  It will not
-               work with open files in a file system.
+               work with open files in a file system.  Support for dup'ing
+               open files on a mounted volume has not been implemented yet.
+
+               There is a stubbed out, partial implemenation in fs/fs_files.c.
+               In would perform the dup2() operation by re-opening the file
+               and setting the file pointer.  The logic, however, would require
+               that we remember the (relative) path to the file in the mounted
+               volume for each open file.
+
+               An option might to add a dup() method to the file system
+               mountpoint interface.
 
                A limitation that results from this is that you cannot
                redirect I/O to an from and file.

include/spawn.h

@@ -112,7 +112,7 @@ extern "C"
 #ifdef CONFIG_BINFMT_EXEPATH
 int posix_spawnp(FAR pid_t *pid, FAR const char *path,
       FAR const posix_spawn_file_actions_t *file_actions,
-      FAR const posix_spawnattr_t * attr,
+      FAR const posix_spawnattr_t *attr,
       FAR char *const argv[], FAR char *const envp[]);
 #define posix_spawn(pid,path,file_actions,attr,argv,envp) \
       posix_spawnp(pid,path,file_actions,attr,argv,envp)

libc/spawn/lib_ps.c

@@ -440,7 +440,7 @@ static int spawn_proxy(int argc, char *argv[])
  *
  * Description:
  *   The posix_spawn() and posix_spawnp() functions will create a new,
- *   child task, constructed a regular executable file.
+ *   child task, constructed from a regular executable file.
  *
  * Input Parameters:
  *
@@ -479,9 +479,9 @@ static int spawn_proxy(int argc, char *argv[])
  *       not supported.  NuttX does not support process groups.
  *     - POSIX_SPAWN_SETSCHEDPARAM: Set new tasks priority to the sched_param
  *       value.
- *     - POSIX_SPAWN_SETSCHEDULER: Set the new task's scheduler priority to
+ *     - POSIX_SPAWN_SETSCHEDULER: Set the new task's scheduler policy to
  *       the sched_policy value.
- *     - POSIX_SPAWN_RESETIDS: Resetting of effective user ID of the child
+ *     - POSIX_SPAWN_RESETIDS: Resetting of the effective user ID of the child
  *       process is not supported.  NuttX does not support effective user
  *       IDs.
  *     - POSIX_SPAWN_SETSIGMASK: Set the new task's signal mask.
@@ -514,11 +514,12 @@ static int spawn_proxy(int argc, char *argv[])
  *     CONFIG_BINFMT_EXEPATH is defined, then only posix_spawnp() behavior
  *     is supported; otherwise, only posix_spawn behavior is supported.
  *   - The 'envp' argument is not used and the 'environ' variable is not
- *     altered (NuttX does not support the 'environ' variable.
+ *     altered (NuttX does not support the 'environ' variable).
  *   - Process groups are not supported (POSIX_SPAWN_SETPGROUP).
  *   - Effective user IDs are not supported (POSIX_SPAWN_RESETIDS).
- *   - Signal masks and signal default actions cannot be modified in the
- *     newly executed task (POSIX_SPAWN_SETSIGDEF and POSIX_SPAWN_SETSIGMASK).
+ *   - Signal default actions cannot be modified in the newly task executed
+ *     because NuttX does not support default signal actions
+ *     (POSIX_SPAWN_SETSIGDEF).
  *
  * POSIX Compatibility
  *   - The value of the argv[0] received by the child task is assigned by

libc/spawn/lib_psa_getschedparam.c

@@ -57,7 +57,7 @@
  *
  * Input Parameters:
  *   attr - The address spawn attributes to be queried.
- *   flags - The location to return the sched_priority value.
+ *   flags - The location to return the spawn-schedparam value.
  *
  * Returned Value:
  *   On success, these functions return 0; on failure they return an error

libc/spawn/lib_psa_getsigmask.c

@@ -59,7 +59,7 @@
  *
  * Input Parameters:
  *   attr - The address spawn attributes to be queried.
- *   sigmask  - The location to return the spawn flags
+ *   sigmask  - The location to return the signal mask
  *
  * Returned Value:
  *   On success, these functions return 0; on failure they return an error

libc/spawn/lib_psa_setschedparam.c

@@ -56,8 +56,8 @@
  *   by attr.
  *
  * Input Parameters:
- *   attr - The address spawn attributes to be used.
- *   parm - The new sched_priority to set.
+ *   attr  - The address spawn attributes to be used.
+ *   param - The new sched_priority to set.
  *
  * Returned Value:
  *   On success, these functions return 0; on failure they return an error

libc/spawn/lib_psfa_addopen.c

@@ -57,8 +57,8 @@
  * Description:
  *   The posix_spawn_file_actions_addopen() function adds an open operation
  *   to the list of operations associated with the object referenced by
- *   file_actions, for subsequent use in a call to posix_spawn(2) or
- *   posix_spawnp(2).  The descriptor referred to by fd is opened using
+ *   file_actions, for subsequent use in a call to posix_spawn() or
+ *   posix_spawnp().  The descriptor referred to by fd is opened using
  *   the path, oflag, and mode arguments as if open() had been called on it
  *   prior to the new child process starting execution.  The string path is
  *   copied by the posix_spawn_file_actions_addopen() function during this
@@ -66,8 +66,8 @@
  *
  * Input Parameters:
  *   file_actions - The posix_spawn_file_actions_t to append the action.
- *   fd - The path to be opened.
- *   path - The first file descriptor to be argument to dup2.
+ *   fd - The file descriptor to be opened.
+ *   path - The path to be opened.
  *   oflags - Open flags
  *   mode - File creation mode
  *

libc/spawn/lib_psfa_init.c

@@ -50,7 +50,7 @@
  *
  * Description:
  *   The posix_spawn_file_actions_init() function initializes the object
- *   referenced by file_actions, to an empty set of file actions for
+ *   referenced by file_actions to an empty set of file actions for
  *   subsequent use in a call to posix_spawn() or posix_spawnp().
  *
  * Input Parameters: