NuttxUserGuide.html

  <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="#standardio">2.11.4 Standard I/O</a></li>
  <li><a href="#PipesNFifos">2.11.5 Pipes and FIFOs</a></li>
  <li><a href="#fatsupport">2.11.6 FAT File System Support</a></li>
  <li><a href="#mmapxip">2.11.7 <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 altogther; 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>psuedo</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>psuedo</i> file system (in the
  same sense that the Linux <code>/proc</code> file system is also
  referred to as a psuedo file system).
</p>

<p>
  Any user supplied data or logic can be accessed via the psuedo-file system.
  Built in support is provided for character and block drivers in the
  <code>/dev</code> psuedo 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 mountpoint within the psuedo 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 psuedo file system and true file systems may be
  mounted in the psuedo file system.
  In the typical Linux installation by comparison, the Linux root file system
  is a true file system and psuedo 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 <cod>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>

<a name="dirunistdops">
<ul><pre>
  #include &lt;unistd.h&gt;
  int       chdir(FAR const char *path);
  FAR char *getcwd(FAR char *buf, size_t size);
</pre></ul>
</a>

<h3><a name="standardio">2.11.4 Standard I/O</a></h3>
<ul><pre>
  #include &lt;stdio.h&gt;
  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);
  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    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);

  FILE  *fdopen(int fd, const char *type);
  int    fstat(int fd, FAR struct stat *buf);              /* 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>

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

<h3>2.11.5.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.5.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.6 FAT File System Support</a></h3>
<h3>2.11.6.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
{
   ubyte   ff_nfats;           /* Number of FATs */
   ubyte   ff_fattype;         /* FAT size: 0 (autoselect), 12, 16, or 32 */
   ubyte   ff_clustshift;      /* Log2 of sectors per cluster: 0-5, 0xff (autoselect) */
   ubyte   ff_volumelabel[11]; /* Volume label */
   uint16  ff_backupboot;      /* Sector number of the backup boot sector (0=use default)*/
   uint16  ff_rootdirentries;  /* Number of root directory entries */
   uint16  ff_rsvdseccount;    /* Reserved sectors */
   uint32  ff_hidsec;          /* Count of hidden sectors preceding fat */
   uint32  ff_volumeid;        /* FAT volume id */
   uint32  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 filesystem.
        </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.7 <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 filesystem 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 underly 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.7.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 filesystem 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
  <code>socket()</code>, bound to a local address with <code>bind()</code>, and is listening for
  connections after a call to <code>listen()</code>.
</p>
<p>
  On return, the <code>addr</code> structure is filled in with the address of the
  connecting entity. The <code>addrlen</code> argument initially contains the size
  of the structure pointed to by <code>addr</code>; on return it will contain the
  actual length of the address returned.
</p>
<p>
  If no pending connections are present on the queue, and the socket is
  not marked as non-blocking, accept blocks the caller until a connection
  is present. If the socket is marked non-blocking and no pending
  connections are present on the queue, accept returns <code>EAGAIN</code>.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>sockfd</code>: Socket descriptor of the listening socket.</li>
  <li><code>addr</code>: Receives the address of the connecting client.</li>
  <li><code>addrlen</code>: Input: allocated size of <code>addr</code>, Return: returned size of <code>addr</code>.</li>
</ul>
<p>
  <b>Returned Values:</b>
  Returns -1 on error. If it succeeds, it returns a non-negative integer
  that is a descriptor for the accepted socket.
</p>
<ul>
  <li><code>EAGAIN</code> or <code>EWOULDBLOCK</code>:
    The socket is marked non-blocking and no connections are present to be accepted.</li>
  <li><code>EBADF</code>:
    The descriptor is invalid.</li>
  <li><code>ENOTSOCK</code>:
    The descriptor references a file, not a socket.</li>
  <li><code>EOPNOTSUPP</code>:
    The referenced socket is not of type <code>SOCK_STREAM</code>.</li>
  <li><code>EINTR</code>:
    The system call was interrupted by a signal that was caught before a valid connection arrived.</li>
  <li><code>ECONNABORTED</code>:
    A connection has been aborted.</li>
  <li><code>EINVAL</code>:
    Socket is not listening for connections.</li>
  <li><code>EMFILE</code>:
    The per-process limit of open file descriptors has been reached.</li>
  <li><code>ENFILE</code>:
    The system maximum for file descriptors has been reached.</li>
  <li><code>EFAULT</code>:
    The addr parameter is not in a writable part of the user address space.</li>
  <li><code>ENOBUFS</code> or <code>ENOMEM</code>:
    Not enough free memory.</li>
  <li><code>EPROTO</code>:
    Protocol error.</li>
  <li><code>EPERM</code>:
    Firewall rules forbid connection.</li>
</ul>

<h3><a name="send">2.12.6 <code>send</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  ssize_t send(int sockfd, const void *buf, size_t len, int flags);
</pre>
<p>
  <b>Description:</b>
  The <code>send()</code> call may be used only when the socket is in a connected state
  (so that the intended recipient is known).
  The only difference between <code>send()</code> and <code>write()</code> is the
  presence of <code>flags</code>.
  With <code>zero</code> flags parameter, <code>send()</code> is equivalent to
  <code>write()</code>. Also, <code>send(s,buf,len,flags)</code> is
  equivalent to <code>sendto(s,buf,len,flags,NULL,0)</code>.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>sockfd</code>: Socket descriptor of socket
  <li><code>buf</code>: Data to send
  <li><code>len</code>: Length of data to send
  <li><code>flags</code>: Send flags
</ul>
<p>
  <b>Returned Values:</b>
  See <a href="#sendto"><code>sendto()</code></a>.
</p>

<h3><a name="sendto">2.12.7 <code>sendto</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include &lt;sys/socket.h&gt;
  ssize_t sendto(int sockfd, const void *buf, size_t len, int flags,
                 const struct sockaddr *to, socklen_t tolen);
</pre>
<p>
  <b>Description:</b>
  If <code>sendto()</code> is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET)
  socket, the parameters to and tolen are ignored (and the error EISCONN
  may be returned when they are not NULL and 0), and the error ENOTCONN is
  returned when the socket was not actually connected.
<p>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>sockfd</code>: Socket descriptor of socket
  <li><code>buf</code>: Data to send
  <li><code>len</code>: Length of data to send
  <li><code>flags</code>: Send flags
  <li><code>to</code>: Address of recipient
  <li><code>tolen</code>: The length of the address structure
</ul>
<p>
  <b>Returned Values:</b>
  On success, returns the number of characters sent.  On  error, -1 is returned,
  and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
</p>
<ul>
  <li><code>EAGAIN</code> or <code>EWOULDBLOCK</code>.
    The socket is marked non-blocking and the requested operation would block.
  <li><code>EBADF</code>.
    An invalid descriptor was specified.
  <li><code>ECONNRESET</code>.
    Connection reset by peer.
  <li><code>EDESTADDRREQ</code>.
    The socket is not connection-mode, and no peer address is set.
  <li><code>EFAULT</code>.
    An invalid user space address was specified for a parameter.
  <li><code>EINTR</code>.
    A signal occurred before any data was transmitted.
  <li><code>EINVAL</code>.
    Invalid argument passed.
  <li><code>EISCONN</code>.
    The connection-mode socket was connected already but a recipient
    was specified. (Now either this error is returned, or the recipient
    specification is ignored.)
  <li><code>EMSGSIZE</code>.
    The socket type requires that message be sent atomically, and the
    size of the message to be sent made this impossible.
  <li><code>ENOBUFS</code>.
    The output queue for a network interface was full. This generally
    indicates that the interface has stopped sending, but may be
    caused by transient congestion.
  <li><code>ENOMEM</code>.
    No memory available.
  <li><code>ENOTCONN</code>.
    The socket is not connected, and no target has been given.