NuttxUserGuide.html

  <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>

<h3><a name="setenv">2.10.4 <code>setenv</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;stdlib.h&gt;
  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>

<h3><a name="unsetenv">2.10.5 <code>unsetenv</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;stdlib.h&gt;
  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>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="FileSystem"><h2>2.11 File System Interfaces</h2></a>
  </td>
  </tr>
</table>

<ul>
  <li><a href="#FileSystemOverview">2.11.1 NuttX File System Overview</a></li>
  <li><a href="#driveroperations">2.11.2 Driver Operations</a></li>
  <li><a href="#directoryoperations">2.11.3 Directory Operations</a></li>
  <li><a href="#dirunistdops">2.11.4 UNIX Standard Operations</a></li>
  <li><a href="#standardio">2.11.5 Standard I/O</a></li>
  <li><a href="#stdstrings">2.11.6 Standard String Operations</a></li>
  <li><a href="#PipesNFifos">2.11.7 Pipes and FIFOs</a></li>
  <li><a href="#fatsupport">2.11.8 FAT File System Support</a></li>
  <li><a href="#mmapxip">2.11.9 <code>mmap()</code> and eXecute In Place (XIP)</a></li>
</ul>

<h3><a name="FileSystemOverview">2.11.1 NuttX File System Overview</a></h3>

<p><b>Overview</b>.
  NuttX includes an optional, scalable file system.
  This file-system may be omitted altogether; NuttX does not depend on the presence
  of any file system.
</p>

<p><b>Pseudo Root File System</b>.
  Or, a simple <i>in-memory</i>, <i>pseudo</i> file system can be enabled.
  This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS
  option to a non-zero value.
  This is an <i>in-memory</i> file system because it does not require any
  storage medium or block driver support.
  Rather, file system contents are generated on-the-fly as referenced via
  standard file system operations (open, close, read, write, etc.).
  In this sense, the file system is <i>pseudo</i> file system (in the
  same sense that the Linux <code>/proc</code> file system is also
  referred to as a pseudo file system).
</p>

<p>
  Any user supplied data or logic can be accessed via the pseudo-file system.
  Built in support is provided for character and block 
  <a href="NuttxPortingGuide.html#DeviceDrivers">driver</a> <i>nodes</i> in the any
  pseudo file system directory.
  (By convention, however, all driver nodes should be in the <code>/dev</code>
  pseudo file system directory).
</p>

<p><b>Mounted File Systems</b>
  The simple in-memory file system can be extended my mounting block
  devices that provide access to true file systems backed up via some
  mass storage device.
  NuttX supports the standard <code>mount()</code> command that allows
  a block driver to be bound to a mount-point within the pseudo file system
  and to a a file system.
  At present, NuttX supports only the VFAT file system.
</p>

<p><b>Comparison to Linux</b>
  From a programming perspective, the NuttX file system appears very similar
  to a Linux file system.
  However, there is a fundamental difference:
  The NuttX root file system is a pseudo file system and true file systems may be
  mounted in the pseudo file system.
  In the typical Linux installation by comparison, the Linux root file system
  is a true file system and pseudo file systems may be mounted in the true,
  root file system.
  The approach selected by NuttX is intended to support greater scalability
  from the very tiny platform to the moderate platform.
</p>

<p><b>File System Interfaces</b>.
  The NuttX file system simply supports a set of standard, file system 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>

<h3><a name="driveroperations">2.11.2 Driver Operations</a></h3>
<ul>
  <li><a href="#drvrfcntlops">2.11.2.1 <code>fcntl.h</code></a></li>
  <li><a href="#drvrunistdops">2.11.2.2 <code>unistd.h</code></a></li>
  <li><a href="#drvrioctlops">2.11.2.3 <code>sys/ioctl.h</code></a></li>
  <li><a href="#drvrpollops">2.11.2.4 <code>poll.h</code></a></li>
  <li><a href="#drvselectops">2.11.2.5 <code>sys/select.h</code></a></li>
</ul>

<h4><a name="drvrfcntlops">2.11.2.1 fcntl.h</a></h4>

<ul><pre>
  #include &lt;fcntl.h&gt;
  int open(const char *path, int oflag, ...);
</pre></ul>

<h4><a name="drvrunistdops">2.11.2.2 unistd.h</a></h4>

<ul><pre>
  #include &lt;unistd.h&gt;
  int     close(int fd);
  int     dup(int fildes);
  int     dup2(int fildes1, int fildes2);
  off_t   lseek(int fd, off_t offset, int whence);
  ssize_t read(int fd, void *buf, size_t nbytes);
  int     unlink(const char *path);
  ssize_t write(int fd, const void *buf, size_t nbytes);
</pre></ul>

<h4><a name="drvrioctlops">2.11.2.3 sys/ioctl.h</a></h4>

<ul><pre>
  #include &lt;sys/ioctl.h&gt;
  int     ioctl(int fd, int req, unsigned long arg);
</pre></ul>

<h4><a name="drvrpollops">2.11.2.4 poll.h</a></h4>

<h5><a name="poll">2.11.2.4.1 poll</a></H5>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;poll.h&gt;
  int     poll(struct pollfd *fds, nfds_t nfds, int timeout);
</pre>
<p>
  <b>Description:</b>
   <code>poll()</code> waits for one of a set of file descriptors to become ready to
   perform I/O.  If none of the events requested (and no error) has
   occurred for any of  the  file  descriptors,  then  <code>poll()</code> blocks until
   one of the events occurs.
</p>
<p>
  <b>Configuration Settings</b>.
  In order to use the <code>poll()</code> API, the following must be defined
  in your NuttX configuration file:
</p>
<ul>
  <li><code>CONFIG_NFILE_DESCRIPTORS</code> Defined to be greater than 0</li>
  <li><code>CONFIG_DISABLE_POLL</code> NOT defined</li>
</ul>
<p>
  In order to use the select with TCP/IP sockets test, you must also have the following additional things
  selected in your NuttX configuration file:
</p>
<ul>
  <li><code>CONFIG_NET</code> Defined for general network support</li>
  <li><code>CONFIG_NET_TCP</code> Defined for TCP/IP support</li>
  <li><code>CONFIG_NSOCKET_DESCRIPTORS</code> Defined to be greater than 0</li>
  <li><code>CONFIG_NET_NTCP_READAHEAD_BUFFERS</code> Defined to be greater than zero</li>
</ul>
<p>
  In order to for select to work with incoming connections, you must also select:
</p>
<ul>
  <li><code>CONFIG_NET_TCPBACKLOG</code>
  Incoming connections pend in a backlog until <code>accept()</cod> is called.
  The size of the backlog is selected when <code>listen()</code> is called.</li>
</ul>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>fds</code>. List of structures describing file descriptors to be monitored.</li>
  <li><code>nfds</code>. The number of entries in the list.</li>
  <li><code>timeout</code>. Specifies an upper limit on the time for which <code>poll()</code> will
    block in milliseconds.  A negative value of <code>timeout</code> means an infinite
    timeout.</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  On success, the number of structures that have nonzero <code>revents</code> fields.
  A value of 0 indicates that the call timed out and no file descriptors were ready.
  On error, -1 is returned, and <code>errno</code> is set appropriately:
</p>
<ul>
  <li><code>EBADF</code>. An invalid file descriptor was given in one of the sets.</li>
  <li><code>EFAULT</code>. The fds address is invalid</li>
  <li><code>EINTR</code>. A signal occurred before any requested event.</li>
  <li><code>EINVAL</code>. The nfds value exceeds a system limit.</li>
  <li><code>ENOMEM</code>. There was no space to allocate internal data structures.</li>
  <li><code>ENOSYS</code>. One or more of the drivers supporting the file descriptor does not support the poll method.</li>
</ul>

<h4><a name="drvselectops">2.11.2.5 sys/select.h</a></h4>

<h5><a name="select">2.11.2.5.1 select</a></H5>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/select.h&gt;
  int     select(int nfds, FAR fd_set *readfds, FAR fd_set *writefds,
                 FAR fd_set *exceptfds, FAR struct timeval *timeout);
</pre>
<p>
  <b>Description:</b>
  <code>select()</code> allows a program to monitor multiple file descriptors, waiting
  until one or more of the file descriptors become &quot;ready&quot; for some class
  of I/O operation (e.g., input possible).  A file descriptor is
  considered  ready if it is possible to perform the corresponding I/O
  operation (e.g., read(2)) without blocking.
</p>
<p>
  <b>NOTE:</b> <a href="#poll"><code>poll()</code></a> is the fundamental API for performing such monitoring
  operation under NuttX.  <code>select()</code> is provided for compatibility and
  is simply a layer of added logic on top of <code>poll()</code>.  As such, <code>select()</code>
  is more wasteful of resources and <a href="#poll"><code>poll()</code></a> is the recommended API to be
  used.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>nfds</code>. the maximum file descriptor number (+1) of any descriptor in any of the three sets.</li>
  <li><code>readfds</code>. the set of descriptions to monitor for read-ready events</li>
  <li><code>writefds</code>. the set of descriptions to monitor for write-ready events</li>
  <li><code>exceptfds</code>. the set of descriptions to monitor for error events</li>
  <li><code>timeout</code>. Return at this time if none of these events of interest occur.</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<ul>
  <li><code>0:</code> Timer expired</li>
  <li><code>&gt;0:</code> The number of bits set in the three sets of descriptors</li>
  <li><code>-1:</code> An error occurred (<code>errno</code> will be set appropriately,
    see <a href="#poll"><code>poll()</code></a>).</li>
</ul>

<h3><a name="directoryoperations">2.11.3 Directory Operations</a></h3>
<a name="dirdirentops">
<ul><pre>
#include &lt;dirent.h&gt;

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>
</a>

<h3><a name="dirunistdops">2.11.4 UNIX Standard Operations</a></h3>
<ul><pre>
#include &lt;unistd.h&gt;

pid_t   getpid(void);
void    _exit(int status) noreturn_function;
unsigned int sleep(unsigned int seconds);
void    usleep(unsigned long usec);

int     close(int fd);
int     dup(int fd);
int     dup2(int fd1, int fd2);
int     fsync(int fd);
off_t   lseek(int fd, off_t offset, int whence);
ssize_t read(int fd, FAR void *buf, size_t nbytes);
ssize_t write(int fd, FAR const void *buf, size_t nbytes);

int     pipe(int filedes[2]);

int     chdir(FAR const char *path);
FAR char *getcwd(FAR char *buf, size_t size);

int     unlink(FAR const char *pathname);
int     rmdir(FAR const char *pathname);
int     getopt(int argc, FAR char *const argv[], FAR const char *optstring);
</pre></ul>
</a>

<h3><a name="standardio">2.11.5 Standard I/O</a></h3>
<ul><pre>
#include &lt;stdio.h&gt;

int    fclose(FILE *stream);
int    fflush(FILE *stream);
FILE  *fdopen(int fd, const char *type);
int    feof(FILE *stream);                               /* Prototyped but not implemented */
int    ferror(FILE *stream);                             /* Prototyped but not implemented */
int    fileno(FAR FILE *stream);
int    fgetc(FILE *stream);
int    fgetpos(FILE *stream, fpos_t *pos);
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);
int    fsetpos(FILE *stream, fpos_t *pos);
long   ftell(FILE *stream);
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    snprintf(FAR char *buf, size_t size, const char *format, ...);
int    sprintf(char *dest, const char *format, ...);
int    sscanf(const char *buf, const char *fmt, ...);
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    vsnprintf(FAR char *buf, size_t size, const char *format, va_list ap);
int    vsscanf(char *buf, const char *s, va_list ap);
int    vsprintf(char *buf, const char *s, va_list ap);

#include &lt;sys/stat.h&gt;

int mkdir(FAR const char *pathname, mode_t mode);
int mkfifo(FAR const char *pathname, mode_t mode);
int stat(const char *path, FAR struct stat *buf);
int fstat(int fd, FAR struct stat *buf);

#include &lt;sys/statfs.h&gt;

int statfs(const char *path, struct statfs *buf);
int fstatfs(int fd, struct statfs *buf);
</pre></ul>

<h3><a name="stdstrings">2.11.6 Standard String Operations</a></h3>
<ul><pre>
#include &lt;string.h&gt;

char  *strchr(const char *s, int c);
FAR char *strdup(const char *s);
const char *strerror(int);
size_t strlen(const char *);
size_t strnlen(const char *, size_t);
char  *strcat(char *, const char *);
char  *strncat(char *, const char *, size_t);
int    strcmp(const char *, const char *);
int    strncmp(const char *, const char *, size_t);
int    strcasecmp(const char *, const char *);
int    strncasecmp(const char *, const char *, size_t);
char  *strcpy(char *dest, const char *src);
char  *strncpy(char *, const char *, size_t);
char  *strpbrk(const char *, const char *);
char  *strchr(const char *, int);
char  *strrchr(const char *, int);
size_t strspn(const char *, const char *);
size_t strcspn(const char *, const char *);
char  *strstr(const char *, const char *);
char  *strtok(char *, const char *);
char  *strtok_r(char *, const char *, char **);

void  *memset(void *s, int c, size_t n);
void  *memcpy(void *dest, const void *src, size_t n);
int    memcmp(const void *s1, const void *s2, size_t n);
void  *memmove(void *dest, const void *src, size_t count);

# define bzero(s,n) (void)memset(s,0,n)
</pre></ul>

<h3><a name="PipesNFifos">2.11.7 Pipes and FIFOs</a></h3>

<h3>2.11.7.1 <a name="pipe"><code>pipe</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;unistd.h&gt;
  int pipe(int filedes[2]);
</pre>
<p>
  <b>Description:</b>
  <ul>
    <p>
      <code>pipe()</code> creates a pair of file descriptors, pointing to a pipe inode, and
      places them in the array pointed to by <code>filedes</code>.
      <code>filedes[0]</code> is for reading, <code>filedes[1]</code> is for writing.
    </p>
  </ul>
</p>
<p>
  <b>Input Parameters:</b>
  <ul>
    <li><code>filedes[2]</code>.  The user provided array in which to catch the pipe file descriptors.</li>
  </ul>
</p>
</p>
<p>
  <b>Returned Values:</b>
  <ul>
    <p>
      0 is returned on success; otherwise, -1 is returned with <code>errno</code> set appropriately.
    </p>
  </ul>
</p>

<h3>2.11.7.2 <a name="mkfifo"><code>mkfifo</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/stat.h&gt;
  int mkfifo(FAR const char *pathname, mode_t mode);
</pre>
<p>
  <b>Description:</b>
  <ul>
    <p>
      <code>mkfifo()</code> makes a FIFO device driver file with name <code>pathname</code>.
      Unlike Linux, a NuttX FIFO is not a special file type but simply a device driver instance.
      <code>mode</code> specifies the FIFO's permissions (but is ignored in the current implementation). 
    </p>
    <p>
      Once the FIFO has been created by <code>mkfifo()</code>, any thread can open it for
      reading or writing, in the same way as an ordinary file.
      However, it must have been opened from both reading and writing before input or output can be performed.
      This FIFO implementation will block all attempts to open a FIFO read-only until at least one thread has opened the FIFO for  writing.
    </p>
    <p>
      If all threads that write to the FIFO have closed, subsequent calls to <code>read()</code> on the FIFO will return 0 (end-of-file).
    </p>
  </ul>
</p>
<p>
  <b>Input Parameters:</b>
  <ul>
    <li><code>pathname</code>.
      The full path to the FIFO instance to attach to or to create (if not already created).
    </li>
    <li><code>mode<code>.
      Ignored for now
    </li>
  </ul>
</p>
<p>
  <b>Returned Values:</b>
  <ul>
    <p>
      0 is returned on success; otherwise, -1 is returned with <code>errno</code> set appropriately.
    </p>
  </ul>
</p>

<h3><a name="fatsupport">2.11.8 FAT File System Support</a></h3>
<h3>2.11.8.1 <a name="mkfatfs"><code>mkfatfs</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<ul><pre>
#include &lt;nuttx/mkfatfs.h&gt;
int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
</pre></ul>
<p>
  <b>Description:</b>
  <ul>
    <p>
      The <code>mkfats()</code> formats a FAT file system image on the block
      device specified by <code>pathname</code>
    </p>
    <p>Assumptions: The caller must assure that the block driver is not mounted and not in
      use when this function is called. 
      The result of formatting a mounted device is indeterminate (but likely not good).
    </p>
  </ul>
</p>
<p>
  <b>Input Parameters:</b>
  <ul>
    <li>
      <code>pathname</code>
      The full path to the registered block driver in the file system.
    </li>
    <li>
      <code>fmt</code>
      A reference to an instance of a structure that provides caller-selectable
      attributes of the created FAT file system.
      <ul>
<pre>
struct fat_format_s
{
   uint8_t  ff_nfats;           /* Number of FATs */
   uint8_t  ff_fattype;         /* FAT size: 0 (autoselect), 12, 16, or 32 */
   uint8_t  ff_clustshift;      /* Log2 of sectors per cluster: 0-5, 0xff (autoselect) */
   uint8_t  ff_volumelabel[11]; /* Volume label */
   uint16_t ff_backupboot;      /* Sector number of the backup boot sector (0=use default)*/
   uint16_t ff_rootdirentries;  /* Number of root directory entries */
   uint16_t ff_rsvdseccount;    /* Reserved sectors */
   uint32_t ff_hidsec;          /* Count of hidden sectors preceding fat */
   uint32_t ff_volumeid;        /* FAT volume id */
   uint32_t ff_nsectors;        /* Number of sectors from device to use: 0: Use all */
};
</pre>
      </ul></li>
    </li>
  </ul>
</p>
<p>
  <b>Returned Values:</b>
  <ul>
    <p>
      Zero (<code>OK</code>) on success;
      -1 (<code>ERROR</code>) on failure with <code>errno</code> set appropriately:
      <ul>
        <li><code>EINVAL</code> -
          NULL block driver string, bad number of FATS in <code>fmt</code>,
          bad FAT size in <code>fmt</code>, bad cluster size in <code>fmt</code>
        </li>
        <li><code>ENOENT</code> - 
          <code>pathname</code> does not refer to anything in the file-system.
        </li>
        <li><code>ENOTBLK</code> -
          <code>pathname</code> does not refer to a block driver
        </li>
        <li><code>EACCESS</code> -
          block driver does not support write or geometry methods
        </li>
      </ul>
    </p>
  </ul>
</p>

<h3><a name="mmapxip">2.11.9 <code>mmap()</code> and eXecute In Place (XIP)</a></h3>
<p>
  NuttX operates in a flat open address space.
  Therefore, it generally does not require <code>mmap()</code> functionality.
  There is one one exception:
  <code>mmap()</code> is the API that is used to support direct access to random
  access media under the following very restrictive conditions:
  <ol>
    <li>
      The file-system supports the <code>FIOC_MMAP</code> ioctl command.
      Any file system that maps files contiguously on the media should support this
      <code>ioctl</code> command.
      By comparison, most file system scatter files over the media in non-contiguous
      sectors.  As of this writing, ROMFS is the only file system that meets this requirement.
    </li>
    <li>
      The underlying block driver supports the <code>BIOC_XIPBASE</code> <code>ioctl</code> command
      that maps the underlying media to a randomly accessible address.
       At present, only the RAM/ROM disk driver does this.
    </li>
  </ol>
</p>

<h3><a name="mmap">2.11.9.1 <code>mmap</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<ul><pre>
#include &lt;sys/mman.h&gt;
int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
FAR void *mmap(FAR void *start, size_t length, int prot, int flags, int fd, off_t offset)
</pre></ul>
<p>
  <b>Description:</b>
  <ul>
    Provides minimal <code>mmap()</code> as needed to support eXecute In Place (XIP)
    operation (as described above).
  </ul>
</p>
<p>
  <b>Input Parameters:</b>
  <ul>
    <li>
      <code>start</code>
        A hint at where to map the memory -- ignored.
        The address of the underlying media is fixed and cannot be re-mapped without MMU support.
    </li>
    <li>
      <code>length</code>
        The length of the mapping -- ignored.
        The entire underlying media is always accessible.
    </li>
    <li>
      <code>prot</code>
       See the <code>PROT_*</code> definitions in <code>sys/mman.h</code>.
       <ul>
         <li>
           <code>PROT_NONE</code> - Will cause an error.
         </li>
         <li>
           <code>PROT_READ</code> - <code>PROT_WRITE</code> and <code>PROT_EXEC</code> also assumed.
         </li>
         <li>
           <code>PROT_WRITE</code> - <code>PROT_READ</code> and <code>PROT_EXEC</code> also assumed.
         </li>
         <li>
           <code>PROT_EXEC</code> - <code>PROT_READ</code> and <code>PROT_WRITE</code> also assumed.
         </li>
       </ul>
    </li>
    <li>
      <code>flags</code>
      See the <code>MAP_*</code> definitions in <code>sys/mman.h</code>.
       <ul>
         <li>
           <code>MAP_SHARED</code> - Required
         </li>
         <li>
           <code>MAP_PRIVATE</code> - Will cause an error
         </li>
         <li>
           <code>MAP_FIXED</code> - Will cause an error
         </li>
         <li>
           <code>MAP_FILE</code> - Ignored
         </li>
         <li>
           <code>MAP_ANONYMOUS</code> - Will cause an error
         </li>
         <li>
           <code>MAP_ANON</code> - Will cause an error
         </li>
         <li>
           <code>MAP_GROWSDOWN</code> - Ignored
         </li>
         <li>
           <code>MAP_DENYWRITE</code> - Will cause an error
         </li>
         <li>
           <code>MAP_EXECUTABLE</code> - Ignored
         </li>
         <li>
           <code>MAP_LOCKED</code> - Ignored
         </li>
         <li>
           <code>MAP_NORESERVE</code> - Ignored
         </li>
         <li>
           <code>MAP_POPULATE</code> - Ignored
         </li>
         <li>
           <code>AP_NONBLOCK</code> - Ignored
         </li>
       </ul>
    </li>
    <li>
      <code>fd</code>
      file descriptor of the backing file -- required.
    </li>
    <li>
      <code>offset</code>
      The offset into the file to map.
    </li>
  </ul>
</p>
<p>
  <b>Returned Values:</b>
  <ul>
    <p>
      On success, <code>mmap()</code> returns a pointer to the mapped area.
      On error, the value <code>MAP_FAILED</code> is returned, and <code>errno</code> is set appropriately.
      <ul>
        <li><code>ENOSYS</code> -
          Returned if any of the unsupported <code>mmap()</code> features are attempted.
        </li>
        <li><code>EBADF</code> - 
          <code>fd</code> is not a valid file descriptor.
        </li>
        <li><code>EINVAL</code> -
          Length is 0. flags contained neither <code>MAP_PRIVATE</code> or <code>MAP_SHARED</code>, or
          contained both of these values.
        </li>
        <li><code>ENODEV</code> -
          The underlying file-system of the specified file does not support memory mapping.
        </li>
      </ul>
    </p>
  </ul>
</p>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="Network"><h2>2.12 Network Interfaces</h2></a>
  </td>
  </tr>
</table>

<p>NuttX includes a simple interface layer based on uIP (see <a href="http://www.sics.se/~adam/uip/index.php/Main_Page">http://www.sics.se</a>).
NuttX supports subset of a standard socket interface to uIP.
These network feature can be enabled by settings in the architecture
<a href="NuttxPortingGuide.html#apndxconfigs">configuration file</a>.
Those socket APIs are discussed in the following paragraphs.</p>
<ul>
<li>
</li>
<li><a href="#socket">2.12.1 socket</a></li>
<li><a href="#bind">2.12.2 bind</a></li>
<li><a href="#connect">2.12.3 connect</a></li>
<li><a href="#listen">2.12.4 listen</a></li>
<li><a href="#accept">2.12.5 accept</a></li>
<li><a href="#send">2.12.6 send</a></li>
<li><a href="#sendto">2.12.7 sendto</a></li>
<li><a href="#recv">2.12.8 recv</a></li>
<li><a href="#recvfrom">2.12.9 recvfrom</a></li>
<li><a href="#setsockopt">2.12.10 setsockopt</a></li>
<li><a href="#getsockopt">2.12.11 getsockopt</a></li>
</ul>

<h3><a name="socket">2.12.1 <code>socket</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  int socket(int domain, int type, int protocol);
</pre>
<p>
  <b>Description:</b>
   socket() creates an endpoint for communication and returns a descriptor.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<p>
<ul>
  <li><code>domain</code>: (see sys/socket.h)</li>
  <li><code>type</code>: (see sys/socket.h)</li>
  <li><code>protocol</code>: (see sys/socket.h)</li>
</ul>
<p>
  <b>Returned Values:</b>
  0 on success; -1 on error with <a href="#ErrnoAccess"><code>errno</code></a> set appropriately:
</p>
<ul>
  <li><code>EACCES</code>.
    Permission to create a socket of the specified type and/or protocol is denied.</li>
  <li><code>EAFNOSUPPORT</code>.
    The implementation does not support the specified address family.</li>
  <li><code>EINVAL</code>.
    Unknown protocol, or protocol family not available.</li>
  <li><code>EMFILE</code>.
    Process file table overflow.</li>
  <li><code>ENFILE</code>
    The system limit on the total number of open files has been reached.</li>
  <li><code>ENOBUFS</code> or <code>ENOMEM</code>.
    Insufficient memory is available. The socket cannot be created until sufficient resources are freed.</li>
  <li><code>EPROTONOSUPPORT</code>.
    The protocol type or the specified protocol is not supported within this domain.</li>
</ul>

<h3><a name="bind">2.12.2 <code>bind</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  int bind(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
</pre>
<p>
  <b>Description:</b>
   <code>bind()</code> gives the socket sockfd the local address <code>addr</code>.
   <code>addr</code> is <code>addrlen</code> bytes long. Traditionally, this is called
   &quot;assigning a name to a socket.&quot; When a socket is created with <code>socket()</code>,
   it exists in a name space (address family) but has no name assigned.
<p>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<p>
<ul>
  <li><code>sockfd</code>: Socket descriptor from socket.</li>
  <li><code>addr</code>: Socket local address.</li>
  <li><code>addrlen</code>: Length of <code>addr</code>.</li>
</ul>
<p>
  <b>Returned Values:</b>
  0 on success; -1 on error with <a href="#ErrnoAccess"><code>errno</code></a> set appropriately:
</p>
<ul>
  <li><code>EACCES</code>
    The address is protected, and the user is not the superuser.</li>
  <li><code>EADDRINUSE</code>
    The given address is already in use.</li>
  <li><code>EBADF</code>
    <code>sockfd</code> is not a valid descriptor.</li>
  <li><code>EINVAL</code>
    The socket is already bound to an address.</li>
  <li><code>ENOTSOCK</code>
    <code>sockfd</code> is a descriptor for a file, not a socket.</li>
</ul>

<h3><a name="connect">2.12.3 <code>connect</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  int connect(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
</pre>
<p>
  <b>Description:</b>
  <code>connect()</code> connects the socket referred to by the file descriptor
  <code>sockfd</code> to the address specified by <code>addr</code>.
  The <code>addrlen</code> argument specifies the size of <code>addr</code>.
  The format of the address in <code>addr</code> is determined by the address space
  of the socket sockfd.

  If the socket sockfd is of type SOCK_DGRAM then <code>addr</code> is the address
  to which datagrams are sent by default, and the only address from which
  datagrams are received. If the socket is of type SOCK_STREAM or
  SOCK_SEQPACKET, this call attempts to make a connection to the socket
  that is bound to the address specified by <code>addr</code>.

  Generally, connection-based protocol sockets may successfully <code>connect()</code>
  only once; connectionless protocol sockets may use <code>connect()</code> multiple
  times to change their association.  Connectionless sockets may dissolve
  the association by connecting to an address with the sa_family member of
  sockaddr set to AF_UNSPEC.
<p>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<p>
<ul>
  <li><code>sockfd</code>: Socket descriptor returned by <code>socket()</code></li>
  <li><code>addr</code>: Server address (form depends on type of socket)</li>
  <li><code>addrlen</code>: Length of actual <code>addr</code></li>
</ul>
<p>
  <b>Returned Values:</b>
  0 on success; -1 on error with <a href="#ErrnoAccess"><code>errno</code></a> set appropriately:
</p>
  <li><code>EACCES</code> or </code>EPERM</code>:
    The user tried to connect to a broadcast address without having the
    socket broadcast flag enabled or the connection request failed
    because of a local firewall rule.</li>
  <li><code>EADDRINUSE</code>
    Local address is already in use.</li>
  <li><code>EAFNOSUPPORT</code>
    The passed address didn't have the correct address family in its
    sa_family field.</li>
  <li><code>EAGAIN</code>
    No more free local ports or insufficient entries in the routing
    cache. For PF_INET.</li>
  <li><code>EALREADY</code>
    The socket is non-blocking and a previous connection attempt has
    not yet been completed.</li>
  <li><code>EBADF</code>
    The file descriptor is not a valid index in the descriptor table.</li>
  <li><code>ECONNREFUSED</code>
    No one listening on the remote address.</li>
  <li><code>EFAULT</code>
    The socket structure address is outside the user's address space.</li>
  <li><code>EINPROGRESS</code>
    The socket is non-blocking and the connection cannot be completed
    immediately.</li>
  <li><code>EINTR</code>
    The system call was interrupted by a signal that was caught.</li>
  <li><code>EISCONN</code>
    The socket is already connected.</li>
  <li><code>ENETUNREACH</code>
    Network is unreachable.</li>
  <li><code>ENOTSOCK</code>
    The file descriptor is not associated with a socket.</li>
  <li><code>ETIMEDOUT</code>
    Timeout while attempting connection. The server may be too busy
    to accept new connections.</li>
</ul>

<h3><a name="listen">2.12.4 listen</a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  int listen(int sockfd, int backlog);
</pre>
<p>
  <b>Description:</b>
  To accept connections, a socket is first created with <code>socket()</code>, a
  willingness to accept incoming connections and a queue limit for incoming
  connections are specified with <code>listen()</code>, and then the connections are
  accepted with <code>accept()</code>. The <code>listen()</coe> call applies only to sockets of
  type <code>SOCK_STREAM</code> or <code>SOCK_SEQPACKET</code>.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>sockfd</code>: Socket descriptor of the bound socket.</li>
  <li><code>backlog</code>: The maximum length the queue of pending connections may grow.
    If a connection request arrives with the queue full, the client may receive an error
    with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission,
    the request may be ignored so that retries succeed.</li>
</ul>
<p>
  <b>Returned Values:</b>
  On success, zero is returned. On error, -1 is returned, and
  <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately.
</p>
<ul>
  <li><code>EADDRINUSE</code>: Another socket is already listening on the same port.</li>
  <li><code>EBADF</code>: The argument <code>sockfd</code> is not a valid descriptor.</li>
  <li><code>ENOTSOCK</code>: The argument <code>sockfd</code> is not a socket.</li>
  <li><code>EOPNOTSUPP</code>: The socket is not of a type that supports the listen operation.</li>
 </ul>
 
<h3><a name="accept">2.12.5 accept</a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);
</pre>
<p>
  <b>Description:</b>
  The <code>accept()</code> function is used with connection-based socket types
 (<code>SOCK_STREAM</code>, <code>SOCK_SEQPACKET</code> and <code>SOCK_RDM</code>).
  It extracts the first connection request on the queue of pending connections,
  creates a new connected socket with most of the same properties as <code>sockfd</code>,
  and allocates a new socket descriptor for the socket, which is returned. The
  newly created socket is no longer in the listening state. The original
  socket <code>sockfd</code> is unaffected by this call.  Per file descriptor flags
  are not inherited across an accept.
</p>
<p>
  The <code>sockfd</code> argument is a socket descriptor that has been created with