diff options
Diffstat (limited to 'nuttx/Documentation/NuttxUserGuide.html')
-rw-r--r-- | nuttx/Documentation/NuttxUserGuide.html | 356 |
1 files changed, 270 insertions, 86 deletions
diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html index 46b4b2be44..7f0b7e5bf0 100644 --- a/nuttx/Documentation/NuttxUserGuide.html +++ b/nuttx/Documentation/NuttxUserGuide.html @@ -21,7 +21,7 @@ User's Manual <p> Gregory Nutt <p> -<small>Last Update: May 27, 2007</small> +<small>Last Update: June 30, 2007</small> </center> <h1>1.0 <A NAME="Introduction">Introduction</a></h1> @@ -53,7 +53,8 @@ Gregory Nutt <li>Paragraph 2.7 <a href="#ClocksNTimers">Clocks and Timers</a></li> <li>Paragraph 2.8 <a href="#Signals">Signal Interfaces</a></li> <li>Paragraph 2.9 <a href="#Pthread">Pthread Interfaces</a></li> - <li>Paragraph 2.10 <a href="#FileSystem">Filesystem Interfaces</a></li> + <li>Paragraph 2.10 <a href="#Environ">Environment Variables</a></li> + <li>Paragraph 2.11 <a href="#FileSystem">Filesystem Interfaces</a></li> </ul> </li> <li> @@ -2208,9 +2209,7 @@ queue. The specified watchdog function will be called from the interrupt level after the specified number of ticks has elapsed. Watchdog timers may be started from the interrupt level. <p> -Watchdog times execute in the context of the timer interrupt handler, but -with the PIC/PID address environment that was in place when wd_start() -was called. +Watchdog times execute in the context of the timer interrupt handler. <p> Watchdog timers execute only once. <p> @@ -5502,6 +5501,272 @@ interface of the same name. <b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name. </p> +<h1><a name="Environ">2.10 Environment Variables</a></h1> +<p><b>Overview</b>. + NuttX supports environment variables that can be used to control the behavior of programs. + In the spirit of NuttX the environment variable behavior attempts to emulate the behavior of + environment variables in the mulit-processing OS: +</p> +<ul> + <li><b>Task environments</b>. + When a new task is created using <a href="#taskcreate">task_create</a>, the environment + of the child task is an inherited, exact copy of the environment of the parent. + However, after child task has been created, subsequent operations by the child task on + its environment does not alter the environment of the parent. + No do operations by the parent effect the child's environment. + The environments start identical but are independent and may diverge. + </li> + <li><b>Thread environments</b>. + When a pthread is created using <a href="#pthreadcreate">pthread_create</a>, the child + thread also inherits that envirnment of the parent. + However, the child does not recieve a copy of the environment but, rather, shares the same + environment. + Changes to the environment are visiable to all threads with the same parentage. + </li> +</ul> +<p><b>Programming Interfaces</b>. + The following environment variable programming interfaces are provided by Nuttx and are + described in detail in the following paragraphs. +</p> +<ul> + <li><a href="#getenv">2.10.1 <code>getenv</code></a></li> + <li><a href="#putenv">2.10.2 <code>putenv</code></a></li> + <li><a href="#clearenv">2.10.3 <code>clearenv</code></a></li> + <li><a href="#setenv">2.10.4 <code>setenv</code></a></li> + <li><a href="#unsetenv">2.10.5 <code>unsetenv</code></a></li> +</ul> +<p><b>Disabling Environment Variable Support</b>. + All support for environment variables can be disabled by setting <code>CONFIG_DISABLE_ENVIRONMENT</code> + in the board configuration file. +</p> + +<h2><a name="getenv">2.10.1 <code>getenv</code></a></h2> +<p> + <b>Function Prototype:</b> +</p> +<pre> + #include <stdlib.h> + FAR char *getenv(const char *name); +</pre> +<p> + <b>Description:</b> + The <code>getenv()</code> function searches the environment list for a string that + matches the string pointed to by <code>name</code>. +</p> +<p> + <b>Input Parameters:</b> +</p> +<p> +<ul> + <li> + <code>name</code>. + The name of the variable to find. + </li> +</ul> +<p> + <b>Returned Values:</b> + The value of the valiable (read-only) or NULL on failure. +</p> + +<h2><a name="putenv">2.10.2 <code>putenv</code></a></h2> +<p> + <b>Function Prototype:</b> +</p> +<pre> + #include <stdlib.h> + int putenv(char *string); +</pre> +<p> + <b>Description:</b> + The <code>putenv()</code> function adds or changes the value of environment variables. + The argument string is of the form <i>name=value</i>. If name does not already + exist in the environment, then string is added to the environment. If + name does exist, then the value of name in the environment is changed to + value. +</p> +<p> + <b>Input Parameters:</b> +</p> +<p> +<ul> + <li> + <code>string</code> + name=value string describing the environment setting to add/modify. + </li> +</ul> +<p> + <b>Returned Values:</b> + Zero on sucess. +</p> + +<h2><a name="clearenv">2.10.3 <code>clearenv</code></a></h2> +<p> + <b>Function Prototype:</b> +</p> +<pre> + #include <stdlib.h> + int clearenv(void); +</pre> +<p> + <b>Description:</b> + The <code>clearenv()</code> function clears the environment of all name-value pairs + and sets the value of the external variable environ to NULL. +</p> +<p> + <b>Input Parameters:</b> + None +</p> +<p> + <b>Returned Values:</b> + Zero on success. +</p> + +<h2><a name="setenv">2.10.4 <code>setenv</code></a></h2> +<p> + <b>Function Prototype:</b> +</p> +<pre> + #include <stdlib.h> + int setenv(const char *name, const char *value, int overwrite); +</pre> +<p> + <b>Description:</b> + The <code>setenv()</code> function adds the variable <code>name</code> to the environment with the + specified <code>value</code> if the variable <code>name</code> does not exist. If the <code>name</code> + does exist in the environment, then its value is changed to <code>value</code> if <code>overwrite</code> + is non-zero; if <code>overwrite</code> is zero, then the value of <code>name</code> is unaltered. +</p> +<p> + <b>Input Parameters:</b> +</p> +<p> +<ul> + <li> + <code>name</code> + The name of the variable to change. + </li> + <li> + <code>value</code> + The new value of the variable. + </li> + <li> + <code>value</code> + Replace any existing value if non-zero. + </li> +</ul> +<p> + <b>Returned Values:</b> + Zero on success. +</p> + +<h2><a name="unsetenv">2.10.5 <code>unsetenv</code></a></h2> +<p> + <b>Function Prototype:</b> +</p> +<pre> + #include <stdlib.h> + int unsetenv(const char *name); +</pre> +<p> + <b>Description:</b> + The <code>unsetenv()</code> function deletes the variable <code>name</code> from the environment. +</p> +<p> + <b>Input Parameters:</b> +</p> +<p> +<ul> + <li> + <code>name</code> + The name of the variable to delete. + </li> +</ul> +<p> + <b>Returned Values:</b> + Zero on success. +</p> + +<h1><a name="FileSystem">2.11 Filesystem Interfaces</a></h1> +<p> + The NuttX filesystem is very simple; it does not involve any block drivers or + particular filesystem (like FAT or EXT2 etc.). + The NuttX filesystem simply supports a set a filesystem APIs + (<code>open()</code>, <code>close()</code>, <code>read()</code>, <code>write</code>, etc.) + and a registration mechanism that allows devices drivers to a associated with <i>nodes</i> + in a file-system-like name space. +</p> + +<h2><a name="driveroperations">2.11.1 Driver Operations</a></h2> +<ul><pre> + #include <fcntl.h> + int open(const char *path, int oflag, ...); +</pre></ul> + +<ul><pre> + #include <unistd.h> + int close(int fd); + int dup(int fildes); + int dup2(int fildes1, int fildes2); + off_t lseek(int fd, off_t offset, int whence); + int read(int fd, void *buf, unsigned int nbytes); + int unlink(const char *path); + int write(int fd, const void *buf, unsigned int nbytes); +</pre></ul> + +<ul><pre> + #include <sys/ioctl.h> + int ioctl(int fd, int req, unsigned long arg); +</pre></ul> + +<h2><a name="directoryoperations">2.11.2 Directory Operations</a></h2> +<ul><pre> + #include <dirent.h> + int closedir(DIR *dirp); + FAR DIR *opendir(const char *path); + FAR struct dirent *readdir(FAR DIR *dirp); + int readdir_r(FAR DIR *dirp, FAR struct dirent *entry, FAR struct dirent **result); + void rewinddir(FAR DIR *dirp); + void seekdir(FAR DIR *dirp, int loc); + int telldir(FAR DIR *dirp); +</pre></ul> + +<h2><a name="standardio">2.11.3 Standard I/O</a></h2> +<ul><pre> + #include <stdio.h> + int fclose(FILE *stream); + int fflush(FILE *stream); + int feof(FILE *stream); /* Prototyped but not implemented */ + int ferror(FILE *stream); /* Prototyped but not implemented */ + int fgetc(FILE *stream); + char *fgets(char *s, int n, FILE *stream); + FILE *fopen(const char *path, const char *type); + int fprintf(FILE *stream, const char *format, ...); + int fputc(int c, FILE *stream); + int fputs(const char *s, FILE *stream); + size_t fread(void *ptr, size_t size, size_t n_items, FILE *stream); + int fseek(FILE *stream, long int offset, int whence); /* Prototyped but not implemented */ + size_t fwrite(const void *ptr, size_t size, size_t n_items, FILE *stream); + char *gets(char *s); + + int printf(const char *format, ...); + int puts(const char *s); + int rename(const char *source, const char *target); + int sprintf(char *dest, const char *format, ...); + int ungetc(int c, FILE *stream); + int vprintf(const char *s, va_list ap); + int vfprintf(FILE *stream, const char *s, va_list ap); + int vsprintf(char *buf, const char *s, va_list ap); + + int chdir(const char *path); /* Prototyped but not implemented */ + FILE *fdopen(int fd, const char *type); + int fstat(int fd, FAR struct stat *buf); /* Prototyped but not implemented */ + char *getcwd(FAR char *buf, size_t size); /* Prototyped but not implemented */ + int mkdir(const char *path, mode_t mode); + int rmdir(const char *path); + int stat(const char *path, FAR struct stat *buf); + int statfs(const char *path, FAR struct statfs *buf); /* Prototyped but not implemented */ +</pre></ul> + <hr> <h1>3.0 <A NAME="Data_Structures">OS Data Structures</a></h1> <H2>3.1 Scalar types</H2> @@ -5704,87 +5969,6 @@ notify a task when a message is available on a queue. have to do some redesign. </p> -<h1><a name="FileSystem">2.10 Filesystem Interfaces</a></h1> -<p> - The NuttX filesystem is very simple; it does not involve any block drivers or - particular filesystem (like FAT or EXT2 etc.). - The NuttX filesystem simply supports a set a filesystem APIs - (<code>open()</code>, <code>close()</code>, <code>read()</code>, <code>write</code>, etc.) - and a registration mechanism that allows devices drivers to a associated with <i>nodes</i> - in a file-system-like name space. -</p> - -<h2><a name="driveroperations">2.10.1 Driver Operations</a></h2> -<ul><pre> - #include <fcntl.h> - int open(const char *path, int oflag, ...); -</pre></ul> - -<ul><pre> - #include <unistd.h> - int close(int fd); - int dup(int fildes); - int dup2(int fildes1, int fildes2); - off_t lseek(int fd, off_t offset, int whence); - int read(int fd, void *buf, unsigned int nbytes); - int unlink(const char *path); - int write(int fd, const void *buf, unsigned int nbytes); -</pre></ul> - -<ul><pre> - #include <sys/ioctl.h> - int ioctl(int fd, int req, unsigned long arg); -</pre></ul> - -<h2><a name="directoryoperations">2.10.2 Directory Operations</a></h2> -<ul><pre> - #include <dirent.h> - int closedir(DIR *dirp); - FAR DIR *opendir(const char *path); - FAR struct dirent *readdir(FAR DIR *dirp); - int readdir_r(FAR DIR *dirp, FAR struct dirent *entry, FAR struct dirent **result); - void rewinddir(FAR DIR *dirp); - void seekdir(FAR DIR *dirp, int loc); - int telldir(FAR DIR *dirp); -</pre></ul> - -<h2><a name="standardio">2.10.3 Standard I/O</a></h2> -<ul><pre> - #include <stdio.h> - int fclose(FILE *stream); - int fflush(FILE *stream); - int feof(FILE *stream); /* Prototyped but not implemented */ - int ferror(FILE *stream); /* Prototyped but not implemented */ - int fgetc(FILE *stream); - char *fgets(char *s, int n, FILE *stream); - FILE *fopen(const char *path, const char *type); - int fprintf(FILE *stream, const char *format, ...); - int fputc(int c, FILE *stream); - int fputs(const char *s, FILE *stream); - size_t fread(void *ptr, size_t size, size_t n_items, FILE *stream); - int fseek(FILE *stream, long int offset, int whence); /* Prototyped but not implemented */ - size_t fwrite(const void *ptr, size_t size, size_t n_items, FILE *stream); - char *gets(char *s); - - int printf(const char *format, ...); - int puts(const char *s); - int rename(const char *source, const char *target); - int sprintf(char *dest, const char *format, ...); - int ungetc(int c, FILE *stream); - int vprintf(const char *s, va_list ap); - int vfprintf(FILE *stream, const char *s, va_list ap); - int vsprintf(char *buf, const char *s, va_list ap); - - int chdir(const char *path); /* Prototyped but not implemented */ - FILE *fdopen(int fd, const char *type); - int fstat(int fd, FAR struct stat *buf); /* Prototyped but not implemented */ - char *getcwd(FAR char *buf, size_t size); /* Prototyped but not implemented */ - int mkdir(const char *path, mode_t mode); - int rmdir(const char *path); - int stat(const char *path, FAR struct stat *buf); - int statfs(const char *path, FAR struct statfs *buf); /* Prototyped but not implemented */ -</pre></ul> - <h1><a name="index">Index</a></h1> <ul> <li><a href="#clockgetres">clock_getres</a></li> |