packages/compat/posix/v2_0/doc/posix.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     posix.sgml                                                  -->
   6 <!--                                                                 -->
   7 <!--     POSIX Compatibility                                         -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <part id="posix-compatibility">
  33 <title>eCos POSIX compatibility layer</title>
  34
  35 <chapter id="posix-standard-support">
  36 <title>POSIX Standard Support</title>
  37
  38 <!-- {{{ Intro  -->
  39
  40     <para>
  41       eCos contains support for the POSIX Specification (ISO&sol;IEC
  42       9945-1)&lsqb;POSIX&rsqb;.
  43     </para>
  44     <para>
  45       POSIX support is divided between the POSIX and the FILEIO
  46       packages. The POSIX package provides support for threads,
  47       signals, synchronization, timers and message queues. The FILEIO
  48       package provides support for file and device I&sol;O. The two
  49       packages may be used together or separately, depending on
  50       configuration.
  51     </para>
  52     <para>
  53       This document takes a functional approach to the POSIX
  54       library. Support for a function implies that the data types and
  55       definitions necessary to support that function, and the objects
  56       it manipulates, are also defined. Any exceptions to this are
  57       noted, and unless otherwise noted, implemented functions behave
  58       as specified in the POSIX standard.
  59     </para>
  60     <para>
  61       This document only covers the differences between the eCos
  62       implementation and the standard; it does not provide complete
  63       documentation. For full information, see the POSIX standard
  64       &lsqb;POSIX&rsqb;. Online, the Open Group Single Unix
  65       Specification &lsqb;SUS2&rsqb; provides complete documentation
  66       of a superset of POSIX. If you have access to a Unix system with
  67       POSIX compatibility, then the manual pages for this will be of
  68       use.  There are also a number of books available.
  69       &lsqb;Lewine&rsqb; covers the process, signal, file and I&sol;O
  70       functions, while &lsqb;Lewis1&rsqb;, &lsqb;Lewis2&rsqb;,
  71       &lsqb;Nichols&rsqb; and &lsqb;Norton&rsqb; cover Pthreads and
  72       related topics (see Bibliography, xref). However, many of these
  73       books are oriented toward using POSIX in non-embedded systems,
  74       so care should be taken in applying them to programming under
  75       eCos.
  76     </para>
  77     <para>
  78       The remainder of this chapter broadly follows the structure
  79       of the POSIX Specification. References to the appropriate
  80       section of the Standard are included.
  81     </para>
  82     <para>
  83       Omitted functions marked with &ldquo;&sol;&sol; TBA&rdquo;
  84       are potential candidates for later implementation.
  85     </para>
  86
  87 <!-- }}} -->
  88 <!-- {{{ Process Primitives -->
  89
  90 <sect1 id="posix-process-primitives">
  91 <title>Process Primitives &lsqb;POSIX Section 3&rsqb;</title>
  92
  93 <!-- =================================================================== -->
  94
  95 <sect2>
  96 <title>Functions Implemented</title>
  97
  98 <screen>
  99 int kill(pid&lowbar;t pid, int sig);
 100 int pthread&lowbar;kill(pthread&lowbar;t thread, int sig);
 101 int sigaction(int sig, const struct sigaction &ast;act,
 102               struct sigaction &ast;oact);
 103 int sigqueue(pid&lowbar;t pid, int sig, const union sigval value);
 104 int sigprocmask(int how, const sigset&lowbar;t &ast;set,
 105                 sigset&lowbar;t &ast;oset);
 106 int pthread&lowbar;sigmask(int how, const sigset&lowbar;t &ast;set,
 107                     sigset&lowbar;t &ast;oset);
 108 int sigpending(sigset&lowbar;t &ast;set);
 109 int sigsuspend(const sigset&lowbar;t &ast;set);
 110 int sigwait(const sigset&lowbar;t &ast;set, int &ast;sig);
 111 int sigwaitinfo(const sigset&lowbar;t &ast;set, siginfo&lowbar;t &ast;info);
 112 int sigtimedwait(const sigset&lowbar;t &ast;set, siginfo&lowbar;t &ast;info,
 113                  const struct timespec &ast;timeout);
 114 int sigemptyset(sigset&lowbar;t &ast;set);
 115 int sigfillset(sigset&lowbar;t &ast;set);
 116 int sigaddset(sigset&lowbar;t &ast;set, int signo);
 117 int sigdelset(sigset&lowbar;t &ast;set, int signo);
 118 int sigismember(const sigset&lowbar;t &ast;set, int signo);
 119 unsigned int alarm( unsigned int seconds );
 120 int pause( void );
 121 unsigned int sleep( unsigned int seconds );
 122 </screen>
 123 </sect2>
 124
 125 <!-- =================================================================== -->
 126
 127 <sect2>
 128 <title>Functions Omitted</title>
 129
 130 <screen>
 131 pid&lowbar;t fork(void);
 132 int execl( const char &ast;path, const char &ast;arg, ... );
 133 int execv( const char &ast;path, char &ast;const argv&lsqb;&rsqb; );
 134 int execle( const char &ast;path, const char &ast;arg, ... );
 135 int execve( const char &ast;path, char &ast;const argv&lsqb;&rsqb;,
 136             char &ast;const envp&lsqb;&rsqb; );
 137 int execlp( const char &ast;path, const char &ast;arg, ... );
 138 int execvp( const char &ast;path, char &ast;const argv&lsqb;&rsqb; );
 139 int pthread&lowbar;atfork( void(&ast;prepare)(void),
 140                     void (&ast;parent)(void),
 141                     void (&ast;child)() );
 142 pid&lowbar;t wait( int &ast;stat&lowbar;loc );
 143 pid&lowbar;t waitpid( pid&lowbar;t pid, int &ast;stat&lowbar;loc,
 144                int options );
 145 void &lowbar;exit( int status );
 146 </screen>
 147 </sect2>
 148
 149 <!-- =================================================================== -->
 150
 151 <sect2>
 152 <title>Notes</title>
 153 <itemizedlist>
 154   <listitem>
 155     <para>
 156     Signal handling may be enabled or disabled with the
 157     CYGPKG&lowbar;POSIX&lowbar;SIGNALS option. Since signals are used
 158     by other POSIX components, such as timers, disabling signals will
 159     disable those components too.
 160     </para>
 161   </listitem>
 162
 163   <listitem>
 164     <para>
 165     <emphasis>kill()</emphasis> and
 166     <emphasis>sigqueue()</emphasis> may only take a
 167     <emphasis role="strong">pid</emphasis> argument of zero,
 168     which maps to the current process.
 169     </para>
 170   </listitem>
 171
 172   <listitem>
 173     <para>
 174     The <emphasis>SIGEV&lowbar;THREAD</emphasis> notification type is
 175             not currently implemented.
 176     </para>
 177   </listitem>
 178
 179   <listitem>
 180     <para>
 181     Job Control and Memory Protection signals are
 182             not supported.
 183     </para>
 184   </listitem>
 185
 186   <listitem>
 187     <para>
 188     An extra implementation defined
 189     <emphasis>si&lowbar;code</emphasis> value,
 190     <emphasis>SI&lowbar;EXCEPT</emphasis>, is defined to
 191     distinguish hardware generated exceptions from
 192     others.
 193     </para>
 194   </listitem>
 195
 196   <listitem>
 197     <para>
 198     Extra signals are defined:
 199     &lowbar;SIGTRAP&lowbar;,&lowbar;SIGIOT&lowbar;,
 200     &lowbar;SIGEMT&lowbar;, and &lowbar;SIGSYS&lowbar;. These are
 201     largely to maintain compatibility with the signal numbers used by
 202     GDB.
 203     </para>
 204   </listitem>
 205
 206   <listitem>
 207     <para>
 208     Signal delivery may currently occur at unexpected places in some
 209     API functions. Using <emphasis>longjmp()</emphasis> to transfer
 210     control out of a signal handler may result in the interrupted
 211     function not being able to complete properly. This may result in
 212     later function calls failing or deadlocking.
 213     </para>
 214   </listitem>
 215 </itemizedlist>
 216 </sect2>
 217
 218
 219 </sect1>
 220
 221 <!-- }}} -->
 222 <!-- {{{ Process Environment -->
 223
 224 <sect1 id="posix-process-environment">
 225 <title>Process Environment &lsqb;POSIX Section 4&rsqb;</title>
 226
 227 <!-- =================================================================== -->
 228
 229 <sect2>
 230 <title>Functions Implemented</title>
 231
 232 <screen>
 233 int uname( struct utsname &ast;name );
 234 time&lowbar;t time( time&lowbar;t &ast;tloc );
 235 char &ast;getenv( const char &ast;name );
 236 int isatty( int fd );
 237 long sysconf( int name );
 238 </screen>
 239 </sect2>
 240
 241 <!-- =================================================================== -->
 242
 243 <sect2>
 244 <title>Functions Omitted</title>
 245 <screen>
 246 pid&lowbar;t getpid( void );
 247 pid&lowbar;t getppid( void );
 248 uid&lowbar;t getuid( void );
 249 uid&lowbar;t geteuid( void );
 250 gid&lowbar;t getgid( void );
 251 gid&lowbar;t getegid( void );
 252 int setuid( uid&lowbar;t uid );
 253 int setgid( gid&lowbar;t gid );
 254 int getgroups( int gidsetsize, gid&lowbar;t grouplist&lsqb;&rsqb; );
 255 char &ast;getlogin( void );
 256 int getlogin&lowbar;r( char &ast;name, size&lowbar;t namesize );
 257 pid&lowbar;t getpgrp( void );
 258 pid&lowbar;t setsid( void );
 259 int setpgid( pid&lowbar;t pid, pid&lowbar;t pgid );
 260 char &ast;ctermid( char &ast;s);
 261 char &ast;ttyname( int fd );                             &sol;&sol; TBA
 262 int ttyname&lowbar;r( int fd, char &ast;name, size&lowbar;t namesize); &sol;&sol; TBA
 263 clock&lowbar;t times( struct tms &ast;buffer );                 &sol;&sol; TBA
 264 </screen>
 265 </sect2>
 266
 267 <!-- =================================================================== -->
 268
 269 <sect2>
 270 <title>Notes</title>
 271         <itemizedlist>
 272           <listitem>
 273             <para>The fields of the <emphasis>utsname</emphasis>
 274             structure are initialized as follows:
 275             <screen>
 276             sysname     &ldquo;eCos&rdquo;
 277             nodename    &ldquo;&rdquo;  (gethostname() is currently not available)
 278
 279             release             Major version number of the kernel
 280             version             Minor version number of the kernel
 281             machine     &ldquo;&rdquo;  (Requires some config tool changes)
 282             </screen>
 283             </para>
 284             <para>
 285             The sizes of these strings are defined by
 286             CYG&lowbar;POSIX&lowbar;UTSNAME&lowbar;LENGTH and
 287             CYG&lowbar;POSIX&lowbar;UTSNAME&lowbar;NODENAME&lowbar;LENGTH. The
 288             latter defaults to the value of the former, but may also
 289             be set independently to accommodate a longer node name.
 290             </para>
 291           </listitem>
 292
 293           <listitem>
 294             <para>
 295             The <emphasis>time()</emphasis> function is currently
 296             implemented in the C library.
 297             </para>
 298           </listitem>
 299
 300           <listitem>
 301             <para>A set of environment strings may be defined at configuration
 302             time with the CYGDAT&lowbar;LIBC&lowbar;DEFAULT&lowbar;ENVIRONMENT
 303             option. The application may also define an environment by direct
 304             assignment to the <emphasis role="strong">environ</emphasis>
 305             variable.
 306             </para>
 307           </listitem>
 308
 309           <listitem>
 310             <para>
 311             At present <emphasis>isatty()</emphasis> assumes that
 312             any character device is a tty and that all other devices are not
 313             ttys. Since the only kind of device that eCos currently supports
 314             is serial character devices, this is an adequate
 315             distinction.
 316             </para>
 317           </listitem>
 318
 319           <listitem>
 320             <para>
 321             All system variables supported by sysconf will yield a
 322             value. However, those that are irrelevant to eCos will
 323             either return the default minimum defined in
 324             <filename>&lt;limits.h&gt;</filename>,
 325             or zero.
 326             </para>
 327           </listitem>
 328         </itemizedlist>
 329
 330 </sect2>
 331 </sect1>
 332
 333 <!-- }}} -->
 334 <!-- {{{ Files and Directories -->
 335
 336 <sect1 id="posix-files-and-directories">
 337 <title>Files and Directories &lsqb;POSIX Section 5&rsqb;</title>
 338
 339 <!-- =================================================================== -->
 340
 341 <sect2>
 342 <title>Functions Implemented</title>
 343
 344 <screen>
 345 DIR &ast;opendir( const char &ast;dirname );
 346 struct dirent &ast;readdir( DIR &ast;dirp );
 347 int readdir&lowbar;r( DIR &ast;dirp, struct dirent &ast;entry,
 348                struct dirent &ast;&ast;result );
 349 void rewinddir( DIR &ast;dirp );
 350 int closedir( DIR &ast;dirp );
 351 int chdir( const char &ast;path );
 352 char &ast;getcwd( char &ast;buf, size&lowbar;t size );
 353 int open( const char &ast; path , int oflag , ... );
 354 int creat( const char &ast; path, mode&lowbar;t mode );
 355 int link( const char &ast;existing, const char &ast;new );
 356 int mkdir( const char &ast;path, mode&lowbar;t mode );
 357 int unlink( const char &ast;path );
 358 int rmdir( const char &ast;path );
 359 int rename( const char &ast;old, const char &ast;new );
 360 int stat( const char &ast;path, struct stat &ast;buf );
 361 int fstat( int fd, struct stat &ast;buf );
 362 int access( const char &ast;path, int amode );
 363 long pathconf(const char &ast;path, int name);
 364 long fpathconf(int fd, int name);
 365 </screen>
 366 </sect2>
 367
 368 <!-- =================================================================== -->
 369
 370 <sect2>
 371 <title>Functions Omitted</title>
 372
 373 <screen>
 374 mode&lowbar;t umask( mode&lowbar;t cmask );
 375 int mkfifo( const char &ast;path, mode&lowbar;t mode );
 376 int chmod( const char &ast;path, mode&lowbar;t mode );                  &sol;&sol; TBA
 377 int fchmod( int fd, mode&lowbar;t mode );                               &sol;&sol; TBA
 378 int chown( const char &ast;path, uid&lowbar;t owner, gid&lowbar;t group );
 379 int utime( const char &ast;path, const struct utimbuf &ast;times );     &sol;&sol; TBA
 380 int ftruncate( int fd, off&lowbar;t length );                          &sol;&sol; TBA
 381 </screen>
 382 </sect2>
 383
 384 <!-- =================================================================== -->
 385
 386 <sect2>
 387 <title>Notes</title>
 388
 389         <itemizedlist>
 390           <listitem>
 391             <para>
 392             If a call to <function>open()</function> or <function>creat()</function> supplies
 393             the third &lowbar;mode&lowbar; parameter, it will
 394             currently be ignored.
 395             </para>
 396           </listitem>
 397           <listitem>
 398             <para>
 399             Most of the functionality of these functions depends on
 400             the underlying filesystem.
 401             </para>
 402             </listitem>
 403           <listitem>
 404             <para>
 405             Currently<emphasis> access()</emphasis> only checks the
 406             <emphasis>F&lowbar;OK</emphasis> mode explicitly, the others are
 407             all assumed to be true by default.
 408             </para>
 409           </listitem>
 410           <listitem>
 411             <para>
 412             The maximum number of open files allowed is supplied by
 413             the CYGNUM&lowbar;FILEIO&lowbar;NFILE option. The maximum number
 414             of file descriptors is supplied by the CYGNUM&lowbar;FILEIO&lowbar;NFD
 415             option.
 416             </para>
 417           </listitem>
 418         </itemizedlist>
 419 </sect2>
 420 </sect1>
 421
 422 <!-- }}} -->
 423 <!-- {{{ Input and Output -->
 424
 425 <sect1 id="posix-input-and-output">
 426 <title>Input and Output &lsqb;POSIX Section 6&rsqb;</title>
 427
 428 <!-- =================================================================== -->
 429
 430 <sect2>
 431 <title>Functions Implemented</title>
 432
 433 <screen>
 434 int dup( int fd );
 435 int dup2( int fd, int fd2 );
 436 int close(int fd);
 437 ssize&lowbar;t  read(int fd, void &ast;buf, size&lowbar;t nbyte);
 438 ssize&lowbar;t  write(int fd, const void &ast;buf, size&lowbar;t nbyte);
 439 int fcntl( int fd, int cmd, ... );
 440 off&lowbar;t lseek(int fd, off&lowbar;t offset, int whence);
 441 int fsync( int fd );
 442 int fdatasync( int fd );</screen>
 443 </sect2>
 444
 445 <!-- =================================================================== -->
 446
 447 <sect2>
 448 <title>Functions Omitted</title>
 449 <screen>
 450 int pipe( int fildes&lsqb;2&rsqb; );
 451 int aio&lowbar;read( struct aiocb &ast;aiocbp );                                &sol;&sol; TBA
 452 int aio&lowbar;write( struct aiocb &ast;aiocbp );                               &sol;&sol; TBA
 453 int lio&lowbar;listio( int mode, struct aiocb &ast;const list&lsqb;&rsqb;,
 454                 int nent, struct sigevent &ast;sig);            &sol;&sol; TBA
 455 int aio&lowbar;error( struct aiocb &ast;aiocbp );                               &sol;&sol; TBA
 456 int aio&lowbar;return( struct aiocb &ast;aiocbp );                              &sol;&sol; TBA
 457 int aio&lowbar;cancel( int fd, struct aiocb &ast;aiocbp );                      &sol;&sol; TBA
 458 int aio&lowbar;suspend( const struct aiocb &ast;const list&lsqb;&rsqb;,
 459                  int nent, const struct timespec &ast;timeout );        &sol;&sol; TBA
 460 int aio&lowbar;fsync( int op, struct aiocb &ast;aiocbp );
 461 &sol;&sol; TBA
 462 </screen>
 463 </sect2>
 464
 465 <!-- =================================================================== -->
 466
 467 <sect2>
 468 <title>Notes</title>
 469         <itemizedlist>
 470           <listitem>
 471             <para>
 472             Only the <emphasis>F&lowbar;DUPFD</emphasis> command
 473             of <emphasis>fcntl()</emphasis> is currently implemented.
 474             </para>
 475           </listitem>
 476           <listitem>
 477             <para>
 478             Most of the functionality of these functions depends on
 479             the underlying filesystem.
 480             </para>
 481           </listitem>
 482         </itemizedlist>
 483 </sect2>
 484 </sect1>
 485
 486 <!-- }}} -->
 487 <!-- {{{ Device and Class Specific Functions -->
 488
 489 <sect1 id="posix-device-and-class-specific-functions">
 490 <title>Device and Class Specific Functions &lsqb;POSIX Section 7&rsqb;</title>
 491
 492 <!-- =================================================================== -->
 493
 494 <sect2>
 495 <title>Functions Implemented</title>
 496 <screen>
 497 speed&lowbar;t cfgetospeed( const struct termios &ast;termios&lowbar;p );
 498 int cfsetospeed( struct termios &ast;termios&lowbar;p, speed&lowbar;t speed );
 499 speed&lowbar;t cfgetispeed( const struct termios &ast;termios&lowbar;p );
 500 int cfsetispeed( struct termios &ast;termios&lowbar;p, speed&lowbar;t speed );
 501 int tcgetattr( int fd, struct termios &ast;termios&lowbar;p );
 502 int tcsetattr( int fd, int optional&lowbar;actions,
 503                const struct termios &ast;termios&lowbar;p );
 504 int tcsendbreak( int fd, int duration );
 505 int tcdrain( int fd );
 506 int tcflush( int fd, int queue&lowbar;selector );
 507 int tcsendbreak( int fd, int action );
 508 </screen>
 509 </sect2>
 510
 511 <!-- =================================================================== -->
 512
 513 <sect2>
 514 <title>Functions Omitted</title>
 515
 516 <screen>
 517 pid&lowbar;t tcgetpgrp( int fd );
 518 int tcsetpgrp( int fd, pid&lowbar;t pgrp );</screen>
 519 </sect2>
 520
 521 <!-- =================================================================== -->
 522
 523 <sect2>
 524 <title>Notes</title>
 525         <itemizedlist>
 526           <listitem>
 527             <para>
 528             Only the functionality relevant to basic serial device
 529             control is implemented. Only very limited support for
 530             canonical input is provided, and then only via the
 531             &ldquo;tty&rdquo; devices, not the &ldquo;serial&rdquo;
 532             devices. None of the functionality relevant to job
 533             control, controlling terminals and sessions is
 534             implemented.
 535             </para>
 536           </listitem>
 537           <listitem>
 538             <para>
 539             Only <emphasis>MIN</emphasis> &equals; 0 and
 540             <emphasis>TIME</emphasis> &equals; 0 functionality is
 541             provided.
 542             </para>
 543           </listitem>
 544           <listitem>
 545             <para>
 546             Hardware flow control is supported if the underlying
 547             device driver and serial port support it.
 548             </para>
 549           </listitem>
 550           <listitem>
 551             <para>
 552             Support for break, framing and parity errors depends on
 553             the functionality of the hardware and device driver.
 554             </para>
 555           </listitem>
 556         </itemizedlist>
 557 </sect2>
 558 </sect1>
 559
 560 <!-- }}} -->
 561 <!-- {{{ C Language Services -->
 562
 563 <sect1 id="posix-C-language-services">
 564 <title>C Language Services &lsqb;POSIX Section 8&rsqb;</title>
 565
 566 <!-- =================================================================== -->
 567
 568 <sect2>
 569 <title>Functions Implemented</title>
 570 <screen>
 571 char &ast;setlocale( int category, const char &ast;locale );
 572 int fileno( FILE &ast;stream );
 573 FILE &ast;fdopen( int fd, const char &ast;type );
 574 int getc&lowbar;unlocked( FILE &ast;stream);
 575 int getchar&lowbar;unlocked( void );
 576 int putc&lowbar;unlocked( FILE &ast;stream );
 577 int putchar&lowbar;unlocked( void );
 578 char &ast;strtok&lowbar;r( char &ast;s, const char &ast;sep,
 579                 char &ast;&ast;lasts );
 580 char &ast;asctime&lowbar;r( const struct tm &ast;tm, char &ast;buf );
 581 char &ast;ctime&lowbar;r( const time&lowbar;t &ast;clock, char &ast;buf );
 582 struct tm &ast;gmtime&lowbar;r( const time&lowbar;t &ast;clock,
 583                      struct tm &ast;result );
 584 struct tm &ast;localtime&lowbar;r( const time&lowbar;t &ast;clock,
 585                         struct tm &ast;result );
 586 int rand&lowbar;r( unsigned int &ast;seed );
 587 </screen>
 588 </sect2>
 589
 590 <!-- =================================================================== -->
 591
 592 <sect2>
 593 <title>Functions Omitted</title>
 594 <screen>
 595 void flockfile( FILE &ast;file );
 596 int ftrylockfile( FILE &ast;file );
 597 void funlockfile( FILE &ast;file );
 598 int sigsetjmp( sigjmp&lowbar;buf env, int savemask );                   &sol;&sol; TBA
 599 void siglongjmp( sigjmp&lowbar;buf env, int val );                      &sol;&sol; TBA
 600 void tzset(void);                                                       &sol;&sol; TBA
 601 </screen>
 602 </sect2>
 603
 604 <!-- =================================================================== -->
 605
 606 <sect2>
 607 <title>Notes</title>
 608         <itemizedlist>
 609           <listitem>
 610             <para>
 611             <emphasis>setlocale()</emphasis> is implemented in the C
 612             library Internationalization package.
 613             </para>
 614           </listitem>
 615           <listitem>
 616             <para>
 617             Functions <emphasis>fileno()</emphasis> and
 618             <emphasis>fdopen()</emphasis> are implemented in the C
 619             library STDIO package.
 620             </para>
 621           </listitem>
 622           <listitem>
 623             <para>
 624             Functions <emphasis>getc&lowbar;unlocked()</emphasis>,
 625             <emphasis>getchar&lowbar;unlocked()</emphasis>,
 626             <emphasis>putc&lowbar;unlocked()</emphasis> and
 627             <emphasis>putchar&lowbar;unlocked()</emphasis> are defined
 628             but are currently identical to their non-unlocked
 629             equivalents.
 630             </para>
 631           </listitem>
 632           <listitem>
 633             <para>
 634             <emphasis>strtok&lowbar;r()</emphasis>, <emphasis>asctime&lowbar;r()</emphasis>,
 635             <emphasis>ctime&lowbar;r()</emphasis>, <emphasis>gmtime&lowbar;r()</emphasis>,
 636             <emphasis>localtime&lowbar;r()</emphasis> and
 637             <emphasis>rand&lowbar;r()</emphasis> are all currently in
 638             the C library, alongside their non-reentrant versions.
 639             </para>
 640           </listitem>
 641         </itemizedlist>
 642 </sect2>
 643 </sect1>
 644
 645 <!-- }}} -->
 646 <!-- {{{ System Databases -->
 647
 648 <sect1 id="posix-system-databases">
 649 <title>System Databases &lsqb;POSIX Section 9&rsqb;</title>
 650
 651 <!-- =================================================================== -->
 652
 653 <sect2>
 654 <title>Functions Implemented</title>
 655
 656 <para>
 657 &lt;none&gt;
 658 </para>
 659
 660 </sect2>
 661
 662 <!-- =================================================================== -->
 663
 664 <sect2>
 665 <title>Functions Omitted</title>
 666
 667 <screen>
 668 struct group &ast;getgrgid( gid&lowbar;t gid );
 669 int getgrgid( gid&lowbar;t gid, struct group &ast;grp, char &ast;buffer,
 670               size&lowbar;t bufsize, struct group &ast;&ast;result );
 671 struct group &ast;getgrname( const char &ast;name );
 672 int getgrname&lowbar;r( const char &ast;name, struct group &ast;grp,
 673                  char &ast;buffer, size&lowbar;t bufsize, struct group &ast;&ast;result );
 674 struct passwd &ast;getpwuid( uid&lowbar;t uid );
 675 int getpwuid&lowbar;r( uid&lowbar;t uid, struct passwd &ast;pwd,
 676                 char &ast;buffer, size&lowbar;t bufsize, struct passwd &ast;&ast;result );
 677 struct passwd &ast;getpwnam( const char &ast;name );
 678 int getpwnam&lowbar;r( const char &ast;name, struct passwd &ast;pwd,
 679                 char &ast;buffer, size&lowbar;t bufsize, struct passwd &ast;&ast;result );
 680 </screen>
 681 </sect2>
 682
 683 <!-- =================================================================== -->
 684
 685 <sect2>
 686 <title>Notes</title>
 687         <itemizedlist>
 688           <listitem>
 689             <para>
 690             None of the functions in this section are implemented.
 691             </para>
 692           </listitem>
 693         </itemizedlist>
 694 </sect2>
 695 </sect1>
 696
 697 <!-- }}} -->
 698 <!-- {{{ Data Interchange Format -->
 699
 700 <sect1 id="posix-data-interchange-format">
 701 <title>Data Interchange Format &lsqb;POSIX Section 10&rsqb;</title>
 702
 703 <para>
 704 This section details <emphasis>tar</emphasis> and
 705 <emphasis>cpio</emphasis> formats. Neither of these is supported by
 706 eCos.
 707 </para>
 708 </sect1>
 709
 710 <!-- }}} -->
 711 <!-- {{{ Synchronization -->
 712
 713 <sect1 id="posix-synchronization">
 714 <title>Synchronization &lsqb;POSIX Section 11&rsqb;</title>
 715
 716
 717 <!-- =================================================================== -->
 718
 719 <sect2>
 720 <title>Functions Implemented</title>
 721
 722 <screen>
 723 int sem&lowbar;init(sem&lowbar;t &ast;sem, int pshared, unsigned int value);
 724 int sem&lowbar;destroy(sem&lowbar;t &ast;sem);
 725 int sem&lowbar;wait(sem&lowbar;t &ast;sem);
 726 int sem&lowbar;trywait(sem&lowbar;t &ast;sem);
 727 int sem&lowbar;post(sem&lowbar;t &ast;sem);
 728 int sem&lowbar;getvalue(sem&lowbar;t &ast;sem, int &ast;sval);
 729 int pthread&lowbar;mutexattr&lowbar;init( pthread&lowbar;mutexattr&lowbar;t &ast;attr);
 730 int pthread&lowbar;mutexattr&lowbar;destroy( pthread&lowbar;mutexattr&lowbar;t &ast;attr);
 731 int pthread&lowbar;mutex&lowbar;init(pthread&lowbar;mutex&lowbar;t &ast;mutex,
 732                        const pthread&lowbar;mutexattr&lowbar;t &ast;mutex&lowbar;attr);
 733 int pthread&lowbar;mutex&lowbar;destroy(pthread&lowbar;mutex&lowbar;t &ast;mutex);
 734 int pthread&lowbar;mutex&lowbar;lock(pthread&lowbar;mutex&lowbar;t &ast;mutex);
 735 int pthread&lowbar;mutex&lowbar;trylock(pthread&lowbar;mutex&lowbar;t &ast;mutex);
 736 int pthread&lowbar;mutex&lowbar;unlock(pthread&lowbar;mutex&lowbar;t &ast;mutex);
 737 int pthread&lowbar;condattr&lowbar;init(pthread&lowbar;condattr&lowbar;t &ast;attr);
 738 int pthread&lowbar;condattr&lowbar;destroy(pthread&lowbar;condattr&lowbar;t &ast;attr);
 739 int pthread&lowbar;cond&lowbar;init(pthread&lowbar;cond&lowbar;t &ast;cond,
 740                        const pthread&lowbar;condattr&lowbar;t &ast;attr);
 741 int pthread&lowbar;cond&lowbar;destroy(pthread&lowbar;cond&lowbar;t &ast;cond);
 742 int pthread&lowbar;cond&lowbar;signal(pthread&lowbar;cond&lowbar;t &ast;cond);
 743 int pthread&lowbar;cond&lowbar;broadcast(pthread&lowbar;cond&lowbar;t &ast;cond);
 744 int pthread&lowbar;cond&lowbar;wait(pthread&lowbar;cond&lowbar;t &ast;cond,
 745                        pthread&lowbar;mutex&lowbar;t &ast;mutex);
 746 int pthread&lowbar;cond&lowbar;timedwait(pthread&lowbar;cond&lowbar;t &ast;cond,
 747                            pthread&lowbar;mutex&lowbar;t &ast;mutex,
 748                            const struct timespec &ast;abstime);
 749 </screen>
 750 </sect2>
 751
 752 <!-- =================================================================== -->
 753
 754 <sect2>
 755 <title>Functions Omitted</title>
 756
 757 <screen>
 758 sem&lowbar;t &ast;sem&lowbar;open(const char &ast;name, int oflag, ...);                &sol;&sol; TBA
 759 int sem&lowbar;close(sem&lowbar;t &ast;sem);                                    &sol;&sol; TBA
 760 int sem&lowbar;unlink(const char &ast;name);                            &sol;&sol; TBA
 761 int pthread&lowbar;mutexattr&lowbar;getpshared( const pthread&lowbar;mutexattr&lowbar;t &ast;attr,
 762                                   int &ast;pshared );
 763 int pthread&lowbar;mutexattr&lowbar;setpshared( const pthread&lowbar;mutexattr&lowbar;t &ast;attr,
 764                                   int pshared );
 765 int  pthread&lowbar;condattr&lowbar;getpshared( const pthread&lowbar;condattr&lowbar;t &ast;attr,
 766                                   int &ast;pshared);
 767 int  pthread&lowbar;condattr&lowbar;setpshared( const pthread&lowbar;condattr&lowbar;t &ast;attr,
 768                                   int pshared);</screen>
 769 </sect2>
 770
 771 <!-- =================================================================== -->
 772
 773 <sect2>
 774 <title>Notes</title>
 775         <itemizedlist>
 776           <listitem>
 777             <para>
 778             The presence of semaphores is controlled by the
 779             CYGPKG&lowbar;POSIX&lowbar;SEMAPHORES option. This in turn
 780             causes the &lowbar;POSIX&lowbar;SEMAPHORES feature test
 781             macro to be defined and the semaphore API to be made
 782             available.
 783             </para>
 784           </listitem>
 785
 786           <listitem>
 787             <para>
 788             The <emphasis role="strong">pshared</emphasis> argument to
 789             <emphasis>sem&lowbar;init()</emphasis> is not implemented,
 790             its value is ignored.
 791             </para>
 792           </listitem>
 793
 794           <listitem>
 795             <para>
 796             Functions <emphasis>sem&lowbar;open()</emphasis>,
 797             <emphasis>sem&lowbar;close()</emphasis> and
 798             <emphasis>sem&lowbar;unlink()</emphasis> are present but
 799             always return an error (ENOSYS).
 800             </para>
 801           </listitem>
 802
 803           <listitem>
 804             <para>
 805             The exact priority inversion protocols supported may be
 806             controlled with the
 807             &lowbar;POSIX&lowbar;THREAD&lowbar;PRIO&lowbar;INHERIT and
 808             &lowbar;POSIX&lowbar;THREAD&lowbar;PRIO&lowbar;PROTECT
 809             configuration options.
 810             </para>
 811           </listitem>
 812
 813           <listitem>
 814             <para>
 815             &lcub;&lowbar;POSIX&lowbar;THREAD&lowbar;PROCESS&lowbar;SHARED&rcub; is
 816             not defined, so the
 817             <emphasis role="strong">process-shared</emphasis> mutex
 818             and condition variable attributes are not supported, and
 819             neither are the functions
 820             <emphasis>pthread&lowbar;mutexattr&lowbar;getpshared()</emphasis>,
 821             <emphasis>pthread&lowbar;mutexattr&lowbar;setpshared()</emphasis>,
 822             <emphasis>pthread&lowbar;condattr&lowbar;getpshared()</emphasis> and
 823             <emphasis>pthread&lowbar;condattr&lowbar;setpshared()</emphasis>.
 824             </para>
 825           </listitem>
 826
 827           <listitem>
 828           <para>
 829             Condition variables do not become bound to a particular
 830             mutex when
 831             <emphasis>pthread&lowbar;cond&lowbar;wait()</emphasis> is
 832             called. Hence different threads may wait on a condition
 833             variable with different mutexes. This is at variance with
 834             the standard, which requires a condition variable to
 835             become (dynamically) bound by the first waiter, and
 836             unbound when the last finishes. However, this difference
 837             is largely benign, and the cost of policing this feature
 838             is non-trivial.
 839           </para>
 840         </listitem>
 841         </itemizedlist>
 842 </sect2>
 843 </sect1>
 844
 845 <!-- }}} -->
 846 <!-- {{{ Memory Management -->
 847
 848 <sect1 id="posix-memory-management">
 849 <title>Memory Management &lsqb;POSIX Section 12&rsqb;</title>
 850
 851 <!-- =================================================================== -->
 852
 853 <sect2>
 854 <title>Functions Implemented</title>
 855
 856 <para>
 857 &lt;none&gt;
 858 </para>
 859 </sect2>
 860
 861 <!-- =================================================================== -->
 862
 863 <sect2>
 864 <title>Functions Omitted</title>
 865
 866 <screen>
 867 int mlockall( int flags );
 868 int munlockall( void );
 869 int mlock( const void &ast;addr, size&lowbar;t len );
 870 int munlock( const void &ast;addr, size&lowbar;t len );
 871 void mmap( void &ast;addr, size&lowbar;t len, int prot, int flags,
 872            int fd, off&lowbar;t off );
 873 int munmap( void &ast;addr, size&lowbar;t len );
 874 int mprotect( const void &ast;addr, size&lowbar;t len, int prot );
 875 int msync( void &ast;addr, size&lowbar;t len, int flags );
 876 int shm&lowbar;open( const char &ast;name, int oflag, mode&lowbar;t mode );
 877 int shm&lowbar;unlink( const char &ast;name );
 878 </screen>
 879 </sect2>
 880
 881 <!-- =================================================================== -->
 882
 883 <sect2>
 884 <title>Notes</title>
 885 <para>
 886 None of these functions are currently provided. Some may
 887 be implemented in a restricted form in the future.
 888 </para>
 889
 890 </sect2>
 891 </sect1>
 892
 893 <!-- }}} -->
 894 <!-- {{{ Execution Scheduling -->
 895
 896 <sect1 id="posix-execution-scheduling">
 897 <title>Execution Scheduling &lsqb;POSIX Section 13&rsqb;</title>
 898
 899 <!-- =================================================================== -->
 900
 901 <sect2>
 902 <title>Functions Implemented</title>
 903
 904 <screen>
 905 int sched&lowbar;yield(void);
 906 int sched&lowbar;get&lowbar;priority&lowbar;max(int policy);
 907 int sched&lowbar;get&lowbar;priority&lowbar;min(int policy);
 908 int sched&lowbar;rr&lowbar;get&lowbar;interval(pid&lowbar;t pid, struct timespec &ast;t);
 909 int pthread&lowbar;attr&lowbar;setscope(pthread&lowbar;attr&lowbar;t &ast;attr, int scope);
 910 int pthread&lowbar;attr&lowbar;getscope(const pthread&lowbar;attr&lowbar;t &ast;attr, int &ast;scope);
 911 int pthread&lowbar;attr&lowbar;setinheritsched(pthread&lowbar;attr&lowbar;t &ast;attr, int inherit);
 912 int pthread&lowbar;attr&lowbar;getinheritsched(const pthread&lowbar;attr&lowbar;t &ast;attr, int &ast;inherit);
 913 int pthread&lowbar;attr&lowbar;setschedpolicy(pthread&lowbar;attr&lowbar;t &ast;attr, int policy);
 914 int pthread&lowbar;attr&lowbar;getschedpolicy(const pthread&lowbar;attr&lowbar;t &ast;attr, int &ast;policy);
 915 int pthread&lowbar;attr&lowbar;setschedparam( pthread&lowbar;attr&lowbar;t &ast;attr, const struct sched&lowbar;param &ast;param);
 916 int pthread&lowbar;attr&lowbar;getschedparam( const pthread&lowbar;attr&lowbar;t &ast;attr,
 917                                 struct sched&lowbar;param &ast;param);
 918 int pthread&lowbar;setschedparam(pthread&lowbar;t thread, int policy,
 919                           const struct sched&lowbar;param &ast;param);
 920 int pthread&lowbar;getschedparam(pthread&lowbar;t thread, int &ast;policy,
 921                           struct sched&lowbar;param &ast;param);
 922 int pthread&lowbar;mutexattr&lowbar;setprotocol( pthread&lowbar;mutexattr&lowbar;t &ast;attr,
 923                                    int protocol);
 924 int pthread&lowbar;mutexattr&lowbar;getprotocol( pthread&lowbar;mutexattr&lowbar;t &ast;attr,
 925                                    int &ast;protocol);
 926 int pthread&lowbar;mutexattr&lowbar;setprioceiling( pthread&lowbar;mutexattr&lowbar;t &ast;attr,
 927                                       int prioceiling);
 928 int pthread&lowbar;mutexattr&lowbar;getprioceiling( pthread&lowbar;mutexattr&lowbar;t &ast;attr,
 929                                       int &ast;prioceiling);
 930 int pthread&lowbar;mutex&lowbar;setprioceiling( pthread&lowbar;mutex&lowbar;t &ast;mutex,
 931                                   int prioceiling,
 932                                   int &ast;old&lowbar;ceiling);
 933 int pthread&lowbar;mutex&lowbar;getprioceiling( pthread&lowbar;mutex&lowbar;t &ast;mutex,
 934                                   int &ast;prioceiling);
 935 </screen>
 936 </sect2>
 937
 938 <!-- =================================================================== -->
 939
 940 <sect2>
 941 <title>Functions Omitted</title>
 942
 943 <screen>
 944 int sched&lowbar;setparam(pid&lowbar;t pid, const struct sched&lowbar;param &ast;param);
 945 int sched&lowbar;getparam(pid&lowbar;t pid, struct sched&lowbar;param &ast;param);
 946 int sched&lowbar;setscheduler(pid&lowbar;t pid, int policy,
 947                        const struct sched&lowbar;param &ast;param);
 948 int sched&lowbar;getscheduler(pid&lowbar;t pid);
 949 </screen>
 950 </sect2>
 951
 952 <!-- =================================================================== -->
 953
 954 <sect2>
 955 <title>Notes</title>
 956         <itemizedlist>
 957         <listitem>
 958           <para>
 959           The functions <emphasis>sched&lowbar;setparam()</emphasis>,
 960           <emphasis>sched&lowbar;getparam()</emphasis>,
 961           <emphasis>sched&lowbar;setscheduler()</emphasis> and
 962           <emphasis>sched&lowbar;getscheduler()</emphasis> are present
 963           but always return an error.
 964           </para>
 965         </listitem>
 966         <listitem>
 967           <para>
 968           The scheduler policy <emphasis>SCHED&lowbar;OTHER</emphasis> is
 969           equivalent to <emphasis>SCHED&lowbar;RR</emphasis>.
 970           </para>
 971         </listitem>
 972         <listitem>
 973           <para>
 974           Only <emphasis>PTHREAD&lowbar;SCOPE&lowbar;SYSTEM</emphasis>
 975           is supported as a
 976           <emphasis role="strong">contentionscope</emphasis>
 977           attribute.
 978           </para>
 979         </listitem>
 980         <listitem>
 981           <para>
 982           The default thread scheduling attributes are:
 983           <screen>
 984           contentionscope          PTHREAD&lowbar;SCOPE&lowbar;SYSTEM
 985           inheritsched             PTHREAD&lowbar;INHERIT&lowbar;SCHED
 986           schedpolicy              SCHED&lowbar;OTHER
 987           schedparam.sched         0
 988           </screen>
 989           </para>
 990         </listitem>
 991         <listitem>
 992           <para>
 993           Mutex priority inversion protection is controlled by a
 994           number of kernel configuration options.
 995           If CYGSEM&lowbar;KERNEL&lowbar;SYNCH&lowbar;MUTEX&lowbar;PRIORITY&lowbar;INVERSION&lowbar;PROTOCOL&lowbar;INHERIT
 996           is defined then
 997           &lcub;&lowbar;POSIX&lowbar;THREAD&lowbar;PRIO&lowbar;INHERIT&rcub;
 998           will be defined and PTHREAD&lowbar;PRIO&lowbar;INHERIT may
 999           be set as the protocol in a
1000           <emphasis>pthread&lowbar;mutexattr&lowbar;t</emphasis>
1001           object.
1002           If CYGSEM&lowbar;KERNEL&lowbar;SYNCH&lowbar;MUTEX&lowbar;PRIORITY&lowbar;INVERSION&lowbar;PROTOCOL&lowbar;CEILING
1003           is defined then
1004           &lcub;&lowbar;POSIX&lowbar;THREAD&lowbar;PRIO&lowbar;PROTECT&rcub;
1005           will be defined and PTHREAD&lowbar;PRIO&lowbar;PROTECT may
1006           be set as the protocol in a
1007           <emphasis>pthread&lowbar;mutexattr&lowbar;t</emphasis> object.
1008           </para>
1009         </listitem>
1010         <listitem>
1011           <para>
1012           The default attribute values set by
1013           <emphasis>pthread&lowbar;mutexattr&lowbar;init()</emphasis>
1014           is to set the protocol attribute to
1015           PTHREAD&lowbar;PRIO&lowbar;NONE and the prioceiling
1016           attribute to zero.
1017           </para>
1018         </listitem>
1019         </itemizedlist>
1020
1021 </sect2>
1022 </sect1>
1023
1024 <!-- }}} -->
1025 <!-- {{{ Clocks and Timers -->
1026
1027 <sect1 id="posix-clocks-and-timers">
1028 <title>Clocks and Timers &lsqb;POSIX Section 14&rsqb;</title>
1029
1030 <!-- =================================================================== -->
1031
1032 <sect2>
1033 <title>Functions Implemented</title>
1034
1035 <screen>
1036 int clock&lowbar;settime( clockid&lowbar;t clock&lowbar;id,
1037 const struct timespec &ast;tp);
1038 int clock&lowbar;gettime( clockid&lowbar;t clock&lowbar;id, struct timespec &ast;tp);
1039 int clock&lowbar;getres( clockid&lowbar;t clock&lowbar;id, struct timespec &ast;tp);
1040 int timer&lowbar;create( clockid&lowbar;t clock&lowbar;id, struct sigevent &ast;evp,
1041                   timer&lowbar;t &ast;timer&lowbar;id);
1042 int timer&lowbar;delete( timer&lowbar;t timer&lowbar;id );
1043 int timer&lowbar;settime( timer&lowbar;t timerid, int flags,
1044                    const struct itimerspec &ast;value,
1045                    struct itimerspec &ast;ovalue );
1046 int timer&lowbar;gettime( timer&lowbar;t timerid, struct itimerspec &ast;value );
1047 int timer&lowbar;getoverrun( timer&lowbar;t timerid );
1048 int nanosleep( const struct timespec &ast;rqtp, struct timespec &ast;rmtp);
1049 int gettimeofday(struct timeval *tv, struct timezone* tz);
1050 </screen>
1051
1052 </sect2>
1053
1054
1055 <!-- =================================================================== -->
1056
1057 <sect2>
1058 <title>Functions Omitted</title>
1059
1060 <para>
1061 &lt;none&gt;
1062 </para>
1063
1064 </sect2>
1065
1066 <!-- =================================================================== -->
1067
1068 <sect2>
1069 <title>Notes</title>
1070
1071 <itemizedlist>
1072   <listitem>
1073     <para>
1074     Currently <emphasis>timer&lowbar;getoverrun()</emphasis> only
1075     reports timer notifications that are delayed in the timer
1076     subsystem.  If they are delayed in the signal subsystem, due to
1077     signal masks for example, this is not counted as an overrun.
1078     </para>
1079   </listitem>
1080
1081   <listitem>
1082     <para>
1083     The option CYGPKG&lowbar;POSIX&lowbar;TIMERS allows the timer support to be
1084     enabled or disabled, and causes &lowbar;POSIX&lowbar;TIMERS to be defined
1085     appropriately. This will cause other parts of the POSIX system to
1086     have limited functionality.
1087     </para>
1088   </listitem>
1089
1090 </itemizedlist>
1091
1092 </sect2>
1093 </sect1>
1094
1095 <!-- }}} -->
1096 <!-- {{{ Message Passing -->
1097
1098 <sect1 id="posix-message-passing">
1099 <title>Message Passing &lsqb;POSIX Section 15&rsqb;</title>
1100
1101 <!-- =================================================================== -->
1102
1103 <sect2>
1104 <title>Functions Implemented</title>
1105
1106 <screen>
1107 mqd&lowbar;t mq&lowbar;open( const char &ast;name, int  oflag, ... );
1108 int mq&lowbar;close( mqd&lowbar;t  mqdes );
1109 int mq&lowbar;unlink( const char &ast;name );
1110 int mq&lowbar;send( mqd&lowbar;t mqdes, const char &ast;msg&lowbar;ptr,
1111              size&lowbar;t msg&lowbar;len, unsigned int msg&lowbar;prio );
1112 ssize&lowbar;t mq&lowbar;receive( mqd&lowbar;t mqdes, char &ast;msg&lowbar;ptr,
1113                     size&lowbar;t msg&lowbar;len, unsigned int &ast;msg&lowbar;prio );
1114 int mq&lowbar;setattr( mqd&lowbar;t mqdes, const struct mq&lowbar;attr &ast;mqstat,
1115                 struct mq&lowbar;attr &ast;omqstat );
1116 int mq&lowbar;getattr( mqd&lowbar;t mqdes, struct mq&lowbar;attr &ast;mqstat );
1117 int mq&lowbar;notify( mqd&lowbar;t mqdes, const struct sigevent &ast;notification );
1118 </screen>
1119 <para>From POSIX 1003.1d draft: </para>
1120 <screen>
1121 int mq&lowbar;send( mqd&lowbar;t mqdes, const char &ast;msg&lowbar;ptr,
1122              size&lowbar;t msg&lowbar;len, unsigned int msg&lowbar;prio,
1123              const struct timespec *abs_timeout );
1124 ssize&lowbar;t mq&lowbar;receive( mqd&lowbar;t mqdes, char &ast;msg&lowbar;ptr,
1125                     size&lowbar;t msg&lowbar;len, unsigned int &ast;msg&lowbar;prio,
1126              const struct timespec *abs_timeout );
1127 </screen>
1128 </sect2>
1129
1130 <!-- =================================================================== -->
1131
1132 <sect2>
1133 <title>Functions Omitted</title>
1134
1135 <para>
1136 &lt;none&gt;
1137 </para>
1138
1139 </sect2>
1140
1141 <!-- =================================================================== -->
1142
1143 <sect2>
1144 <title>Notes</title>
1145
1146 <itemizedlist>
1147   <listitem>
1148     <para>
1149     The presence of message queues is controlled by the
1150     CYGPKG&lowbar;POSIX&lowbar;MQUEUES option.  Setting this will
1151     cause &lsqb;&lowbar;POSIX&lowbar;MESSAGE&lowbar;PASSING&rsqb; to
1152     be defined and the message queue API to be made available.
1153     </para>
1154   </listitem>
1155
1156   <listitem>
1157     <para>
1158     Message queues are not currently filesystem objects. They live in
1159     their own name and descriptor spaces.
1160     </para>
1161   </listitem>
1162 </itemizedlist>
1163
1164 </sect2>
1165 </sect1>
1166
1167 <!-- }}} -->
1168 <!-- {{{ Thread Management -->
1169
1170 <sect1 id="posix-thread-management">
1171 <title>Thread Management &lsqb;POSIX Section 16&rsqb;</title>
1172
1173 <!-- =================================================================== -->
1174
1175 <sect2>
1176 <title>Functions Implemented</title>
1177
1178 <screen>
1179 int pthread&lowbar;attr&lowbar;init(pthread&lowbar;attr&lowbar;t &ast;attr);
1180 int pthread&lowbar;attr&lowbar;destroy(pthread&lowbar;attr&lowbar;t &ast;attr);
1181 int pthread&lowbar;attr&lowbar;setdetachstate(pthread&lowbar;attr&lowbar;t &ast;attr,
1182                                 int detachstate);
1183 int pthread&lowbar;attr&lowbar;getdetachstate(const pthread&lowbar;attr&lowbar;t &ast;attr,
1184                                 int &ast;detachstate);
1185 int pthread&lowbar;attr&lowbar;setstackaddr(pthread&lowbar;attr&lowbar;t &ast;attr,
1186                               void &ast;stackaddr);
1187 int pthread&lowbar;attr&lowbar;getstackaddr(const pthread&lowbar;attr&lowbar;t &ast;attr,
1188                               void &ast;&ast;stackaddr);
1189 int pthread&lowbar;attr&lowbar;setstacksize(pthread&lowbar;attr&lowbar;t &ast;attr,
1190                               size&lowbar;t stacksize);
1191 int pthread&lowbar;attr&lowbar;getstacksize(const pthread&lowbar;attr&lowbar;t &ast;attr,
1192                               size&lowbar;t &ast;stacksize);
1193 int pthread&lowbar;create( pthread&lowbar;t &ast;thread,
1194                     const pthread&lowbar;attr&lowbar;t &ast;attr,
1195                     void &ast;(&ast;start&lowbar;routine)(void &ast;),
1196                     void &ast;arg);
1197 pthread&lowbar;t pthread&lowbar;self( void );
1198 int pthread&lowbar;equal(pthread&lowbar;t thread1, pthread&lowbar;t thread2);
1199 void pthread&lowbar;exit(void &ast;retval);
1200 int pthread&lowbar;join(pthread&lowbar;t thread, void &ast;&ast;thread&lowbar;return);
1201 int pthread&lowbar;detach(pthread&lowbar;t thread);
1202 int pthread&lowbar;once(pthread&lowbar;once&lowbar;t &ast;once&lowbar;control,
1203                  void (&ast;init&lowbar;routine)(void));
1204 </screen>
1205
1206 </sect2>
1207
1208 <!-- =================================================================== -->
1209
1210 <sect2>
1211 <title>Functions Omitted</title>
1212
1213 <para>
1214 &lt;none&gt;
1215 </para>
1216
1217 </sect2>
1218
1219 <!-- =================================================================== -->
1220
1221 <sect2>
1222 <title>Notes</title>
1223
1224 <itemizedlist>
1225   <listitem>
1226     <para>
1227     The presence of thread support as a whole is controlled by the the
1228     CYGPKG_POSIX_PTHREAD configuration option. Note that disabling
1229     this will also disable many other features of the POSIX package,
1230     since these are intimately bound up with the thread mechanism.
1231     </para>
1232   </listitem>
1233
1234   <listitem>
1235     <para>
1236     The default (non-scheduling) thread attributes are:
1237     </para>
1238     <screen>
1239     detachstate            PTHREAD&lowbar;CREATE&lowbar;JOINABLE
1240     stackaddr              unset
1241     stacksize              unset
1242     </screen>
1243   </listitem>
1244
1245   <listitem>
1246     <para>
1247       Dynamic thread stack allocation is only provided if there is an
1248       implementation of
1249       <emphasis>malloc()</emphasis> configured (i.e. a package
1250       implements the
1251       CYGINT&lowbar;MEMALLOC&lowbar;MALLOC&lowbar;ALLOCATORS
1252       interface). If there is no malloc() available, then the thread
1253       creator must supply a stack. If only a stack address is supplied
1254       then the stack is assumed to be PTHREAD&lowbar;STACK&lowbar;MIN
1255       bytes long. This size is seldom useful for any but the most
1256       trivial of threads.  If a different sized stack is used, both
1257       the stack address and stack size must be supplied.
1258     </para>
1259   </listitem>
1260
1261   <listitem>
1262     <para>
1263       The value of PTHREAD&lowbar;THREADS&lowbar;MAX is supplied by
1264       the CYGNUM&lowbar;POSIX&lowbar;PTHREAD&lowbar;THREADS&lowbar;MAX
1265       option. This defines the maximum number of threads allowed. The
1266       POSIX standard requires this value to be at least 64, and this
1267       is the default value set.
1268     </para>
1269   </listitem>
1270
1271   <listitem>
1272     <para>
1273     When the POSIX package is installed, the thread that calls
1274     <emphasis>main()</emphasis> is initialized as a POSIX thread. The
1275     priority of that thread is controlled by the
1276     CYGNUM&lowbar;POSIX&lowbar;MAIN&lowbar;DEFAULT&lowbar;PRIORITY option.
1277     </para>
1278   </listitem>
1279 </itemizedlist>
1280
1281 </sect2>
1282 </sect1>
1283
1284 <!-- }}} -->
1285 <!-- {{{ Thread-Specific Data -->
1286
1287 <sect1 id="posix-thread-specific-data">
1288 <title>Thread-Specific Data &lsqb;POSIX Section 17&rsqb;</title>
1289
1290 <!-- =================================================================== -->
1291
1292 <sect2>
1293 <title>Functions Implemented</title>
1294
1295 <screen>
1296 int pthread&lowbar;key&lowbar;create(pthread&lowbar;key&lowbar;t &ast;key,
1297                        void (&ast;destructor)(void &ast;));
1298 int pthread&lowbar;setspecific(pthread&lowbar;key&lowbar;t key, const void &ast;pointer);
1299 void &ast;pthread&lowbar;getspecific(pthread&lowbar;key&lowbar;t key);
1300 int pthread&lowbar;key&lowbar;delete(pthread&lowbar;key&lowbar;t key);
1301 </screen>
1302
1303 </sect2>
1304
1305 <!-- =================================================================== -->
1306
1307 <sect2>
1308 <title>Functions Omitted</title>
1309 <para>
1310 &lt;none&gt;
1311 </para>
1312 </sect2>
1313
1314 <!-- =================================================================== -->
1315
1316 <sect2>
1317 <title>Notes</title>
1318
1319 <itemizedlist>
1320   <listitem>
1321     <para>
1322     The value of PTHREAD&lowbar;DESTRUCTOR&lowbar;ITERATIONS is
1323     provided by the
1324     CYGNUM&lowbar;POSIX&lowbar;PTHREAD&lowbar;DESTRUCTOR&lowbar;ITERATIONS
1325     option. This controls the number of times that a key destructor
1326     will be called while the data item remains non-NULL.
1327     </para>
1328   </listitem>
1329
1330   <listitem>
1331     <para>
1332     The value of PTHREAD&lowbar;KEYS&lowbar;MAX is provided
1333     by the CYGNUM&lowbar;POSIX&lowbar;PTHREAD&lowbar;KEYS&lowbar;MAX
1334     option. This defines the maximum number of per-thread data items
1335     supported. The POSIX standard calls for this to be a minimum of
1336     128, which is rather large for an embedded system. The default
1337     value for this option is set to 128 for compatibility but it
1338     should be reduced to a more usable value.
1339     </para>
1340   </listitem>
1341 </itemizedlist>
1342
1343 </sect2>
1344 </sect1>
1345
1346 <!-- }}} -->
1347 <!-- {{{ Thread Cancellation -->
1348
1349 <sect1 id="posix-thread-cancellation">
1350 <title>Thread Cancellation &lsqb;POSIX Section 18&rsqb;</title>
1351
1352 <!-- =================================================================== -->
1353
1354 <sect2>
1355 <title>Functions Implemented</title>
1356
1357 <screen>
1358 int pthread&lowbar;cancel(pthread&lowbar;t thread);
1359 int pthread&lowbar;setcancelstate(int state, int &ast;oldstate);
1360 int pthread&lowbar;setcanceltype(int type, int &ast;oldtype);
1361 void pthread&lowbar;testcancel(void);
1362 void pthread&lowbar;cleanup&lowbar;push( void (&ast;routine)(void &ast;),
1363                            void &ast;arg);
1364 void pthread&lowbar;cleanup&lowbar;pop( int execute);
1365 </screen>
1366 </sect2>
1367
1368
1369 <!-- =================================================================== -->
1370
1371 <sect2>
1372 <title>Functions Omitted</title>
1373 <para>
1374 &lt;none&gt;
1375 </para>
1376 </sect2>
1377
1378 <!-- =================================================================== -->
1379
1380 <sect2>
1381 <title>Notes</title>
1382 <para>
1383 Asynchronous cancellation is only partially implemented.  In
1384 particular, cancellation may occur in unexpected places in some
1385 functions. It is strongly recommended that only synchronous
1386 cancellation be used.
1387 </para>
1388 </sect2>
1389 </sect1>
1390
1391 <!-- }}} -->
1392 <!-- {{{ Non-POSIX Functions -->
1393
1394 <sect1 id="posix-non-posix-functions">
1395 <title>Non-POSIX Functions</title>
1396
1397 <para>
1398 In addition to the standard POSIX functions defined above, the
1399 following non-POSIX functions are defined in the FILEIO package.
1400 </para>
1401
1402 <!-- =================================================================== -->
1403
1404 <sect2>
1405 <title>General I&sol;O Functions</title>
1406 <screen>
1407 int ioctl( int fd, CYG&lowbar;ADDRWORD com, CYG&lowbar;ADDRWORD data );
1408 int select( int nfd, fd&lowbar;set &ast;in, fd&lowbar;set &ast;out, fd&lowbar;set &ast;ex, struct timeval &ast;tv);
1409 </screen>
1410 </sect2>
1411
1412
1413 <!-- =================================================================== -->
1414
1415 <sect2>
1416 <title>Socket Functions</title>
1417 <screen>
1418 int socket( int domain, int type, int protocol);
1419 int bind( int s, const struct sockaddr &ast;sa, unsigned int len);
1420 int listen( int s, int len);
1421 int accept( int s, struct sockaddr &ast;sa, socklen&lowbar;t &ast;addrlen);
1422 int connect( int s, const struct sockaddr &ast;sa, socklen&lowbar;t len);
1423 int getpeername( int s, struct sockaddr &ast;sa, socklen&lowbar;t &ast;len);
1424 int getsockname( int s, struct sockaddr &ast;sa, socklen&lowbar;t &ast;len);
1425 int setsockopt( int s, int level, int optname, const void &ast;optval,
1426                 socklen&lowbar;t optlen);
1427 int getsockopt( int s, int level, int optname, void &ast;optval,
1428                 socklen&lowbar;t &ast;optlen);
1429 ssize&lowbar;t recvmsg( int s, struct msghdr &ast;msg, int flags);
1430 ssize&lowbar;t recvfrom( int s, void &ast;buf, size&lowbar;t len, int flags,
1431                   struct sockaddr &ast;from, socklen&lowbar;t &ast;fromlen);
1432 ssize&lowbar;t recv( int s, void &ast;buf, size&lowbar;t len, int flags);
1433 ssize&lowbar;t sendmsg( int s, const struct msghdr &ast;msg, int flags);
1434 ssize&lowbar;t sendto( int s, const void &ast;buf, size&lowbar;t len, int flags,
1435                 const struct sockaddr &ast;to, socklen&lowbar;t tolen);
1436 ssize&lowbar;t send( int s, const void &ast;buf, size&lowbar;t len, int flags);
1437 int shutdown( int s, int how);
1438 </screen>
1439 </sect2>
1440
1441 <!-- =================================================================== -->
1442
1443 <sect2>
1444 <title>Notes</title>
1445 <itemizedlist>
1446   <listitem>
1447    <para>
1448    The precise behaviour of these functions depends mainly on the
1449    functionality of the underlying filesystem or network stack to
1450    which they are applied.
1451    </para>
1452   </listitem>
1453 </itemizedlist>
1454 </sect2>
1455 </sect1>
1456
1457 <!-- }}} -->
1458
1459 </chapter>
1460
1461 <!-- {{{ Bibliography -->
1462
1463 <bibliography id="posix-references-and-bibliography">
1464 <title>References and Bibliography</title>
1465
1466     <bibliomixed>
1467       <bibliomisc>&lsqb;Lewine&rsqb;</bibliomisc>
1468       <author>
1469         <firstname>Donald</firstname>
1470         <othername>A.</othername>
1471         <surname>Lweine</surname>
1472       </author>
1473       <title>Posix Programmer&rsquo;s Guide: Writing Portable Unix
1474         Programs With the POSIX.1 Standard O&rsquo;Reilly &amp;
1475         Associates; ISBN: 0937175730.</title></bibliomixed>
1476
1477     <bibliomixed>
1478       <bibliomisc>&lsqb;Lewis1&rsqb;</bibliomisc>
1479       <author>
1480         <firstname>Bil</firstname>
1481         <surname>Lewis</surname>
1482       </author>
1483       <author>
1484         <firstname>Daniel</firstname>
1485         <othername>J.</othername>
1486         <surname>Berg</surname>
1487       </author>
1488       <title>Threads Primer: A Guide to Multithreaded Programming</title>
1489       <publishername>Prentice Hall</publishername>
1490       <isbn>ISBN: 013443698</isbn>
1491     </bibliomixed>
1492
1493     <bibliomixed>
1494       <bibliomisc>&lsqb;Lewis2&rsqb;</bibliomisc>
1495       <author>
1496         <firstname>Bil</firstname>
1497         <surname>Lewis</surname>
1498       </author>
1499       <author>
1500         <firstname>Daniel</firstname>
1501         <othername>J.</othername>
1502         <surname>Berg</surname>
1503       </author>
1504       <title>Multithreaded Programming With Pthreads</title>
1505       <publisher>
1506         <publishername>Prentice Hall Computer Books</publishername>
1507       </publisher>
1508       <isbn>ISBN: 0136807291</isbn>
1509     </bibliomixed>
1510
1511     <bibliomixed>
1512       <bibliomisc>&lsqb;Nichols&rsqb;</bibliomisc>
1513       <author>
1514         <firstname>Bradford</firstname>
1515         <surname>Nichols</surname>
1516       </author>
1517       <author>
1518         <firstname>Dick</firstname>
1519         <surname>Buttlar</surname>
1520       </author>
1521       <author>
1522         <firstname>Jacqueline</firstname>
1523         <othername>Proulx</othername>
1524         <surname>Farrell</surname>
1525       </author>
1526       <title>Pthreads Programming: A POSIX Standard for Better
1527         Multiprocessing (O&rsquo;Reilly Nutshell)</title>
1528       <publisher><publishername>O&rsquo;Reilly &amp; Associates</publishername>
1529       </publisher>
1530       <isbn>ISBN: 1565921151</isbn>
1531     </bibliomixed>
1532
1533     <bibliomixed>
1534       <bibliomisc>&lsqb;Norton&rsqb;</bibliomisc>
1535       <author>
1536         <firstname>Scott</firstname>
1537         <othername>J.</othername>
1538         <surname>Norton</surname>
1539       </author>
1540       <author>
1541         <firstname>Mark</firstname>
1542         <othername>D.</othername>
1543         <surname>Depasquale</surname>
1544       </author>
1545       <title>Thread Time: The MultiThreaded Programming Guide</title>
1546       <publisher><publishername>Prentice Hall</publishername>
1547       </publisher>
1548       <isbn>ISBN: 0131900676</isbn></bibliomixed>
1549
1550
1551     <bibliomixed>
1552       <bibliomisc>&lsqb;POSIX&rsqb;</bibliomisc>
1553       <title>Portable Operating System Interface(POSIX) -
1554 Part 1: System Application Programming Interface (API)&lsqb;C
1555 Language&rsqb;</title>
1556       <corpauthor>ISO&sol;IEC 9945-1:1996, IEEE</corpauthor></bibliomixed>
1557
1558     <bibliomixed>
1559       <bibliomisc>&lsqb;SUS2&rsqb;</bibliomisc>
1560       <title>Open Group; Single Unix Specification, Version 2</title>
1561       <bibliomisc><ulink
1562       url="http://www.opengroup.org/public/pubs/online/7908799/index.html">http://www.opengroup.org/public/pubs/online/7908799/index.html</ulink></bibliomisc>
1563     </bibliomixed>
1564
1565   </bibliography>
1566
1567 <!-- }}} -->
1568
1569 </part>