From 5a180ec4940c993311eedddaa13194f9977968f1 Mon Sep 17 00:00:00 2001 From: patacongo Date: Fri, 11 Jan 2013 21:51:54 +0000 Subject: Documentation update git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@5512 42af7a65-404d-4744-a932-0658087f49c3 --- nuttx/Documentation/NuttxUserGuide.html | 748 +++++++++++++++++++++++++++++--- 1 file changed, 694 insertions(+), 54 deletions(-) (limited to 'nuttx/Documentation') diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html index 89bc08942..c6eabd29a 100644 --- a/nuttx/Documentation/NuttxUserGuide.html +++ b/nuttx/Documentation/NuttxUserGuide.html @@ -13,7 +13,7 @@

NuttX Operating System

User's Manual

by

Gregory Nutt

-

Last Updated: January 8, 2013

+

Last Updated: January 11, 2013

@@ -193,18 +193,52 @@ paragraphs.

Task Control Interfaces. The following task control interfaces are provided by NuttX:

+

+ Non-standard task control interfaces inspired by VxWorks interfaces: +

+

+ Standard interfaces +

+ +

+ Standard vfork and exec[v|l] interfaces: +

+ +

+ Standard posix_spawn interfaces: +

+ +

2.1.1 task_create

@@ -472,53 +506,7 @@ STATUS taskDelete(int tid);
  • Deletion of self is supported, but only because task_delete() will re-direct processing to exit(). -

    2.1.5 exit

    - -

    -Function Prototype: -

    -    #include <sched.h>
-    void exit(int code);
-
-    #include <nuttx/unistd.h>
-    void _exit(int code);
-
    - -

    -Description: This function causes the calling task to cease -to exist -- its stack and TCB will be deallocated. exit differs from -_exit in that it flushes streams, closes file descriptors and will -execute any function registered with atexit() or on_exit(). -

    -Input Parameters: -

    - -

    -Returned Value: None. - -

    -Assumptions/Limitations: - -

    -POSIX Compatibility: This is equivalent to the ANSI interface: -

    -    void exit(int code);
-
    -And the UNIX interface: -
    -    void _exit(int code);
-
    - -

    - The NuttX exit() differs from ANSI exit() in the following ways: -

    - - -

    2.1.6 task_restart

    +

    2.1.5 task_restart

    Function Prototype:

    +

    2.1.6 exit

    + +

    +Function Prototype: +

    +    #include <sched.h>
+    void exit(int code);
+
+    #include <nuttx/unistd.h>
+    void _exit(int code);
+
    + +

    +Description: This function causes the calling task to cease +to exist -- its stack and TCB will be deallocated. exit differs from +_exit in that it flushes streams, closes file descriptors and will +execute any function registered with atexit() or on_exit(). +

    +Input Parameters: +

    + +

    +Returned Value: None. + +

    +Assumptions/Limitations: + +

    +POSIX Compatibility: This is equivalent to the ANSI interface: +

    +    void exit(int code);
+
    +And the UNIX interface: +
    +    void _exit(int code);
+
    + +

    + The NuttX exit() differs from ANSI exit() in the following ways: +

    + +

    2.1.7 getpid

    @@ -780,6 +814,595 @@ int execl(FAR const char *path, ...); There are, however, several compatibility issues as detailed in the description of execv().

    +

    2.1.11 posix_spawn and posix_spawnp

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawn() and posix_spawnp() functions will create a new, child task, constructed from a regular executable file.

    +

    +

    + Input Parameters: +

    + +

    + Returned Value: + posix_spawn() and posix_spawnp() will return zero on success. + Otherwise, an error number will be returned as the function return value to indicate the error: +

    + +

    + Assumptions/Limitations: +

    + +

    + POSIX Compatibility: + The value of the argv[0] received by the child task is assigned by NuttX. + For the caller of posix_spawn(), the provided argv[0] will correspond to argv[1] received by the new task. +

    + +

    2.1.12 posix_spawn_file_actions_init

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawn_file_actions_init() function initializes the object 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: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h>. +

    + +

    2.1.13 posix_spawn_file_actions_destroy

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawn_file_actions_destroy() function destroys the object referenced by file_actions which was previously intialized by posix_spawn_file_actions_init(), returning any resources obtained at the time of initialization to the system for subsequent reuse. + A posix_spawn_file_actions_t may be reinitialized after having been destroyed, but must not be reused after destruction, unless it has been reinitialized. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.14 posix_spawn_file_actions_addclose

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawn_file_actions_addclose() function adds a close operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). + The descriptor referred to by fd is closed as if close() had been called on it prior to the new child process starting execution. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.15 posix_spawn_file_actions_adddup2

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawn_file_actions_adddup2() function adds a dup2 operation to the list of operations associated with the object referenced by file_actions, for subsequent use in a call to posix_spawn() or posix_spawnp(). + The descriptor referred to by fd2 is created as if dup2() had been called on fd1 prior to the new child process starting execution. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.16 posix_spawn_file_actions_addopen

    +

    + Function Prototype: +

    + +

    + 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() 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 process, so storage need not be persistent in the caller. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.17 posix_spawnattr_init

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_init() function initializes the object referenced by attr, to an empty set of spawn attributes for subsequent use in a call to posix_spawn() or posix_spawnp(). +

    +

    + Then the spawn attributes are no longer needed, they should be destroyed by calling posix_spawnattr_destroyed(). + In NuttX, however, posix_spawnattr_destroyed() is just stub: +

    + +

    + For portability, the convention of calling posix_spawnattr_destroyed() when the attributes are not longer needed should still be followed. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.18 posix_spawnattr_getflags

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_getflags() function will obtain the value of the spawn-flags attribute from the attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.19 posix_spawnattr_getschedparam

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_getschedparam() function will obtain the value of the spawn-schedparam attribute from the attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.20 posix_spawnattr_getschedpolicy

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_getschedpolicy() function will obtain the value of the spawn-schedpolicy attribute from the attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.21 posix_spawnattr_getsigmask

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_getsigdefault() function will obtain the value of the spawn-sigmask attribute from the attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.22 posix_spawnattr_setflags

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_setflags() function will set the spawn-flags attribute in an initialized attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.23 posix_spawnattr_setschedparam

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_setschedparam() function will set the spawn-schedparam attribute in an initialized attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.24 posix_spawnattr_setschedpolicy

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_setschedpolicy() function will set the spawn-schedpolicy attribute in an initialized attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + +

    2.1.25 posix_spawnattr_setsigmask

    +

    + Function Prototype: +

    + +

    + Description: + The posix_spawnattr_setsigmask() function will set the spawn-sigmask attribute in an initialized attributes object referenced by attr. +

    +

    + Input Parameters: +

    + +

    + Returned Value: + On success, this function returns 0; on failure it will return an error number from <errno.h> +

    + - + + -
    @@ -8395,13 +9018,30 @@ notify a task when a message is available on a queue.
  • on_exit
  • open
  • opendir
    • -
  • OS Interfaces
  • pause
  • pipe
  • poll
  • poll.h
    • +    		 +
  • posix_spawn
    • +
  • posix_spawn_file_actions_addclose
    • +
  • posix_spawn_file_actions_adddup2
    • +
  • posix_spawn_file_actions_addopen
    • +
  • posix_spawn_file_actions_destroy
    • +
  • posix_spawn_file_actions_init
    • +
  • posix_spawnattr_init
    • +
  • posix_spawnattr_destroy
    • +
  • posix_spawnattr_getflags
    • +
  • posix_spawnattr_getschedparam
    • +
  • posix_spawnattr_getschedpolicy
    • +
  • posix_spawnattr_getsigmask
    • +
  • posix_spawnattr_setflags
    • +
  • posix_spawnattr_setschedparam
    • +
  • posix_spawnattr_setschedpolicy
    • +
  • posix_spawnattr_setsigmask
    • +
  • posix_spawnp
  • printf
  • Pthread Interfaces
  • pthread_attr_destroy
    • @@ -8467,6 +9107,8 @@ notify a task when a message is available on a queue.
  • recv
  • recvfrom
  • rename
    • +
  • rmdir
  • rewinddir
  • ROM disk driver
    • @@ -8474,8 +9116,6 @@ notify a task when a message is available on a queue.
  • sched_getparam
  • sched_get_priority_max
  • sched_get_priority_min
    • -
  • sched_get_rr_interval
  • sched_lockcount
  • sched_lock
    • -- cgit v1.2.3