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 </screen>
1050
1051 </sect2>
1052
1053
1054 <!-- =================================================================== -->
1055
1056 <sect2>
1057 <title>Functions Omitted</title>
1058
1059 <para>
1060 &lt;none&gt;
1061 </para>
1062
1063 </sect2>
1064
1065 <!-- =================================================================== -->
1066
1067 <sect2>
1068 <title>Notes</title>
1069
1070 <itemizedlist>
1071   <listitem>
1072     <para>
1073     Currently <emphasis>timer&lowbar;getoverrun()</emphasis> only
1074     reports timer notifications that are delayed in the timer
1075     subsystem.  If they are delayed in the signal subsystem, due to
1076     signal masks for example, this is not counted as an overrun.
1077     </para>
1078   </listitem>
1079
1080   <listitem>
1081     <para>
1082     The option CYGPKG&lowbar;POSIX&lowbar;TIMERS allows the timer support to be
1083     enabled or disabled, and causes &lowbar;POSIX&lowbar;TIMERS to be defined
1084     appropriately. This will cause other parts of the POSIX system to
1085     have limited functionality.
1086     </para>
1087   </listitem>
1088
1089 </itemizedlist>
1090
1091 </sect2>
1092 </sect1>
1093
1094 <!-- }}} -->
1095 <!-- {{{ Message Passing -->
1096
1097 <sect1 id="posix-message-passing">
1098 <title>Message Passing &lsqb;POSIX Section 15&rsqb;</title>
1099
1100 <!-- =================================================================== -->
1101
1102 <sect2>
1103 <title>Functions Implemented</title>
1104
1105 <screen>
1106 mqd&lowbar;t mq&lowbar;open( const char &ast;name, int  oflag, ... );
1107 int mq&lowbar;close( mqd&lowbar;t  mqdes );
1108 int mq&lowbar;unlink( const char &ast;name );
1109 int mq&lowbar;send( mqd&lowbar;t mqdes, const char &ast;msg&lowbar;ptr,
1110              size&lowbar;t msg&lowbar;len, unsigned int msg&lowbar;prio );
1111 ssize&lowbar;t mq&lowbar;receive( mqd&lowbar;t mqdes, char &ast;msg&lowbar;ptr,
1112                     size&lowbar;t msg&lowbar;len, unsigned int &ast;msg&lowbar;prio );
1113 int mq&lowbar;setattr( mqd&lowbar;t mqdes, const struct mq&lowbar;attr &ast;mqstat,
1114                 struct mq&lowbar;attr &ast;omqstat );
1115 int mq&lowbar;getattr( mqd&lowbar;t mqdes, struct mq&lowbar;attr &ast;mqstat );
1116 int mq&lowbar;notify( mqd&lowbar;t mqdes, const struct sigevent &ast;notification );
1117 </screen>
1118 <para>From POSIX 1003.1d draft: </para>
1119 <screen>
1120 int mq&lowbar;send( mqd&lowbar;t mqdes, const char &ast;msg&lowbar;ptr,
1121              size&lowbar;t msg&lowbar;len, unsigned int msg&lowbar;prio,
1122              const struct timespec *abs_timeout );
1123 ssize&lowbar;t mq&lowbar;receive( mqd&lowbar;t mqdes, char &ast;msg&lowbar;ptr,
1124                     size&lowbar;t msg&lowbar;len, unsigned int &ast;msg&lowbar;prio,
1125              const struct timespec *abs_timeout );
1126 </screen>
1127 </sect2>
1128
1129 <!-- =================================================================== -->
1130
1131 <sect2>
1132 <title>Functions Omitted</title>
1133
1134 <para>
1135 &lt;none&gt;
1136 </para>
1137
1138 </sect2>
1139
1140 <!-- =================================================================== -->
1141
1142 <sect2>
1143 <title>Notes</title>
1144
1145 <itemizedlist>
1146   <listitem>
1147     <para>
1148     The presence of message queues is controlled by the
1149     CYGPKG&lowbar;POSIX&lowbar;MQUEUES option.  Setting this will
1150     cause &lsqb;&lowbar;POSIX&lowbar;MESSAGE&lowbar;PASSING&rsqb; to
1151     be defined and the message queue API to be made available.
1152     </para>
1153   </listitem>
1154
1155   <listitem>
1156     <para>
1157     Message queues are not currently filesystem objects. They live in
1158     their own name and descriptor spaces.
1159     </para>
1160   </listitem>
1161 </itemizedlist>
1162
1163 </sect2>
1164 </sect1>
1165
1166 <!-- }}} -->
1167 <!-- {{{ Thread Management -->
1168
1169 <sect1 id="posix-thread-management">
1170 <title>Thread Management &lsqb;POSIX Section 16&rsqb;</title>
1171
1172 <!-- =================================================================== -->
1173
1174 <sect2>
1175 <title>Functions Implemented</title>
1176
1177 <screen>
1178 int pthread&lowbar;attr&lowbar;init(pthread&lowbar;attr&lowbar;t &ast;attr);
1179 int pthread&lowbar;attr&lowbar;destroy(pthread&lowbar;attr&lowbar;t &ast;attr);
1180 int pthread&lowbar;attr&lowbar;setdetachstate(pthread&lowbar;attr&lowbar;t &ast;attr,
1181                                 int detachstate);
1182 int pthread&lowbar;attr&lowbar;getdetachstate(const pthread&lowbar;attr&lowbar;t &ast;attr,
1183                                 int &ast;detachstate);
1184 int pthread&lowbar;attr&lowbar;setstackaddr(pthread&lowbar;attr&lowbar;t &ast;attr,
1185                               void &ast;stackaddr);
1186 int pthread&lowbar;attr&lowbar;getstackaddr(const pthread&lowbar;attr&lowbar;t &ast;attr,
1187                               void &ast;&ast;stackaddr);
1188 int pthread&lowbar;attr&lowbar;setstacksize(pthread&lowbar;attr&lowbar;t &ast;attr,
1189                               size&lowbar;t stacksize);
1190 int pthread&lowbar;attr&lowbar;getstacksize(const pthread&lowbar;attr&lowbar;t &ast;attr,
1191                               size&lowbar;t &ast;stacksize);
1192 int pthread&lowbar;create( pthread&lowbar;t &ast;thread,
1193                     const pthread&lowbar;attr&lowbar;t &ast;attr,
1194                     void &ast;(&ast;start&lowbar;routine)(void &ast;),
1195                     void &ast;arg);
1196 pthread&lowbar;t pthread&lowbar;self( void );
1197 int pthread&lowbar;equal(pthread&lowbar;t thread1, pthread&lowbar;t thread2);
1198 void pthread&lowbar;exit(void &ast;retval);
1199 int pthread&lowbar;join(pthread&lowbar;t thread, void &ast;&ast;thread&lowbar;return);
1200 int pthread&lowbar;detach(pthread&lowbar;t thread);
1201 int pthread&lowbar;once(pthread&lowbar;once&lowbar;t &ast;once&lowbar;control,
1202                  void (&ast;init&lowbar;routine)(void));
1203 </screen>
1204
1205 </sect2>
1206
1207 <!-- =================================================================== -->
1208
1209 <sect2>
1210 <title>Functions Omitted</title>
1211
1212 <para>
1213 &lt;none&gt;
1214 </para>
1215
1216 </sect2>
1217
1218 <!-- =================================================================== -->
1219
1220 <sect2>
1221 <title>Notes</title>
1222
1223 <itemizedlist>
1224   <listitem>
1225     <para>
1226     The presence of thread support as a whole is controlled by the the
1227     CYGPKG_POSIX_PTHREAD configuration option. Note that disabling
1228     this will also disable many other features of the POSIX package,
1229     since these are intimately bound up with the thread mechanism.
1230     </para>
1231   </listitem>
1232
1233   <listitem>
1234     <para>
1235     The default (non-scheduling) thread attributes are:
1236     </para>
1237     <screen>
1238     detachstate            PTHREAD&lowbar;CREATE&lowbar;JOINABLE
1239     stackaddr              unset
1240     stacksize              unset
1241     </screen>
1242   </listitem>
1243
1244   <listitem>
1245     <para>
1246       Dynamic thread stack allocation is only provided if there is an
1247       implementation of
1248       <emphasis>malloc()</emphasis> configured (i.e. a package
1249       implements the
1250       CYGINT&lowbar;MEMALLOC&lowbar;MALLOC&lowbar;ALLOCATORS
1251       interface). If there is no malloc() available, then the thread
1252       creator must supply a stack. If only a stack address is supplied
1253       then the stack is assumed to be PTHREAD&lowbar;STACK&lowbar;MIN
1254       bytes long. This size is seldom useful for any but the most
1255       trivial of threads.  If a different sized stack is used, both
1256       the stack address and stack size must be supplied.
1257     </para>
1258   </listitem>
1259
1260   <listitem>
1261     <para>
1262       The value of PTHREAD&lowbar;THREADS&lowbar;MAX is supplied by
1263       the CYGNUM&lowbar;POSIX&lowbar;PTHREAD&lowbar;THREADS&lowbar;MAX
1264       option. This defines the maximum number of threads allowed. The
1265       POSIX standard requires this value to be at least 64, and this
1266       is the default value set.
1267     </para>
1268   </listitem>
1269
1270   <listitem>
1271     <para>
1272     When the POSIX package is installed, the thread that calls
1273     <emphasis>main()</emphasis> is initialized as a POSIX thread. The
1274     priority of that thread is controlled by the
1275     CYGNUM&lowbar;POSIX&lowbar;MAIN&lowbar;DEFAULT&lowbar;PRIORITY option.
1276     </para>
1277   </listitem>
1278 </itemizedlist>
1279
1280 </sect2>
1281 </sect1>
1282
1283 <!-- }}} -->
1284 <!-- {{{ Thread-Specific Data -->
1285
1286 <sect1 id="posix-thread-specific-data">
1287 <title>Thread-Specific Data &lsqb;POSIX Section 17&rsqb;</title>
1288
1289 <!-- =================================================================== -->
1290
1291 <sect2>
1292 <title>Functions Implemented</title>
1293
1294 <screen>
1295 int pthread&lowbar;key&lowbar;create(pthread&lowbar;key&lowbar;t &ast;key,
1296                        void (&ast;destructor)(void &ast;));
1297 int pthread&lowbar;setspecific(pthread&lowbar;key&lowbar;t key, const void &ast;pointer);
1298 void &ast;pthread&lowbar;getspecific(pthread&lowbar;key&lowbar;t key);
1299 int pthread&lowbar;key&lowbar;delete(pthread&lowbar;key&lowbar;t key);
1300 </screen>
1301
1302 </sect2>
1303
1304 <!-- =================================================================== -->
1305
1306 <sect2>
1307 <title>Functions Omitted</title>
1308 <para>
1309 &lt;none&gt;
1310 </para>
1311 </sect2>
1312
1313 <!-- =================================================================== -->
1314
1315 <sect2>
1316 <title>Notes</title>
1317
1318 <itemizedlist>
1319   <listitem>
1320     <para>
1321     The value of PTHREAD&lowbar;DESTRUCTOR&lowbar;ITERATIONS is
1322     provided by the
1323     CYGNUM&lowbar;POSIX&lowbar;PTHREAD&lowbar;DESTRUCTOR&lowbar;ITERATIONS
1324     option. This controls the number of times that a key destructor
1325     will be called while the data item remains non-NULL.
1326     </para>
1327   </listitem>
1328
1329   <listitem>
1330     <para>
1331     The value of PTHREAD&lowbar;KEYS&lowbar;MAX is provided
1332     by the CYGNUM&lowbar;POSIX&lowbar;PTHREAD&lowbar;KEYS&lowbar;MAX
1333     option. This defines the maximum number of per-thread data items
1334     supported. The POSIX standard calls for this to be a minimum of
1335     128, which is rather large for an embedded system. The default
1336     value for this option is set to 128 for compatibility but it
1337     should be reduced to a more usable value.
1338     </para>
1339   </listitem>
1340 </itemizedlist>
1341
1342 </sect2>
1343 </sect1>
1344
1345 <!-- }}} -->
1346 <!-- {{{ Thread Cancellation -->
1347
1348 <sect1 id="posix-thread-cancellation">
1349 <title>Thread Cancellation &lsqb;POSIX Section 18&rsqb;</title>
1350
1351 <!-- =================================================================== -->
1352
1353 <sect2>
1354 <title>Functions Implemented</title>
1355
1356 <screen>
1357 int pthread&lowbar;cancel(pthread&lowbar;t thread);
1358 int pthread&lowbar;setcancelstate(int state, int &ast;oldstate);
1359 int pthread&lowbar;setcanceltype(int type, int &ast;oldtype);
1360 void pthread&lowbar;testcancel(void);
1361 void pthread&lowbar;cleanup&lowbar;push( void (&ast;routine)(void &ast;),
1362                            void &ast;arg);
1363 void pthread&lowbar;cleanup&lowbar;pop( int execute);
1364 </screen>
1365 </sect2>
1366
1367
1368 <!-- =================================================================== -->
1369
1370 <sect2>
1371 <title>Functions Omitted</title>
1372 <para>
1373 &lt;none&gt;
1374 </para>
1375 </sect2>
1376
1377 <!-- =================================================================== -->
1378
1379 <sect2>
1380 <title>Notes</title>
1381 <para>
1382 Asynchronous cancellation is only partially implemented.  In
1383 particular, cancellation may occur in unexpected places in some
1384 functions. It is strongly recommended that only synchronous
1385 cancellation be used.
1386 </para>
1387 </sect2>
1388 </sect1>
1389
1390 <!-- }}} -->
1391 <!-- {{{ Non-POSIX Functions -->
1392
1393 <sect1 id="posix-non-posix-functions">
1394 <title>Non-POSIX Functions</title>
1395
1396 <para>
1397 In addition to the standard POSIX functions defined above, the
1398 following non-POSIX functions are defined in the FILEIO package.
1399 </para>
1400
1401 <!-- =================================================================== -->
1402
1403 <sect2>
1404 <title>General I&sol;O Functions</title>
1405 <screen>
1406 int ioctl( int fd, CYG&lowbar;ADDRWORD com, CYG&lowbar;ADDRWORD data );
1407 int select( int nfd, fd&lowbar;set &ast;in, fd&lowbar;set &ast;out, fd&lowbar;set &ast;ex, struct timeval &ast;tv);
1408 </screen>
1409 </sect2>
1410
1411
1412 <!-- =================================================================== -->
1413
1414 <sect2>
1415 <title>Socket Functions</title>
1416 <screen>
1417 int socket( int domain, int type, int protocol);
1418 int bind( int s, const struct sockaddr &ast;sa, unsigned int len);
1419 int listen( int s, int len);
1420 int accept( int s, struct sockaddr &ast;sa, socklen&lowbar;t &ast;addrlen);
1421 int connect( int s, const struct sockaddr &ast;sa, socklen&lowbar;t len);
1422 int getpeername( int s, struct sockaddr &ast;sa, socklen&lowbar;t &ast;len);
1423 int getsockname( int s, struct sockaddr &ast;sa, socklen&lowbar;t &ast;len);
1424 int setsockopt( int s, int level, int optname, const void &ast;optval,
1425                 socklen&lowbar;t optlen);
1426 int getsockopt( int s, int level, int optname, void &ast;optval,
1427                 socklen&lowbar;t &ast;optlen);
1428 ssize&lowbar;t recvmsg( int s, struct msghdr &ast;msg, int flags);
1429 ssize&lowbar;t recvfrom( int s, void &ast;buf, size&lowbar;t len, int flags,
1430                   struct sockaddr &ast;from, socklen&lowbar;t &ast;fromlen);
1431 ssize&lowbar;t recv( int s, void &ast;buf, size&lowbar;t len, int flags);
1432 ssize&lowbar;t sendmsg( int s, const struct msghdr &ast;msg, int flags);
1433 ssize&lowbar;t sendto( int s, const void &ast;buf, size&lowbar;t len, int flags,
1434                 const struct sockaddr &ast;to, socklen&lowbar;t tolen);
1435 ssize&lowbar;t send( int s, const void &ast;buf, size&lowbar;t len, int flags);
1436 int shutdown( int s, int how);
1437 </screen>
1438 </sect2>
1439
1440 <!-- =================================================================== -->
1441
1442 <sect2>
1443 <title>Notes</title>
1444 <itemizedlist>
1445   <listitem>
1446    <para>
1447    The precise behaviour of these functions depends mainly on the
1448    functionality of the underlying filesystem or network stack to
1449    which they are applied.
1450    </para>
1451   </listitem>
1452 </itemizedlist>
1453 </sect2>
1454 </sect1>
1455
1456 <!-- }}} -->
1457
1458 </chapter>
1459
1460 <!-- {{{ Bibliography -->
1461
1462 <bibliography id="posix-references-and-bibliography">
1463 <title>References and Bibliography</title>
1464
1465     <bibliomixed>
1466       <bibliomisc>&lsqb;Lewine&rsqb;</bibliomisc>
1467       <author>
1468         <firstname>Donald</firstname>
1469         <othername>A.</othername>
1470         <surname>Lweine</surname>
1471       </author>
1472       <title>Posix Programmer&rsquo;s Guide: Writing Portable Unix
1473         Programs With the POSIX.1 Standard O&rsquo;Reilly &amp;
1474         Associates; ISBN: 0937175730.</title></bibliomixed>
1475
1476     <bibliomixed>
1477       <bibliomisc>&lsqb;Lewis1&rsqb;</bibliomisc>
1478       <author>
1479         <firstname>Bil</firstname>
1480         <surname>Lewis</surname>
1481       </author>
1482       <author>
1483         <firstname>Daniel</firstname>
1484         <othername>J.</othername>
1485         <surname>Berg</surname>
1486       </author>
1487       <title>Threads Primer: A Guide to Multithreaded Programming</title>
1488       <publishername>Prentice Hall</publishername>
1489       <isbn>ISBN: 013443698</isbn>
1490     </bibliomixed>
1491
1492     <bibliomixed>
1493       <bibliomisc>&lsqb;Lewis2&rsqb;</bibliomisc>
1494       <author>
1495         <firstname>Bil</firstname>
1496         <surname>Lewis</surname>
1497       </author>
1498       <author>
1499         <firstname>Daniel</firstname>
1500         <othername>J.</othername>
1501         <surname>Berg</surname>
1502       </author>
1503       <title>Multithreaded Programming With Pthreads</title>
1504       <publisher>
1505         <publishername>Prentice Hall Computer Books</publishername>
1506       </publisher>
1507       <isbn>ISBN: 0136807291</isbn>
1508     </bibliomixed>
1509
1510     <bibliomixed>
1511       <bibliomisc>&lsqb;Nichols&rsqb;</bibliomisc>
1512       <author>
1513         <firstname>Bradford</firstname>
1514         <surname>Nichols</surname>
1515       </author>
1516       <author>
1517         <firstname>Dick</firstname>
1518         <surname>Buttlar</surname>
1519       </author>
1520       <author>
1521         <firstname>Jacqueline</firstname>
1522         <othername>Proulx</othername>
1523         <surname>Farrell</surname>
1524       </author>
1525       <title>Pthreads Programming: A POSIX Standard for Better
1526         Multiprocessing (O&rsquo;Reilly Nutshell)</title>
1527       <publisher><publishername>O&rsquo;Reilly &amp; Associates</publishername>
1528       </publisher>
1529       <isbn>ISBN: 1565921151</isbn>
1530     </bibliomixed>
1531
1532     <bibliomixed>
1533       <bibliomisc>&lsqb;Norton&rsqb;</bibliomisc>
1534       <author>
1535         <firstname>Scott</firstname>
1536         <othername>J.</othername>
1537         <surname>Norton</surname>
1538       </author>
1539       <author>
1540         <firstname>Mark</firstname>
1541         <othername>D.</othername>
1542         <surname>Depasquale</surname>
1543       </author>
1544       <title>Thread Time: The MultiThreaded Programming Guide</title>
1545       <publisher><publishername>Prentice Hall</publishername>
1546       </publisher>
1547       <isbn>ISBN: 0131900676</isbn></bibliomixed>
1548
1549
1550     <bibliomixed>
1551       <bibliomisc>&lsqb;POSIX&rsqb;</bibliomisc>
1552       <title>Portable Operating System Interface(POSIX) -
1553 Part 1: System Application Programming Interface (API)&lsqb;C
1554 Language&rsqb;</title>
1555       <corpauthor>ISO&sol;IEC 9945-1:1996, IEEE</corpauthor></bibliomixed>
1556
1557     <bibliomixed>
1558       <bibliomisc>&lsqb;SUS2&rsqb;</bibliomisc>
1559       <title>Open Group; Single Unix Specification, Version 2</title>
1560       <bibliomisc><ulink
1561       url="http://www.opengroup.org/public/pubs/online/7908799/index.html">http://www.opengroup.org/public/pubs/online/7908799/index.html</ulink></bibliomisc>
1562     </bibliomixed>
1563
1564   </bibliography>
1565
1566 <!-- }}} -->
1567
1568 </part>