NuttxUserGuide.html

<h3>2.11.5.1 <a name="pipe"><code>pipe</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include <unistd.h>
  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 <sys/stat.h>
  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>

<h2><a name="fatsupport">2.11.6 FAT File System Support</a></h2>
<h3>2.11.5.1 <a name="mkfatfs"><code>mkfatfs</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<ul><pre>
#include <nutts/mkfatfs.h>
int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
</pre></ul>
<p>
  <b>Description:</b>
  <ul>
    <p>
      The <code>mkfafs()</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>

<h2>2.12 <a name="Network">Network Interfaces</a></h2>
<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 <sys/socket.h>
  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 <sys/socket.h>
  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 <sys/socket.h>
  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 <sys/socket.h>
  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 <sys/socket.h>
  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 <sys/socket.h>
  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 <sys/socket.h>
  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.
  <li><code>ENOTSOCK</code>.
    The argument s is not a socket.
  <li><code>EOPNOTSUPP</code>.
    Some bit in the flags argument is inappropriate for the socket type.
  <li><code>EPIPE</code>.
    The local end has been shut down on a connection oriented socket.
    In this case the process will also receive a SIGPIPE unless
    MSG_NOSIGNAL is set.
</ul>

<h3><a name="recv">2.12.8 <code>recv</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include <sys/socket.h>
  ssize_t recv(int sockfd, void *buf, size_t len, int flags);
</pre>
<p>
  <b>Description:</b>
  The <code>recv()</code> call is identical to
  <a href="#recvfrom"><code>recvfrom()</code></a> with a NULL
  <code>from</code> parameter.
<p>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  </li>
  <li>sockfd</code>: Socket descriptor of socket </li>
  <li>buf</code>: Buffer to receive data </li>
  <li>len</code>: Length of buffer </li>
  <li>flags</code>: Receive flags </li>
</ul>
<p>
  <b>Returned Values:</b>
  see <a href="#recvfrom"><code>recvfrom()</code></a>.
  Zero on success.
</p>

<h3><a name="recvfrom">2.12.9 <code>recvfrom</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include <sys/socket.h>
  ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
                   struct sockaddr *from, socklen_t *fromlen);
</pre>
<p>
  <b>Description:</b>
  <code>recvfrom()</code> receives messages from a socket, and may be used to receive
  data on a socket whether or not it is connection-oriented.
</p>
<p>
  If <code>from</code> is not NULL, and the underlying protocol provides the source
  address, this source address is filled in. The argument <code>fromlen</code>
  initialized to the size of the buffer associated with <code>from</code>, and modified
  on return to indicate the actual size of the address stored there.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
    <li><code>sockfd</code>: Socket descriptor of socket.</li>
    <li><code>buf</code>:  Buffer to receive data.</li>
    <li><code>len</code>: Length of buffer.</li>
    <li><code>flags</code>: Receive flags.</li>
    <li><code>from</code>: Address of source.</li>
    <li><code>fromlen</code>: The length of the address structure.</li>
</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>.
      The socket is marked non-blocking and the receive operation would block,
      or a receive timeout had been set and the timeout expired before data
      was received.
    <li><code>EBADF</code>.
      The argument <code>sockfd</code> is an invalid descriptor.
    <li><code>ECONNREFUSED</code>.
      A remote host refused to allow the network connection (typically because
      it is not running the requested service).
    <li><code>EFAULT</code>.
      The receive buffer pointer(s) point outside the process's address space.
    <li><code>EINTR</code>.
      The receive was interrupted by delivery of a signal before any data were
      available.
    <li><code>EINVAL</code>.
      Invalid argument passed.
    <li><code>ENOMEM</code>.
      Could not allocate memory.
    <li><code>ENOTCONN</code>.
      The socket is associated with a connection-oriented protocol and has
      not been connected.
    <li><code>ENOTSOCK</code>.
      The argument <code>sockfd</code> does not refer to a socket.
</ul>

<h3><a name="setsockopt">2.12.10 <code>setsockopt</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include <sys/socket.h>
  int setsockopt(int sockfd, int level, int option,
                 const void *value, socklen_t value_len);
</pre>
<p>
  <b>Description:</b>
  <code>setsockopt()</code> sets the option specified by the <code>option</code> argument,
  at the protocol level specified by the <code>level</code> argument, to the value
  pointed to by the <code>value</code> argument for the socket associated with the
  file descriptor specified by the <code>sockfd</code> argument.
</p>
<p>
  The <code>level</code> argument specifies the protocol level of the option. To set
  options at the socket level, specify the level argument as SOL_SOCKET.
</p>
<p>
  See <sys/socket.h> a complete list of values for the <code>option</code> argument.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>sockfd</code>: Socket descriptor of socket
  <li><code>level</code>: Protocol level to set the option
  <li><code>option</code>: identifies the option to set
  <li><code>value</code>: Points to the argument value
  <li><code>value_len</code>: The length of the argument value
</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>BADF</code>.
     The <code>sockfd</code> argument is not a valid socket descriptor.
  <li><code>DOM</code>.
     The send and receive timeout values are too big to fit into the
     timeout fields in the socket structure.
  <li><code>INVAL</code>.
     The specified option is invalid at the specified socket <code>level</code> or the
     socket has been shut down.
  <li><code>ISCONN</code>.
     The socket is already connected, and a specified option cannot be set
     while the socket is connected.
  <li><code>NOPROTOOPT</code>.
     The <code>option</code> is not supported by the protocol.
  <li><code>NOTSOCK</code>.
     The <code>sockfd</code> argument does not refer to a socket.
  <li><code>NOMEM</code>.
     There was insufficient memory available for the operation to complete.
  <li><code>NOBUFS</code>.
     Insufficient resources are available in the system to complete the call.
</ul>

<h3><a name="getsockopt">2.12.11 <code>getsockopt</code></a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
  #include <sys/socket.h>
  int getsockopt(int sockfd, int level, int option,
                 void *value, socklen_t *value_len);
</pre>
<p>
  <b>Description:</b>
  <code>getsockopt()</code> retrieve thse value for the option specified by the
  <code>option</code> argument for the socket specified by the <code>sockfd</code> argument. If
  the size of the option value is greater than <code>value_len</code>, the value
  stored in the object pointed to by the <code>value</code> argument will be silently
  truncated. Otherwise, the length pointed to by the <code>value_len</code> argument
  will be modified to indicate the actual length of the<code>value</code>.
</p>
<p>
  The <code>level</code> argument specifies the protocol level of the option. To
  retrieve options at the socket level, specify the level argument as
  SOL_SOCKET.
</p>
<p>
  See <sys/socket.h> a complete list of values for the <code>option</code> argument.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>sockfd    Socket descriptor of socket
  <li><code>level     Protocol level to set the option
  <li><code>option    identifies the option to get
  <li><code>value     Points to the argument value
  <li><code>value_len The length of the argument value
</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>BADF</code>.
    The <code>sockfd</code> argument is not a valid socket descriptor.</li>
  <li><code>INVAL</code>.
    The specified option is invalid at the specified socket <code>level</code> or the
    socket has been shutdown.</li>
  <li><code>NOPROTOOPT</code>.
    The <code>option</code> is not supported by the protocol.</li>
  <li><code>NOTSOCK</code>.
    The <code>sockfd</code> argument does not refer to a socket.</li>
  <li><code>NOBUFS
    Insufficient resources are available in the system to complete the call.</li>
</ul>

<hr>
<h1>3.0 <A NAME="Data_Structures">OS Data Structures</A></h1>
<H2>3.1 <A NAME="ScalarType">Scalar Types</A></H2>
<p>
Many of the types used to communicate with NuttX are simple
scalar types. These types are used to provide architecture independence
of the OS from the application. The scalar types used at the NuttX
interface include:
<ul>
<li>pid_t
<li>size_t
<li>sigset_t
<li>STATUS
<li>time_t
</ul>

<H2>3.2 <A NAME="HiddenStructures">Hidden Interface Structures</A></H2>
<p>
Several of the types used to interface with NuttX are
structures that are intended to be hidden from the application.
From the standpoint of the application, these structures (and
structure pointers) should be treated as simple handles to reference
OS resources. These hidden structures include:
<ul>
<li>_TCB
<li>mqd_t
<li>sem_t
<li>WDOG_ID
<li>pthread_key_t
</ul>
<p>
  In order to maintain portability, applications should not reference
  specific elements within these hidden structures. These hidden
  structures will not be described further in this user's manual.
</p>
<p>

<H2>3.3 <A NAME="ErrnoAccess">Access to the <code>errno</code> Variable</A></H2>
<p>
  A pointer to the thread-specific <code>errno</code> value is available through a
  function call:
</p>
<p>
  <b>Function Prototype:</b>
<p>
<pre>    #include <errno.h>
    #define errno *get_errno_ptr()
    int *get_errno_ptr( void )</pre>
<p>
  <b>Description</b>:
  <code>get_errno_ptr()</code> returns a pointer to the thread-specific <code>errno</code> value.
  Note that the symbol <code>errno</code> is defined to be <code>get_errno_ptr()</code> so that the usual
  access by referencing the symbol <code>errno</code> will work as expected.
</p>
<p>
  There is a unique, private <code>errno</code> value for each NuttX task.
  However, the implementation of <code>errno</code> differs somewhat from the use of
  <code>errno</code> in most multi-threaded process environments:
  In NuttX, each pthread will also have its own private copy of <code>errno</code> and the
  <code>errno</code> will not be shared between pthreads.
  This is, perhaps, non-standard but promotes better thread independence.
<p>
<b>Input Parameters</b>:  None
<p>
<b>Returned Values</b>:
<p>
<ul>
<li>A pointer to the thread-specific <code>errno</code> value.
</ul>
<p>

<H2>3.4 <A NAME="UserStructures">User Interface Structures</A></H2>
<p>
<H3>3.4.1 main_t</H3>
<p>
main_t defines the type of a task entry point. main_t is declared
in sys/types.h as:
<pre>
    typedef int (*main_t)(int argc, char *argv[]);
</pre>

<H3>3.4.2 struct sched_param</H3>

<p>
This structure is used to pass scheduling priorities to and from
NuttX;
<pre>
    struct sched_param
    {
      int sched_priority;
    };
</pre>

<H3>3.4.3 struct timespec</H3>

<p>
This structure is used to pass timing information between the
NuttX and a user application:
<pre>
    struct timespec
    {
      time_t tv_sec;  /* Seconds */
      long   tv_nsec; /* Nanoseconds */
    };
</pre>

<H3>3.4.4 struct mq_attr</H3>

<p>
This structure is used to communicate message queue attributes
between NuttX and a MoBY application:
<pre>
    struct mq_attr {
      size_t       mq_maxmsg;   /* Max number of messages in queue */
      size_t       mq_msgsize;  /* Max message size */
      unsigned     mq_flags;    /* Queue flags */
      size_t       mq_curmsgs;  /* Number of messages currently in queue */
    };
</pre>

<H3>3.4.5 struct sigaction</H3>

<p>
The following structure defines the action to take for given signal:
<pre>
    struct sigaction
    {
      union
      {
        void (*_sa_handler)(int);
        void (*_sa_sigaction)(int, siginfo_t *, void *);
      } sa_u;
      sigset_t           sa_mask;
      int                sa_flags;
    };
    #define sa_handler   sa_u._sa_handler
    #define sa_sigaction sa_u._sa_sigaction
</pre>

<H3>3.4.6 struct siginfo/siginfo_t</H3>

<p>
The following types is used to pass parameters to/from signal
handlers:
<pre>
    typedef struct siginfo
    {
      int          si_signo;
      int          si_code;
      union sigval si_value;
   } siginfo_t;
</pre>

<H3>3.4.7 union sigval</H3>

<p>
This defines the type of the struct siginfo si_value field and
is used to pass parameters with signals.
<pre>
    union sigval
    {
      int   sival_int;
      void *sival_ptr;
    };
</pre>

<H3>3.4.8 struct sigevent</H3>

<p>
The following is used to attach a signal to a message queue to
notify a task when a message is available on a queue.
<pre>
    struct sigevent
    {
      int          sigev_signo;
      union sigval sigev_value;
      int          sigev_notify;
    };
</pre>

<H3>3.4.9 Watchdog Data Types</H3>

<p>
  When a watchdog expires, the callback function with this
  type is called:
</p>
<pre>
    typedef void (*wdentry_t)(int argc, ...);
</pre>
<p>
  Where argc is the number of uint32 type arguments that follow.
</p>
  The arguments are passed as uint32 values.
  For systems where the sizeof(pointer) &lt; sizeof(uint32), the
  following union defines the alignment of the pointer within the
  uint32.  For example, the SDCC MCS51 general pointer is
  24-bits, but uint32 is 32-bits (of course).
</p>
<pre>
    union wdparm_u
    {
      void   *pvarg;
      uint32 *dwarg;
    };
    typedef union wdparm_u wdparm_t;
</pre>
<p>
  For most 32-bit systems, pointers and uint32 are the same size
  For systems where sizeof(pointer) > sizeof(uint32), we will
  have to do some redesign.
</p>

<h1><a name="index">Index</a></h1>
<table width="100%">
<tr>
<td valign="top" width="34%">
  <li><a href="#accept">accept</a></li>
  <li><a href="#bind">bind</a></li>
  <li><a href="#dirunistdops">chdir</a></li>
  <li><a href="#clockgetres">clock_getres</a></li>
  <li><a href="#clockgettime">clock_gettime</a></li>
  <li><a href="#ClocksNTimers">Clocks</a></li>
  <li><a href="#clocksettime">clock_settime</a></li>
  <li><a href="#drvrunistdops">close</a></li>
  <li><a href="#dirdirentops">closedir</a></li>
  <li><a href="#connect">connect</a></li>