3 <!-- =============================================================== -->
7 <!-- POSIX Compatibility -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
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 <!-- =============================================================== -->
23 <!-- ####COPYRIGHTEND#### -->
24 <!-- =============================================================== -->
25 <!-- #####DESCRIPTIONBEGIN#### -->
27 <!-- ####DESCRIPTIONEND#### -->
28 <!-- =============================================================== -->
32 <part id="posix-compatibility">
33 <title>eCos POSIX compatibility layer</title>
35 <chapter id="posix-standard-support">
36 <title>POSIX Standard Support</title>
41 eCos contains support for the POSIX Specification (ISO/IEC
42 9945-1)[POSIX].
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/O. The two
49 packages may be used together or separately, depending on
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.
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 [POSIX]. Online, the Open Group Single Unix
65 Specification [SUS2] 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 [Lewine] covers the process, signal, file and I/O
70 functions, while [Lewis1], [Lewis2],
71 [Nichols] and [Norton] 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
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.
83 Omitted functions marked with “// TBA”
84 are potential candidates for later implementation.
88 <!-- {{{ Process Primitives -->
90 <sect1 id="posix-process-primitives">
91 <title>Process Primitives [POSIX Section 3]</title>
93 <!-- =================================================================== -->
96 <title>Functions Implemented</title>
99 int kill(pid_t pid, int sig);
100 int pthread_kill(pthread_t thread, int sig);
101 int sigaction(int sig, const struct sigaction *act,
102 struct sigaction *oact);
103 int sigqueue(pid_t pid, int sig, const union sigval value);
104 int sigprocmask(int how, const sigset_t *set,
105 sigset_t *oset);
106 int pthread_sigmask(int how, const sigset_t *set,
107 sigset_t *oset);
108 int sigpending(sigset_t *set);
109 int sigsuspend(const sigset_t *set);
110 int sigwait(const sigset_t *set, int *sig);
111 int sigwaitinfo(const sigset_t *set, siginfo_t *info);
112 int sigtimedwait(const sigset_t *set, siginfo_t *info,
113 const struct timespec *timeout);
114 int sigemptyset(sigset_t *set);
115 int sigfillset(sigset_t *set);
116 int sigaddset(sigset_t *set, int signo);
117 int sigdelset(sigset_t *set, int signo);
118 int sigismember(const sigset_t *set, int signo);
119 unsigned int alarm( unsigned int seconds );
121 unsigned int sleep( unsigned int seconds );
125 <!-- =================================================================== -->
128 <title>Functions Omitted</title>
131 pid_t fork(void);
132 int execl( const char *path, const char *arg, ... );
133 int execv( const char *path, char *const argv[] );
134 int execle( const char *path, const char *arg, ... );
135 int execve( const char *path, char *const argv[],
136 char *const envp[] );
137 int execlp( const char *path, const char *arg, ... );
138 int execvp( const char *path, char *const argv[] );
139 int pthread_atfork( void(*prepare)(void),
140 void (*parent)(void),
141 void (*child)() );
142 pid_t wait( int *stat_loc );
143 pid_t waitpid( pid_t pid, int *stat_loc,
145 void _exit( int status );
149 <!-- =================================================================== -->
156 Signal handling may be enabled or disabled with the
157 CYGPKG_POSIX_SIGNALS option. Since signals are used
158 by other POSIX components, such as timers, disabling signals will
159 disable those components too.
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.
174 The <emphasis>SIGEV_THREAD</emphasis> notification type is
175 not currently implemented.
181 Job Control and Memory Protection signals are
188 An extra implementation defined
189 <emphasis>si_code</emphasis> value,
190 <emphasis>SI_EXCEPT</emphasis>, is defined to
191 distinguish hardware generated exceptions from
198 Extra signals are defined:
199 _SIGTRAP_,_SIGIOT_,
200 _SIGEMT_, and _SIGSYS_. These are
201 largely to maintain compatibility with the signal numbers used by
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.
222 <!-- {{{ Process Environment -->
224 <sect1 id="posix-process-environment">
225 <title>Process Environment [POSIX Section 4]</title>
227 <!-- =================================================================== -->
230 <title>Functions Implemented</title>
233 int uname( struct utsname *name );
234 time_t time( time_t *tloc );
235 char *getenv( const char *name );
236 int isatty( int fd );
237 long sysconf( int name );
241 <!-- =================================================================== -->
244 <title>Functions Omitted</title>
246 pid_t getpid( void );
247 pid_t getppid( void );
248 uid_t getuid( void );
249 uid_t geteuid( void );
250 gid_t getgid( void );
251 gid_t getegid( void );
252 int setuid( uid_t uid );
253 int setgid( gid_t gid );
254 int getgroups( int gidsetsize, gid_t grouplist[] );
255 char *getlogin( void );
256 int getlogin_r( char *name, size_t namesize );
257 pid_t getpgrp( void );
258 pid_t setsid( void );
259 int setpgid( pid_t pid, pid_t pgid );
260 char *ctermid( char *s);
261 char *ttyname( int fd ); // TBA
262 int ttyname_r( int fd, char *name, size_t namesize); // TBA
263 clock_t times( struct tms *buffer ); // TBA
267 <!-- =================================================================== -->
273 <para>The fields of the <emphasis>utsname</emphasis>
274 structure are initialized as follows:
276 sysname “eCos”
277 nodename “” (gethostname() is currently not available)
279 release Major version number of the kernel
280 version Minor version number of the kernel
281 machine “” (Requires some config tool changes)
285 The sizes of these strings are defined by
286 CYG_POSIX_UTSNAME_LENGTH and
287 CYG_POSIX_UTSNAME_NODENAME_LENGTH. The
288 latter defaults to the value of the former, but may also
289 be set independently to accommodate a longer node name.
295 The <emphasis>time()</emphasis> function is currently
296 implemented in the C library.
301 <para>A set of environment strings may be defined at configuration
302 time with the CYGDAT_LIBC_DEFAULT_ENVIRONMENT
303 option. The application may also define an environment by direct
304 assignment to the <emphasis role="strong">environ</emphasis>
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
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><limits.h></filename>,
334 <!-- {{{ Files and Directories -->
336 <sect1 id="posix-files-and-directories">
337 <title>Files and Directories [POSIX Section 5]</title>
339 <!-- =================================================================== -->
342 <title>Functions Implemented</title>
345 DIR *opendir( const char *dirname );
346 struct dirent *readdir( DIR *dirp );
347 int readdir_r( DIR *dirp, struct dirent *entry,
348 struct dirent **result );
349 void rewinddir( DIR *dirp );
350 int closedir( DIR *dirp );
351 int chdir( const char *path );
352 char *getcwd( char *buf, size_t size );
353 int open( const char * path , int oflag , ... );
354 int creat( const char * path, mode_t mode );
355 int link( const char *existing, const char *new );
356 int mkdir( const char *path, mode_t mode );
357 int unlink( const char *path );
358 int rmdir( const char *path );
359 int rename( const char *old, const char *new );
360 int stat( const char *path, struct stat *buf );
361 int fstat( int fd, struct stat *buf );
362 int access( const char *path, int amode );
363 long pathconf(const char *path, int name);
364 long fpathconf(int fd, int name);
368 <!-- =================================================================== -->
371 <title>Functions Omitted</title>
374 mode_t umask( mode_t cmask );
375 int mkfifo( const char *path, mode_t mode );
376 int chmod( const char *path, mode_t mode ); // TBA
377 int fchmod( int fd, mode_t mode ); // TBA
378 int chown( const char *path, uid_t owner, gid_t group );
379 int utime( const char *path, const struct utimbuf *times ); // TBA
380 int ftruncate( int fd, off_t length ); // TBA
384 <!-- =================================================================== -->
392 If a call to <function>open()</function> or <function>creat()</function> supplies
393 the third _mode_ parameter, it will
394 currently be ignored.
399 Most of the functionality of these functions depends on
400 the underlying filesystem.
405 Currently<emphasis> access()</emphasis> only checks the
406 <emphasis>F_OK</emphasis> mode explicitly, the others are
407 all assumed to be true by default.
412 The maximum number of open files allowed is supplied by
413 the CYGNUM_FILEIO_NFILE option. The maximum number
414 of file descriptors is supplied by the CYGNUM_FILEIO_NFD
423 <!-- {{{ Input and Output -->
425 <sect1 id="posix-input-and-output">
426 <title>Input and Output [POSIX Section 6]</title>
428 <!-- =================================================================== -->
431 <title>Functions Implemented</title>
435 int dup2( int fd, int fd2 );
437 ssize_t read(int fd, void *buf, size_t nbyte);
438 ssize_t write(int fd, const void *buf, size_t nbyte);
439 int fcntl( int fd, int cmd, ... );
440 off_t lseek(int fd, off_t offset, int whence);
442 int fdatasync( int fd );</screen>
445 <!-- =================================================================== -->
448 <title>Functions Omitted</title>
450 int pipe( int fildes[2] );
451 int aio_read( struct aiocb *aiocbp ); // TBA
452 int aio_write( struct aiocb *aiocbp ); // TBA
453 int lio_listio( int mode, struct aiocb *const list[],
454 int nent, struct sigevent *sig); // TBA
455 int aio_error( struct aiocb *aiocbp ); // TBA
456 int aio_return( struct aiocb *aiocbp ); // TBA
457 int aio_cancel( int fd, struct aiocb *aiocbp ); // TBA
458 int aio_suspend( const struct aiocb *const list[],
459 int nent, const struct timespec *timeout ); // TBA
460 int aio_fsync( int op, struct aiocb *aiocbp );
465 <!-- =================================================================== -->
472 Only the <emphasis>F_DUPFD</emphasis> command
473 of <emphasis>fcntl()</emphasis> is currently implemented.
478 Most of the functionality of these functions depends on
479 the underlying filesystem.
487 <!-- {{{ Device and Class Specific Functions -->
489 <sect1 id="posix-device-and-class-specific-functions">
490 <title>Device and Class Specific Functions [POSIX Section 7]</title>
492 <!-- =================================================================== -->
495 <title>Functions Implemented</title>
497 speed_t cfgetospeed( const struct termios *termios_p );
498 int cfsetospeed( struct termios *termios_p, speed_t speed );
499 speed_t cfgetispeed( const struct termios *termios_p );
500 int cfsetispeed( struct termios *termios_p, speed_t speed );
501 int tcgetattr( int fd, struct termios *termios_p );
502 int tcsetattr( int fd, int optional_actions,
503 const struct termios *termios_p );
504 int tcsendbreak( int fd, int duration );
505 int tcdrain( int fd );
506 int tcflush( int fd, int queue_selector );
507 int tcsendbreak( int fd, int action );
511 <!-- =================================================================== -->
514 <title>Functions Omitted</title>
517 pid_t tcgetpgrp( int fd );
518 int tcsetpgrp( int fd, pid_t pgrp );</screen>
521 <!-- =================================================================== -->
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 “tty” devices, not the “serial”
532 devices. None of the functionality relevant to job
533 control, controlling terminals and sessions is
539 Only <emphasis>MIN</emphasis> = 0 and
540 <emphasis>TIME</emphasis> = 0 functionality is
546 Hardware flow control is supported if the underlying
547 device driver and serial port support it.
552 Support for break, framing and parity errors depends on
553 the functionality of the hardware and device driver.
561 <!-- {{{ C Language Services -->
563 <sect1 id="posix-C-language-services">
564 <title>C Language Services [POSIX Section 8]</title>
566 <!-- =================================================================== -->
569 <title>Functions Implemented</title>
571 char *setlocale( int category, const char *locale );
572 int fileno( FILE *stream );
573 FILE *fdopen( int fd, const char *type );
574 int getc_unlocked( FILE *stream);
575 int getchar_unlocked( void );
576 int putc_unlocked( FILE *stream );
577 int putchar_unlocked( void );
578 char *strtok_r( char *s, const char *sep,
579 char **lasts );
580 char *asctime_r( const struct tm *tm, char *buf );
581 char *ctime_r( const time_t *clock, char *buf );
582 struct tm *gmtime_r( const time_t *clock,
583 struct tm *result );
584 struct tm *localtime_r( const time_t *clock,
585 struct tm *result );
586 int rand_r( unsigned int *seed );
590 <!-- =================================================================== -->
593 <title>Functions Omitted</title>
595 void flockfile( FILE *file );
596 int ftrylockfile( FILE *file );
597 void funlockfile( FILE *file );
598 int sigsetjmp( sigjmp_buf env, int savemask ); // TBA
599 void siglongjmp( sigjmp_buf env, int val ); // TBA
600 void tzset(void); // TBA
604 <!-- =================================================================== -->
611 <emphasis>setlocale()</emphasis> is implemented in the C
612 library Internationalization package.
617 Functions <emphasis>fileno()</emphasis> and
618 <emphasis>fdopen()</emphasis> are implemented in the C
619 library STDIO package.
624 Functions <emphasis>getc_unlocked()</emphasis>,
625 <emphasis>getchar_unlocked()</emphasis>,
626 <emphasis>putc_unlocked()</emphasis> and
627 <emphasis>putchar_unlocked()</emphasis> are defined
628 but are currently identical to their non-unlocked
634 <emphasis>strtok_r()</emphasis>, <emphasis>asctime_r()</emphasis>,
635 <emphasis>ctime_r()</emphasis>, <emphasis>gmtime_r()</emphasis>,
636 <emphasis>localtime_r()</emphasis> and
637 <emphasis>rand_r()</emphasis> are all currently in
638 the C library, alongside their non-reentrant versions.
646 <!-- {{{ System Databases -->
648 <sect1 id="posix-system-databases">
649 <title>System Databases [POSIX Section 9]</title>
651 <!-- =================================================================== -->
654 <title>Functions Implemented</title>
662 <!-- =================================================================== -->
665 <title>Functions Omitted</title>
668 struct group *getgrgid( gid_t gid );
669 int getgrgid( gid_t gid, struct group *grp, char *buffer,
670 size_t bufsize, struct group **result );
671 struct group *getgrname( const char *name );
672 int getgrname_r( const char *name, struct group *grp,
673 char *buffer, size_t bufsize, struct group **result );
674 struct passwd *getpwuid( uid_t uid );
675 int getpwuid_r( uid_t uid, struct passwd *pwd,
676 char *buffer, size_t bufsize, struct passwd **result );
677 struct passwd *getpwnam( const char *name );
678 int getpwnam_r( const char *name, struct passwd *pwd,
679 char *buffer, size_t bufsize, struct passwd **result );
683 <!-- =================================================================== -->
690 None of the functions in this section are implemented.
698 <!-- {{{ Data Interchange Format -->
700 <sect1 id="posix-data-interchange-format">
701 <title>Data Interchange Format [POSIX Section 10]</title>
704 This section details <emphasis>tar</emphasis> and
705 <emphasis>cpio</emphasis> formats. Neither of these is supported by
711 <!-- {{{ Synchronization -->
713 <sect1 id="posix-synchronization">
714 <title>Synchronization [POSIX Section 11]</title>
717 <!-- =================================================================== -->
720 <title>Functions Implemented</title>
723 int sem_init(sem_t *sem, int pshared, unsigned int value);
724 int sem_destroy(sem_t *sem);
725 int sem_wait(sem_t *sem);
726 int sem_trywait(sem_t *sem);
727 int sem_post(sem_t *sem);
728 int sem_getvalue(sem_t *sem, int *sval);
729 int pthread_mutexattr_init( pthread_mutexattr_t *attr);
730 int pthread_mutexattr_destroy( pthread_mutexattr_t *attr);
731 int pthread_mutex_init(pthread_mutex_t *mutex,
732 const pthread_mutexattr_t *mutex_attr);
733 int pthread_mutex_destroy(pthread_mutex_t *mutex);
734 int pthread_mutex_lock(pthread_mutex_t *mutex);
735 int pthread_mutex_trylock(pthread_mutex_t *mutex);
736 int pthread_mutex_unlock(pthread_mutex_t *mutex);
737 int pthread_condattr_init(pthread_condattr_t *attr);
738 int pthread_condattr_destroy(pthread_condattr_t *attr);
739 int pthread_cond_init(pthread_cond_t *cond,
740 const pthread_condattr_t *attr);
741 int pthread_cond_destroy(pthread_cond_t *cond);
742 int pthread_cond_signal(pthread_cond_t *cond);
743 int pthread_cond_broadcast(pthread_cond_t *cond);
744 int pthread_cond_wait(pthread_cond_t *cond,
745 pthread_mutex_t *mutex);
746 int pthread_cond_timedwait(pthread_cond_t *cond,
747 pthread_mutex_t *mutex,
748 const struct timespec *abstime);
752 <!-- =================================================================== -->
755 <title>Functions Omitted</title>
758 sem_t *sem_open(const char *name, int oflag, ...); // TBA
759 int sem_close(sem_t *sem); // TBA
760 int sem_unlink(const char *name); // TBA
761 int pthread_mutexattr_getpshared( const pthread_mutexattr_t *attr,
763 int pthread_mutexattr_setpshared( const pthread_mutexattr_t *attr,
765 int pthread_condattr_getpshared( const pthread_condattr_t *attr,
767 int pthread_condattr_setpshared( const pthread_condattr_t *attr,
768 int pshared);</screen>
771 <!-- =================================================================== -->
778 The presence of semaphores is controlled by the
779 CYGPKG_POSIX_SEMAPHORES option. This in turn
780 causes the _POSIX_SEMAPHORES feature test
781 macro to be defined and the semaphore API to be made
788 The <emphasis role="strong">pshared</emphasis> argument to
789 <emphasis>sem_init()</emphasis> is not implemented,
790 its value is ignored.
796 Functions <emphasis>sem_open()</emphasis>,
797 <emphasis>sem_close()</emphasis> and
798 <emphasis>sem_unlink()</emphasis> are present but
799 always return an error (ENOSYS).
805 The exact priority inversion protocols supported may be
807 _POSIX_THREAD_PRIO_INHERIT and
808 _POSIX_THREAD_PRIO_PROTECT
809 configuration options.
815 {_POSIX_THREAD_PROCESS_SHARED} is
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_mutexattr_getpshared()</emphasis>,
821 <emphasis>pthread_mutexattr_setpshared()</emphasis>,
822 <emphasis>pthread_condattr_getpshared()</emphasis> and
823 <emphasis>pthread_condattr_setpshared()</emphasis>.
829 Condition variables do not become bound to a particular
831 <emphasis>pthread_cond_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
846 <!-- {{{ Memory Management -->
848 <sect1 id="posix-memory-management">
849 <title>Memory Management [POSIX Section 12]</title>
851 <!-- =================================================================== -->
854 <title>Functions Implemented</title>
861 <!-- =================================================================== -->
864 <title>Functions Omitted</title>
867 int mlockall( int flags );
868 int munlockall( void );
869 int mlock( const void *addr, size_t len );
870 int munlock( const void *addr, size_t len );
871 void mmap( void *addr, size_t len, int prot, int flags,
872 int fd, off_t off );
873 int munmap( void *addr, size_t len );
874 int mprotect( const void *addr, size_t len, int prot );
875 int msync( void *addr, size_t len, int flags );
876 int shm_open( const char *name, int oflag, mode_t mode );
877 int shm_unlink( const char *name );
881 <!-- =================================================================== -->
886 None of these functions are currently provided. Some may
887 be implemented in a restricted form in the future.
894 <!-- {{{ Execution Scheduling -->
896 <sect1 id="posix-execution-scheduling">
897 <title>Execution Scheduling [POSIX Section 13]</title>
899 <!-- =================================================================== -->
902 <title>Functions Implemented</title>
905 int sched_yield(void);
906 int sched_get_priority_max(int policy);
907 int sched_get_priority_min(int policy);
908 int sched_rr_get_interval(pid_t pid, struct timespec *t);
909 int pthread_attr_setscope(pthread_attr_t *attr, int scope);
910 int pthread_attr_getscope(const pthread_attr_t *attr, int *scope);
911 int pthread_attr_setinheritsched(pthread_attr_t *attr, int inherit);
912 int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inherit);
913 int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
914 int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy);
915 int pthread_attr_setschedparam( pthread_attr_t *attr, const struct sched_param *param);
916 int pthread_attr_getschedparam( const pthread_attr_t *attr,
917 struct sched_param *param);
918 int pthread_setschedparam(pthread_t thread, int policy,
919 const struct sched_param *param);
920 int pthread_getschedparam(pthread_t thread, int *policy,
921 struct sched_param *param);
922 int pthread_mutexattr_setprotocol( pthread_mutexattr_t *attr,
924 int pthread_mutexattr_getprotocol( pthread_mutexattr_t *attr,
926 int pthread_mutexattr_setprioceiling( pthread_mutexattr_t *attr,
928 int pthread_mutexattr_getprioceiling( pthread_mutexattr_t *attr,
929 int *prioceiling);
930 int pthread_mutex_setprioceiling( pthread_mutex_t *mutex,
932 int *old_ceiling);
933 int pthread_mutex_getprioceiling( pthread_mutex_t *mutex,
934 int *prioceiling);
938 <!-- =================================================================== -->
941 <title>Functions Omitted</title>
944 int sched_setparam(pid_t pid, const struct sched_param *param);
945 int sched_getparam(pid_t pid, struct sched_param *param);
946 int sched_setscheduler(pid_t pid, int policy,
947 const struct sched_param *param);
948 int sched_getscheduler(pid_t pid);
952 <!-- =================================================================== -->
959 The functions <emphasis>sched_setparam()</emphasis>,
960 <emphasis>sched_getparam()</emphasis>,
961 <emphasis>sched_setscheduler()</emphasis> and
962 <emphasis>sched_getscheduler()</emphasis> are present
963 but always return an error.
968 The scheduler policy <emphasis>SCHED_OTHER</emphasis> is
969 equivalent to <emphasis>SCHED_RR</emphasis>.
974 Only <emphasis>PTHREAD_SCOPE_SYSTEM</emphasis>
976 <emphasis role="strong">contentionscope</emphasis>
982 The default thread scheduling attributes are:
984 contentionscope PTHREAD_SCOPE_SYSTEM
985 inheritsched PTHREAD_INHERIT_SCHED
986 schedpolicy SCHED_OTHER
993 Mutex priority inversion protection is controlled by a
994 number of kernel configuration options.
995 If CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_INHERIT
997 {_POSIX_THREAD_PRIO_INHERIT}
998 will be defined and PTHREAD_PRIO_INHERIT may
999 be set as the protocol in a
1000 <emphasis>pthread_mutexattr_t</emphasis>
1002 If CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_CEILING
1004 {_POSIX_THREAD_PRIO_PROTECT}
1005 will be defined and PTHREAD_PRIO_PROTECT may
1006 be set as the protocol in a
1007 <emphasis>pthread_mutexattr_t</emphasis> object.
1012 The default attribute values set by
1013 <emphasis>pthread_mutexattr_init()</emphasis>
1014 is to set the protocol attribute to
1015 PTHREAD_PRIO_NONE and the prioceiling
1025 <!-- {{{ Clocks and Timers -->
1027 <sect1 id="posix-clocks-and-timers">
1028 <title>Clocks and Timers [POSIX Section 14]</title>
1030 <!-- =================================================================== -->
1033 <title>Functions Implemented</title>
1036 int clock_settime( clockid_t clock_id,
1037 const struct timespec *tp);
1038 int clock_gettime( clockid_t clock_id, struct timespec *tp);
1039 int clock_getres( clockid_t clock_id, struct timespec *tp);
1040 int timer_create( clockid_t clock_id, struct sigevent *evp,
1041 timer_t *timer_id);
1042 int timer_delete( timer_t timer_id );
1043 int timer_settime( timer_t timerid, int flags,
1044 const struct itimerspec *value,
1045 struct itimerspec *ovalue );
1046 int timer_gettime( timer_t timerid, struct itimerspec *value );
1047 int timer_getoverrun( timer_t timerid );
1048 int nanosleep( const struct timespec *rqtp, struct timespec *rmtp);
1054 <!-- =================================================================== -->
1057 <title>Functions Omitted</title>
1065 <!-- =================================================================== -->
1068 <title>Notes</title>
1073 Currently <emphasis>timer_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.
1082 The option CYGPKG_POSIX_TIMERS allows the timer support to be
1083 enabled or disabled, and causes _POSIX_TIMERS to be defined
1084 appropriately. This will cause other parts of the POSIX system to
1085 have limited functionality.
1095 <!-- {{{ Message Passing -->
1097 <sect1 id="posix-message-passing">
1098 <title>Message Passing [POSIX Section 15]</title>
1100 <!-- =================================================================== -->
1103 <title>Functions Implemented</title>
1106 mqd_t mq_open( const char *name, int oflag, ... );
1107 int mq_close( mqd_t mqdes );
1108 int mq_unlink( const char *name );
1109 int mq_send( mqd_t mqdes, const char *msg_ptr,
1110 size_t msg_len, unsigned int msg_prio );
1111 ssize_t mq_receive( mqd_t mqdes, char *msg_ptr,
1112 size_t msg_len, unsigned int *msg_prio );
1113 int mq_setattr( mqd_t mqdes, const struct mq_attr *mqstat,
1114 struct mq_attr *omqstat );
1115 int mq_getattr( mqd_t mqdes, struct mq_attr *mqstat );
1116 int mq_notify( mqd_t mqdes, const struct sigevent *notification );
1118 <para>From POSIX 1003.1d draft: </para>
1120 int mq_send( mqd_t mqdes, const char *msg_ptr,
1121 size_t msg_len, unsigned int msg_prio,
1122 const struct timespec *abs_timeout );
1123 ssize_t mq_receive( mqd_t mqdes, char *msg_ptr,
1124 size_t msg_len, unsigned int *msg_prio,
1125 const struct timespec *abs_timeout );
1129 <!-- =================================================================== -->
1132 <title>Functions Omitted</title>
1140 <!-- =================================================================== -->
1143 <title>Notes</title>
1148 The presence of message queues is controlled by the
1149 CYGPKG_POSIX_MQUEUES option. Setting this will
1150 cause [_POSIX_MESSAGE_PASSING] to
1151 be defined and the message queue API to be made available.
1157 Message queues are not currently filesystem objects. They live in
1158 their own name and descriptor spaces.
1167 <!-- {{{ Thread Management -->
1169 <sect1 id="posix-thread-management">
1170 <title>Thread Management [POSIX Section 16]</title>
1172 <!-- =================================================================== -->
1175 <title>Functions Implemented</title>
1178 int pthread_attr_init(pthread_attr_t *attr);
1179 int pthread_attr_destroy(pthread_attr_t *attr);
1180 int pthread_attr_setdetachstate(pthread_attr_t *attr,
1182 int pthread_attr_getdetachstate(const pthread_attr_t *attr,
1183 int *detachstate);
1184 int pthread_attr_setstackaddr(pthread_attr_t *attr,
1185 void *stackaddr);
1186 int pthread_attr_getstackaddr(const pthread_attr_t *attr,
1187 void **stackaddr);
1188 int pthread_attr_setstacksize(pthread_attr_t *attr,
1189 size_t stacksize);
1190 int pthread_attr_getstacksize(const pthread_attr_t *attr,
1191 size_t *stacksize);
1192 int pthread_create( pthread_t *thread,
1193 const pthread_attr_t *attr,
1194 void *(*start_routine)(void *),
1196 pthread_t pthread_self( void );
1197 int pthread_equal(pthread_t thread1, pthread_t thread2);
1198 void pthread_exit(void *retval);
1199 int pthread_join(pthread_t thread, void **thread_return);
1200 int pthread_detach(pthread_t thread);
1201 int pthread_once(pthread_once_t *once_control,
1202 void (*init_routine)(void));
1207 <!-- =================================================================== -->
1210 <title>Functions Omitted</title>
1218 <!-- =================================================================== -->
1221 <title>Notes</title>
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.
1235 The default (non-scheduling) thread attributes are:
1238 detachstate PTHREAD_CREATE_JOINABLE
1246 Dynamic thread stack allocation is only provided if there is an
1248 <emphasis>malloc()</emphasis> configured (i.e. a package
1250 CYGINT_MEMALLOC_MALLOC_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_STACK_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.
1262 The value of PTHREAD_THREADS_MAX is supplied by
1263 the CYGNUM_POSIX_PTHREAD_THREADS_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.
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_POSIX_MAIN_DEFAULT_PRIORITY option.
1284 <!-- {{{ Thread-Specific Data -->
1286 <sect1 id="posix-thread-specific-data">
1287 <title>Thread-Specific Data [POSIX Section 17]</title>
1289 <!-- =================================================================== -->
1292 <title>Functions Implemented</title>
1295 int pthread_key_create(pthread_key_t *key,
1296 void (*destructor)(void *));
1297 int pthread_setspecific(pthread_key_t key, const void *pointer);
1298 void *pthread_getspecific(pthread_key_t key);
1299 int pthread_key_delete(pthread_key_t key);
1304 <!-- =================================================================== -->
1307 <title>Functions Omitted</title>
1313 <!-- =================================================================== -->
1316 <title>Notes</title>
1321 The value of PTHREAD_DESTRUCTOR_ITERATIONS is
1323 CYGNUM_POSIX_PTHREAD_DESTRUCTOR_ITERATIONS
1324 option. This controls the number of times that a key destructor
1325 will be called while the data item remains non-NULL.
1331 The value of PTHREAD_KEYS_MAX is provided
1332 by the CYGNUM_POSIX_PTHREAD_KEYS_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.
1346 <!-- {{{ Thread Cancellation -->
1348 <sect1 id="posix-thread-cancellation">
1349 <title>Thread Cancellation [POSIX Section 18]</title>
1351 <!-- =================================================================== -->
1354 <title>Functions Implemented</title>
1357 int pthread_cancel(pthread_t thread);
1358 int pthread_setcancelstate(int state, int *oldstate);
1359 int pthread_setcanceltype(int type, int *oldtype);
1360 void pthread_testcancel(void);
1361 void pthread_cleanup_push( void (*routine)(void *),
1363 void pthread_cleanup_pop( int execute);
1368 <!-- =================================================================== -->
1371 <title>Functions Omitted</title>
1377 <!-- =================================================================== -->
1380 <title>Notes</title>
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.
1391 <!-- {{{ Non-POSIX Functions -->
1393 <sect1 id="posix-non-posix-functions">
1394 <title>Non-POSIX Functions</title>
1397 In addition to the standard POSIX functions defined above, the
1398 following non-POSIX functions are defined in the FILEIO package.
1401 <!-- =================================================================== -->
1404 <title>General I/O Functions</title>
1406 int ioctl( int fd, CYG_ADDRWORD com, CYG_ADDRWORD data );
1407 int select( int nfd, fd_set *in, fd_set *out, fd_set *ex, struct timeval *tv);
1412 <!-- =================================================================== -->
1415 <title>Socket Functions</title>
1417 int socket( int domain, int type, int protocol);
1418 int bind( int s, const struct sockaddr *sa, unsigned int len);
1419 int listen( int s, int len);
1420 int accept( int s, struct sockaddr *sa, socklen_t *addrlen);
1421 int connect( int s, const struct sockaddr *sa, socklen_t len);
1422 int getpeername( int s, struct sockaddr *sa, socklen_t *len);
1423 int getsockname( int s, struct sockaddr *sa, socklen_t *len);
1424 int setsockopt( int s, int level, int optname, const void *optval,
1425 socklen_t optlen);
1426 int getsockopt( int s, int level, int optname, void *optval,
1427 socklen_t *optlen);
1428 ssize_t recvmsg( int s, struct msghdr *msg, int flags);
1429 ssize_t recvfrom( int s, void *buf, size_t len, int flags,
1430 struct sockaddr *from, socklen_t *fromlen);
1431 ssize_t recv( int s, void *buf, size_t len, int flags);
1432 ssize_t sendmsg( int s, const struct msghdr *msg, int flags);
1433 ssize_t sendto( int s, const void *buf, size_t len, int flags,
1434 const struct sockaddr *to, socklen_t tolen);
1435 ssize_t send( int s, const void *buf, size_t len, int flags);
1436 int shutdown( int s, int how);
1440 <!-- =================================================================== -->
1443 <title>Notes</title>
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.
1460 <!-- {{{ Bibliography -->
1462 <bibliography id="posix-references-and-bibliography">
1463 <title>References and Bibliography</title>
1466 <bibliomisc>[Lewine]</bibliomisc>
1468 <firstname>Donald</firstname>
1469 <othername>A.</othername>
1470 <surname>Lweine</surname>
1472 <title>Posix Programmer’s Guide: Writing Portable Unix
1473 Programs With the POSIX.1 Standard O’Reilly &
1474 Associates; ISBN: 0937175730.</title></bibliomixed>
1477 <bibliomisc>[Lewis1]</bibliomisc>
1479 <firstname>Bil</firstname>
1480 <surname>Lewis</surname>
1483 <firstname>Daniel</firstname>
1484 <othername>J.</othername>
1485 <surname>Berg</surname>
1487 <title>Threads Primer: A Guide to Multithreaded Programming</title>
1488 <publishername>Prentice Hall</publishername>
1489 <isbn>ISBN: 013443698</isbn>
1493 <bibliomisc>[Lewis2]</bibliomisc>
1495 <firstname>Bil</firstname>
1496 <surname>Lewis</surname>
1499 <firstname>Daniel</firstname>
1500 <othername>J.</othername>
1501 <surname>Berg</surname>
1503 <title>Multithreaded Programming With Pthreads</title>
1505 <publishername>Prentice Hall Computer Books</publishername>
1507 <isbn>ISBN: 0136807291</isbn>
1511 <bibliomisc>[Nichols]</bibliomisc>
1513 <firstname>Bradford</firstname>
1514 <surname>Nichols</surname>
1517 <firstname>Dick</firstname>
1518 <surname>Buttlar</surname>
1521 <firstname>Jacqueline</firstname>
1522 <othername>Proulx</othername>
1523 <surname>Farrell</surname>
1525 <title>Pthreads Programming: A POSIX Standard for Better
1526 Multiprocessing (O’Reilly Nutshell)</title>
1527 <publisher><publishername>O’Reilly & Associates</publishername>
1529 <isbn>ISBN: 1565921151</isbn>
1533 <bibliomisc>[Norton]</bibliomisc>
1535 <firstname>Scott</firstname>
1536 <othername>J.</othername>
1537 <surname>Norton</surname>
1540 <firstname>Mark</firstname>
1541 <othername>D.</othername>
1542 <surname>Depasquale</surname>
1544 <title>Thread Time: The MultiThreaded Programming Guide</title>
1545 <publisher><publishername>Prentice Hall</publishername>
1547 <isbn>ISBN: 0131900676</isbn></bibliomixed>
1551 <bibliomisc>[POSIX]</bibliomisc>
1552 <title>Portable Operating System Interface(POSIX) -
1553 Part 1: System Application Programming Interface (API)[C
1554 Language]</title>
1555 <corpauthor>ISO/IEC 9945-1:1996, IEEE</corpauthor></bibliomixed>
1558 <bibliomisc>[SUS2]</bibliomisc>
1559 <title>Open Group; Single Unix Specification, Version 2</title>
1561 url="http://www.opengroup.org/public/pubs/online/7908799/index.html">http://www.opengroup.org/public/pubs/online/7908799/index.html</ulink></bibliomisc>