NuttxUserGuide.html

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="Data_Structures"><h1>3.0 OS Data Structures</h1></a>
  </td>
  </tr>
</table>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="ScalarType"><h2>3.1 Scalar Types</h2></a>
  </td>
  </tr>
</table>

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="HiddenStructures"><h2>3.2 Hidden Interface Structures</h2></a>
  </td>
  </tr>
</table>

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="ErrnoAccess"><h2>3.3 Access to the <code>errno</code> Variable</h2></a>
  </td>
  </tr>
</table>

<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 &lt;errno.h&gt;
    #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>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="UserStructures"><h2>3.4 User Interface Structures</h2></a>
  </td>
  </tr>
</table>

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="index"><h1>Index</h1></a>
  </td>
  </tr>
</table>

<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="#mmapxip">BIOC_XIPBASE</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>
  <li><a href="#Data_Structures">Data structures</a></li>
  <li><a href="#directoryoperations">Directory operations</a></li>
  <li><a href="#driveroperations">Driver operations</a></li>
  <li><a href="#drvrunistdops">dup</a></li>
  <li><a href="#drvrunistdops">dup2</a></li>
  <li><a href="#mmapxip">eXecute In Place (XIP)</a></li>
  <li><a href="#exit">exit</a></li>
  <li><a href="#fatsupport">FAT File System Support</a></li>
  <li><a href="#standardio">fclose</a></li>
  <li><a href="#standardio">fdopen</a></li>
  <li><a href="#standardio">feof</a></li>
  <li><a href="#standardio">ferror</a></li>
  <li><a href="#FileSystem">File system, interfaces</a></li>
  <li><a href="#FileSystemOverview">File system, overview</a></li>
  <li><a href="#standardio">fflush</a></li>
  <li><a href="#standardio">fgetc</a></li>
  <li><a href="#standardio">fgetpos</a></li>
  <li><a href="#standardio">fgets</a></li>
  <li><a href="#mmapxip">FIOC_MMAP</a></li>
  <li><a href="#standardio">fopen</a></li>
  <li><a href="#standardio">fprintf</a></li>
  <li><a href="#standardio">fputc</a></li>
  <li><a href="#standardio">fputs</a></li>
  <li><a href="#standardio">fread</a></li>
  <li><a href="#standardio">fseek</a></li>
  <li><a href="#standardio">fsetpos</a></li>
  <li><a href="#standardio">fstat(</a></li>
  <li><a href="#standardio">ftell</a></li>
  <li><a href="#standardio">fwrite</a></li>
  <li><a href="#dirunistdops">getcwd</a></li>
  <li><a href="#getpid">getpid</a></li>
  <li><a href="#standardio">gets</a></li>
  <li><a href="#getsockopt">getsockopt</a></li>
  <li><a href="#gmtimer">gmtime_r</a></li>
  <li><a href="#Introduction">Introduction</a>
  <li><a href="#drvrioctlops">ioctl</a></li>
  <li><a href="#kill">kill</a></li>
  <li><a href="#listen">listen</a></li>
  <li><a href="#localtimer">localtime_r</a></li>
  <li><a href="#drvrunistdops">lseek</a></li>
  <li><a href="#Message_Queue">Named Message Queue Interfaces</a>
  <li><a href="#standardio">mkdir</a></li>
  <li><a href="#mkfatfs">mkfatfs</a></li>
  <li><a href="#mkfifo">mkfifo</a></li>
  <li><a href="#mktime">mktime</a></li>
  <li><a href="#mqclose">mq_close</a></li>
  <li><a href="#mqgetattr">mq_getattr</a></li>
  <li><a href="#mqnotify">mq_notify</a></li>
  <li><a href="#mqopen">mq_open</a></li>
  <li><a href="#mqreceive">mq_receive</a></li>
  <li><a href="#mqsend">mq_send</a></li>
  <li><a href="#mqsetattr">mq_setattr</a></li>
  <li><a href="#mqtimedreceive">mq_timedreceive</a></li>
  <li><a href="#mqtimedsend">mq_timedsend</a></li>
  <li><a href="#mqunlink">mq_unlink</a></li>
  <li><a href="#mmap">mmap</a></li>
  <li><a href="#Network">Network Interfaces</a></li>
  <li><a href="#drvrfcntlops">open</a></li>
  <li><a href="#dirdirentops">opendir</a></li>
  <li><a href="#OS_Interfaces">OS Interfaces</a></li>
</td>
<td valign="top" width="33%">
  <li><a href="#pipe">pipe</a></li>
  <li><a href="#standardio">printf</a></li>
  <li><a href="#Pthread">Pthread Interfaces</a>
  <li><a href="#pthreadattrdestroy">pthread_attr_destroy</a></li>
  <li><a href="#pthreadattrgetinheritsched">pthread_attr_getinheritsched</a></li>
  <li><a href="#pthreadattrgetschedparam">pthread_attr_getschedparam</a></li>
  <li><a href="#pthreadattrgetschedpolicy">pthread_attr_getschedpolicy</a></li>
  <li><a href="#pthreadattrgetstacksize">pthread_attr_getstacksize</a></li>
  <li><a href="#pthreadattrinit">pthread_attr_init</a></li>
  <li><a href="#pthreadattrsetinheritsched">pthread_attr_setinheritsched</a></li>
  <li><a href="#pthreadattrsetschedparam">pthread_attr_setschedparam</a></li>
  <li><a href="#pthreadattrsetschedpolity">pthread_attr_setschedpolicy</a></li>
  <li><a href="#pthreadattrsetstacksize">pthread_attr_setstacksize</a></li>
  <li><a href="#pthreadbarrierattrinit">pthread_barrierattr_init</a></li>
  <li><a href="#pthreadbarrierattrdestroy">pthread_barrierattr_destroy</a></li>
  <li><a href="#pthreadbarrierattrgetpshared">pthread_barrierattr_getpshared</a></li>
  <li><a href="#pthreadbarrierattrsetpshared">pthread_barrierattr_setpshared</a></li>
  <li><a href="#pthreadbarrierdestroy">pthread_barrier_destroy</a></li>
  <li><a href="#pthreadbarrierinit">pthread_barrier_init</a></li>
  <li><a href="#pthreadbarrierwait">pthread_barrier_wait</a></li>
  <li><a href="#pthreadcancel">pthread_cancel</a></li>
  <li><a href="#pthreadconaddrinit">pthread_condattr_init</a></li>
  <li><a href="#pthreadcondbroadcast">pthread_cond_broadcast</a></li>
  <li><a href="#pthreadconddestroy">pthread_cond_destroy</a></li>
  <li><a href="#pthreadcondinit">pthread_cond_init</a></li>
  <li><a href="#pthreadcondsignal">pthread_cond_signal</a></li>
  <li><a href="#pthreadcondtimedwait">pthread_cond_timedwait</a></li>
  <li><a href="#pthreadcondwait">pthread_cond_wait</a></li>
  <li><a href="#pthreadcreate">pthread_create</a></li>
  <li><a href="#pthreaddetach">pthread_detach</a></li>
  <li><a href="#pthreadexit">pthread_exit</a></li>
  <li><a href="#pthreadgetschedparam">pthread_getschedparam</a></li>
  <li><a href="#pthreadgetspecific">pthread_getspecific</a></li>
  <li><a href="#Pthread"><i>pthreads</i></a> share some resources.
  <li><a href="#pthreadjoin">pthread_join</a></li>
  <li><a href="#pthreadkeycreate">pthread_key_create</a></li>
  <li><a href="#pthreadkeydelete">pthread_key_delete</a></li>
  <li><a href="#pthreadkill">pthread_kill</a></li>
  <li><a href="#pthreadmutexattrdestroy">pthread_mutexattr_destroy</a></li>
  <li><a href="#pthreadmutexattrgetpshared">pthread_mutexattr_getpshared</a></li>
  <li><a href="#pthreadmutexattrgettype">pthread_mutexattr_gettype</a></li>
  <li><a href="#pthreadmutexattrinit">pthread_mutexattr_init</a></li>
  <li><a href="#pthreadmutexattrsetpshared">pthread_mutexattr_setpshared</a></li>
  <li><a href="#pthreadmutexattrsettype">pthread_mutexattr_settype</a></li>
  <li><a href="#pthreadmutexdestrory">pthread_mutex_destroy</a></li>
  <li><a href="#pthreadmutexinit">pthread_mutex_init</a></li>
  <li><a href="#pthreadmutexlock">pthread_mutex_lock</a></li>
  <li><a href="#pthreadmutextrylock">pthread_mutex_trylock</a></li>
  <li><a href="#pthreadmutexunlock">pthread_mutex_unlock</a></li>
  <li><a href="#pthreadocndattrdestroy">pthread_condattr_destroy</a></li>
  <li><a href="#pthreadonce">pthread_once</a></li>
  <li><a href="#pthreadself">pthread_self</a></li>
  <li><a href="#pthreadsetcancelstate">pthread_setcancelstate</a></li>
  <li><a href="#pthreadsetschedparam">pthread_setschedparam</a></li>
  <li><a href="#pthreadsetspecific">pthread_setspecific</a></li>
  <li><a href="#pthreadsigmask">pthread_sigmask</a></li>
  <li><a href="#pthreadtestcancelstate">pthread_testcancelstate</a></li>
  <li><a href="#pthreadyield">pthread_yield</a></li>
  <li><a href="#standardio">puts</a></li>
  <li><a href="#mmapxip">RAM disk driver</a></li>
  <li><a href="#drvrunistdops">read</a></li>
  <li><a href="#dirdirentops">readdir</a></li>
  <li><a href="#dirdirentops">readdir_r</a></li>
  <li><a href="#recv">recv</a></li>
  <li><a href="#recvfrom">recvfrom</a></li>
  <li><a href="#standardio">rename</a></li>
  <li><a href="#standardio">rmdir</a></li>
  <li><a href="#dirdirentops">rewinddir</a></li>
  <li><a href="#mmapxip">ROM disk driver</a></li>
  <li><a href="#mmapxip">ROMFS</a></li>
  <li><a href="#schedgetparam">sched_getparam</a></li>
</td>
<td valign="top">
  <li><a href="#schedgetprioritymax">sched_get_priority_max</a></li>
  <li><a href="#schedgetprioritymin">sched_get_priority_min</a></li>
  <li><a href="#schedgetrrinterval">sched_get_rr_interval</a></li>
  <li><a href="#schedlockcount">sched_lockcount</a></li>
  <li><a href="#schedlock">sched_lock</a></li>
  <li><a href="#schedsetparam">sched_setparam</a></li>
  <li><a href="#schedsetscheduler">sched_setscheduler</a></li>
  <li><a href="#schedunlock">sched_unlock</a></li>
  <li><a href="#sched_yield">sched_yield</a></li>
  <li><a href="#Semaphores">Counting Semaphore Interfaces</a>
  <li><a href="#semclose">sem_close</a></li>
  <li><a href="#semdestroy">sem_destroy</a></li>
  <li><a href="#semgetvalue">sem_getvalue</a></li>
  <li><a href="#seminit">sem_init</a></li>
  <li><a href="#semopen">sem_open</a></li>
  <li><a href="#sempost">sem_post</a></li>
  <li><a href="#semtrywait">sem_trywait</a></li>
  <li><a href="#semunlink">sem_unlink</a></li>
  <li><a href="#semwait">sem_wait</a></li>
  <li><a href="#setgetscheduler">sched_getscheduler</a></li>
  <li><a href="#dirdirentops">seekdir</a></li>
  <li><a href="#send">send</a></li>
  <li><a href="#sendto">sendto</a></li>
  <li><a href="#setsockopt">setsockopt</a></li>
  <li><a href="#sigaction">sigaction</a></li>
  <li><a href="#sigaddset">sigaddset</a></li>
  <li><a href="#sigdelset">sigdelset</a></li>
  <li><a href="#sigemptyset">sigemptyset</a></li>
  <li><a href="#sigfillset">sigfillset</a></li>
  <li><a href="#sigismember">sigismember</a></li>
  <li><a href="#Signals">Signal Interfaces</a>
  <li><a href="#sigpending">sigpending</a></li>
  <li><a href="#sigprocmask">sigprocmask</a></li>
  <li><a href="#sigqueue">sigqueue</a></li>
  <li><a href="#sigsuspend">sigsuspend</a></li>
  <li><a href="#sigtimedwait">sigtimedwait</a></li>
  <li><a href="#sigwaitinfo">sigwaitinfo</a></li>
  <li><a href="#socket">socket</a></li>
  <li><a href="#standardio">sprintf</a></li>
  <li><a href="#standardio">Standard I/O</a></li>
  <li><a href="#standardio">stat</a></li>
  <li><a href="#standardio">statfs</a></li>
  <li><a href="#taskactivate">task_activate</a></li>
  <li><a href="#Task_Control">Task Control Interfaces</a>
  <li><a href="#taskcreate">task_create</a></li>
  <li><a href="#taskdelete">task_delete</a></li>
  <li><a href="#taskinit">task_init</a></li>
  <li><a href="#taskrestart">task_restart</a></li>
  <li><a href="#Task_Schedule">Task Scheduling Interfaces</a>
  <li><a href="#Task_Switch">Task Switching Interfaces</a>
  <li><a href="#dirdirentops">telldir</a></li>
  <li><a href="#timercreate">timer_create</a></li>
  <li><a href="#timerdelete">timer_delete</a></li>
  <li><a href="#timergetoverrun">timer_getoverrun</a></li>
  <li><a href="#timergettime">timer_gettime</a></li>
  <li><a href="#ClocksNTimers">Timers</a></li>
  <li><a href="#timersettime">timer_settime</a></li>
  <li><a href="#standardio">ungetc</a></li>
  <li><a href="#drvrunistdops">unlink</a></li>
  <li><a href="#standardio">vfprintf</a></li>
  <li><a href="#standardio">vprintf</a></li>
  <li><a href="#standardio">vsprintf</a></li>
  <li><a href="#Watchdogs">Watchdog Timer Interfaces</a>
  <li><a href="#wdcancel">wd_cancel</a></li>
  <li><a href="#wdcreate">wd_create</a></li>
  <li><a href="#wddelete">wd_delete</a></li>
  <li><a href="#wdgettime">wd_gettime</a></li>
  <li><a href="#wdstart">wd_start</a></li>
  <li><a href="#drvrunistdops">write</a></li>
  <li><a href="#mmapxip">XIP</a></li>
</td>
</tr>
</table>

</BODY>
</HTML>