URL
https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk
Subversion Repositories openrisc_me
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [packages/] [compat/] [posix/] [v2_0/] [doc/] [posix.sgml] - Rev 454
Go to most recent revision | Compare with Previous | Blame | View Log
<!-- {{{ Banner -->
<!-- =============================================================== -->
<!-- -->
<!-- posix.sgml -->
<!-- -->
<!-- POSIX Compatibility -->
<!-- -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN#### -->
<!-- -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/) -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission obtained from the copyright holder -->
<!-- =============================================================== -->
<!-- -->
<!-- ####COPYRIGHTEND#### -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN#### -->
<!-- -->
<!-- ####DESCRIPTIONEND#### -->
<!-- =============================================================== -->
<!-- }}} -->
<part id="posix-compatibility">
<title>eCos POSIX compatibility layer</title>
<chapter id="posix-standard-support">
<title>POSIX Standard Support</title>
<!-- {{{ Intro -->
<para>
eCos contains support for the POSIX Specification (ISO/IEC
9945-1)[POSIX].
</para>
<para>
POSIX support is divided between the POSIX and the FILEIO
packages. The POSIX package provides support for threads,
signals, synchronization, timers and message queues. The FILEIO
package provides support for file and device I/O. The two
packages may be used together or separately, depending on
configuration.
</para>
<para>
This document takes a functional approach to the POSIX
library. Support for a function implies that the data types and
definitions necessary to support that function, and the objects
it manipulates, are also defined. Any exceptions to this are
noted, and unless otherwise noted, implemented functions behave
as specified in the POSIX standard.
</para>
<para>
This document only covers the differences between the eCos
implementation and the standard; it does not provide complete
documentation. For full information, see the POSIX standard
[POSIX]. Online, the Open Group Single Unix
Specification [SUS2] provides complete documentation
of a superset of POSIX. If you have access to a Unix system with
POSIX compatibility, then the manual pages for this will be of
use. There are also a number of books available.
[Lewine] covers the process, signal, file and I/O
functions, while [Lewis1], [Lewis2],
[Nichols] and [Norton] cover Pthreads and
related topics (see Bibliography, xref). However, many of these
books are oriented toward using POSIX in non-embedded systems,
so care should be taken in applying them to programming under
eCos.
</para>
<para>
The remainder of this chapter broadly follows the structure
of the POSIX Specification. References to the appropriate
section of the Standard are included.
</para>
<para>
Omitted functions marked with “// TBA”
are potential candidates for later implementation.
</para>
<!-- }}} -->
<!-- {{{ Process Primitives -->
<sect1 id="posix-process-primitives">
<title>Process Primitives [POSIX Section 3]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int kill(pid_t pid, int sig);
int pthread_kill(pthread_t thread, int sig);
int sigaction(int sig, const struct sigaction *act,
struct sigaction *oact);
int sigqueue(pid_t pid, int sig, const union sigval value);
int sigprocmask(int how, const sigset_t *set,
sigset_t *oset);
int pthread_sigmask(int how, const sigset_t *set,
sigset_t *oset);
int sigpending(sigset_t *set);
int sigsuspend(const sigset_t *set);
int sigwait(const sigset_t *set, int *sig);
int sigwaitinfo(const sigset_t *set, siginfo_t *info);
int sigtimedwait(const sigset_t *set, siginfo_t *info,
const struct timespec *timeout);
int sigemptyset(sigset_t *set);
int sigfillset(sigset_t *set);
int sigaddset(sigset_t *set, int signo);
int sigdelset(sigset_t *set, int signo);
int sigismember(const sigset_t *set, int signo);
unsigned int alarm( unsigned int seconds );
int pause( void );
unsigned int sleep( unsigned int seconds );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
pid_t fork(void);
int execl( const char *path, const char *arg, ... );
int execv( const char *path, char *const argv[] );
int execle( const char *path, const char *arg, ... );
int execve( const char *path, char *const argv[],
char *const envp[] );
int execlp( const char *path, const char *arg, ... );
int execvp( const char *path, char *const argv[] );
int pthread_atfork( void(*prepare)(void),
void (*parent)(void),
void (*child)() );
pid_t wait( int *stat_loc );
pid_t waitpid( pid_t pid, int *stat_loc,
int options );
void _exit( int status );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
Signal handling may be enabled or disabled with the
CYGPKG_POSIX_SIGNALS option. Since signals are used
by other POSIX components, such as timers, disabling signals will
disable those components too.
</para>
</listitem>
<listitem>
<para>
<emphasis>kill()</emphasis> and
<emphasis>sigqueue()</emphasis> may only take a
<emphasis role="strong">pid</emphasis> argument of zero,
which maps to the current process.
</para>
</listitem>
<listitem>
<para>
The <emphasis>SIGEV_THREAD</emphasis> notification type is
not currently implemented.
</para>
</listitem>
<listitem>
<para>
Job Control and Memory Protection signals are
not supported.
</para>
</listitem>
<listitem>
<para>
An extra implementation defined
<emphasis>si_code</emphasis> value,
<emphasis>SI_EXCEPT</emphasis>, is defined to
distinguish hardware generated exceptions from
others.
</para>
</listitem>
<listitem>
<para>
Extra signals are defined:
_SIGTRAP_,_SIGIOT_,
_SIGEMT_, and _SIGSYS_. These are
largely to maintain compatibility with the signal numbers used by
GDB.
</para>
</listitem>
<listitem>
<para>
Signal delivery may currently occur at unexpected places in some
API functions. Using <emphasis>longjmp()</emphasis> to transfer
control out of a signal handler may result in the interrupted
function not being able to complete properly. This may result in
later function calls failing or deadlocking.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Process Environment -->
<sect1 id="posix-process-environment">
<title>Process Environment [POSIX Section 4]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int uname( struct utsname *name );
time_t time( time_t *tloc );
char *getenv( const char *name );
int isatty( int fd );
long sysconf( int name );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
pid_t getpid( void );
pid_t getppid( void );
uid_t getuid( void );
uid_t geteuid( void );
gid_t getgid( void );
gid_t getegid( void );
int setuid( uid_t uid );
int setgid( gid_t gid );
int getgroups( int gidsetsize, gid_t grouplist[] );
char *getlogin( void );
int getlogin_r( char *name, size_t namesize );
pid_t getpgrp( void );
pid_t setsid( void );
int setpgid( pid_t pid, pid_t pgid );
char *ctermid( char *s);
char *ttyname( int fd ); // TBA
int ttyname_r( int fd, char *name, size_t namesize); // TBA
clock_t times( struct tms *buffer ); // TBA
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>The fields of the <emphasis>utsname</emphasis>
structure are initialized as follows:
<screen>
sysname “eCos”
nodename “” (gethostname() is currently not available)
release Major version number of the kernel
version Minor version number of the kernel
machine “” (Requires some config tool changes)
</screen>
</para>
<para>
The sizes of these strings are defined by
CYG_POSIX_UTSNAME_LENGTH and
CYG_POSIX_UTSNAME_NODENAME_LENGTH. The
latter defaults to the value of the former, but may also
be set independently to accommodate a longer node name.
</para>
</listitem>
<listitem>
<para>
The <emphasis>time()</emphasis> function is currently
implemented in the C library.
</para>
</listitem>
<listitem>
<para>A set of environment strings may be defined at configuration
time with the CYGDAT_LIBC_DEFAULT_ENVIRONMENT
option. The application may also define an environment by direct
assignment to the <emphasis role="strong">environ</emphasis>
variable.
</para>
</listitem>
<listitem>
<para>
At present <emphasis>isatty()</emphasis> assumes that
any character device is a tty and that all other devices are not
ttys. Since the only kind of device that eCos currently supports
is serial character devices, this is an adequate
distinction.
</para>
</listitem>
<listitem>
<para>
All system variables supported by sysconf will yield a
value. However, those that are irrelevant to eCos will
either return the default minimum defined in
<filename><limits.h></filename>,
or zero.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Files and Directories -->
<sect1 id="posix-files-and-directories">
<title>Files and Directories [POSIX Section 5]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
DIR *opendir( const char *dirname );
struct dirent *readdir( DIR *dirp );
int readdir_r( DIR *dirp, struct dirent *entry,
struct dirent **result );
void rewinddir( DIR *dirp );
int closedir( DIR *dirp );
int chdir( const char *path );
char *getcwd( char *buf, size_t size );
int open( const char * path , int oflag , ... );
int creat( const char * path, mode_t mode );
int link( const char *existing, const char *new );
int mkdir( const char *path, mode_t mode );
int unlink( const char *path );
int rmdir( const char *path );
int rename( const char *old, const char *new );
int stat( const char *path, struct stat *buf );
int fstat( int fd, struct stat *buf );
int access( const char *path, int amode );
long pathconf(const char *path, int name);
long fpathconf(int fd, int name);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
mode_t umask( mode_t cmask );
int mkfifo( const char *path, mode_t mode );
int chmod( const char *path, mode_t mode ); // TBA
int fchmod( int fd, mode_t mode ); // TBA
int chown( const char *path, uid_t owner, gid_t group );
int utime( const char *path, const struct utimbuf *times ); // TBA
int ftruncate( int fd, off_t length ); // TBA
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
If a call to <function>open()</function> or <function>creat()</function> supplies
the third _mode_ parameter, it will
currently be ignored.
</para>
</listitem>
<listitem>
<para>
Most of the functionality of these functions depends on
the underlying filesystem.
</para>
</listitem>
<listitem>
<para>
Currently<emphasis> access()</emphasis> only checks the
<emphasis>F_OK</emphasis> mode explicitly, the others are
all assumed to be true by default.
</para>
</listitem>
<listitem>
<para>
The maximum number of open files allowed is supplied by
the CYGNUM_FILEIO_NFILE option. The maximum number
of file descriptors is supplied by the CYGNUM_FILEIO_NFD
option.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Input and Output -->
<sect1 id="posix-input-and-output">
<title>Input and Output [POSIX Section 6]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int dup( int fd );
int dup2( int fd, int fd2 );
int close(int fd);
ssize_t read(int fd, void *buf, size_t nbyte);
ssize_t write(int fd, const void *buf, size_t nbyte);
int fcntl( int fd, int cmd, ... );
off_t lseek(int fd, off_t offset, int whence);
int fsync( int fd );
int fdatasync( int fd );</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
int pipe( int fildes[2] );
int aio_read( struct aiocb *aiocbp ); // TBA
int aio_write( struct aiocb *aiocbp ); // TBA
int lio_listio( int mode, struct aiocb *const list[],
int nent, struct sigevent *sig); // TBA
int aio_error( struct aiocb *aiocbp ); // TBA
int aio_return( struct aiocb *aiocbp ); // TBA
int aio_cancel( int fd, struct aiocb *aiocbp ); // TBA
int aio_suspend( const struct aiocb *const list[],
int nent, const struct timespec *timeout ); // TBA
int aio_fsync( int op, struct aiocb *aiocbp );
// TBA
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
Only the <emphasis>F_DUPFD</emphasis> command
of <emphasis>fcntl()</emphasis> is currently implemented.
</para>
</listitem>
<listitem>
<para>
Most of the functionality of these functions depends on
the underlying filesystem.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Device and Class Specific Functions -->
<sect1 id="posix-device-and-class-specific-functions">
<title>Device and Class Specific Functions [POSIX Section 7]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
speed_t cfgetospeed( const struct termios *termios_p );
int cfsetospeed( struct termios *termios_p, speed_t speed );
speed_t cfgetispeed( const struct termios *termios_p );
int cfsetispeed( struct termios *termios_p, speed_t speed );
int tcgetattr( int fd, struct termios *termios_p );
int tcsetattr( int fd, int optional_actions,
const struct termios *termios_p );
int tcsendbreak( int fd, int duration );
int tcdrain( int fd );
int tcflush( int fd, int queue_selector );
int tcsendbreak( int fd, int action );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
pid_t tcgetpgrp( int fd );
int tcsetpgrp( int fd, pid_t pgrp );</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
Only the functionality relevant to basic serial device
control is implemented. Only very limited support for
canonical input is provided, and then only via the
“tty” devices, not the “serial”
devices. None of the functionality relevant to job
control, controlling terminals and sessions is
implemented.
</para>
</listitem>
<listitem>
<para>
Only <emphasis>MIN</emphasis> = 0 and
<emphasis>TIME</emphasis> = 0 functionality is
provided.
</para>
</listitem>
<listitem>
<para>
Hardware flow control is supported if the underlying
device driver and serial port support it.
</para>
</listitem>
<listitem>
<para>
Support for break, framing and parity errors depends on
the functionality of the hardware and device driver.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ C Language Services -->
<sect1 id="posix-C-language-services">
<title>C Language Services [POSIX Section 8]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
char *setlocale( int category, const char *locale );
int fileno( FILE *stream );
FILE *fdopen( int fd, const char *type );
int getc_unlocked( FILE *stream);
int getchar_unlocked( void );
int putc_unlocked( FILE *stream );
int putchar_unlocked( void );
char *strtok_r( char *s, const char *sep,
char **lasts );
char *asctime_r( const struct tm *tm, char *buf );
char *ctime_r( const time_t *clock, char *buf );
struct tm *gmtime_r( const time_t *clock,
struct tm *result );
struct tm *localtime_r( const time_t *clock,
struct tm *result );
int rand_r( unsigned int *seed );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
void flockfile( FILE *file );
int ftrylockfile( FILE *file );
void funlockfile( FILE *file );
int sigsetjmp( sigjmp_buf env, int savemask ); // TBA
void siglongjmp( sigjmp_buf env, int val ); // TBA
void tzset(void); // TBA
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
<emphasis>setlocale()</emphasis> is implemented in the C
library Internationalization package.
</para>
</listitem>
<listitem>
<para>
Functions <emphasis>fileno()</emphasis> and
<emphasis>fdopen()</emphasis> are implemented in the C
library STDIO package.
</para>
</listitem>
<listitem>
<para>
Functions <emphasis>getc_unlocked()</emphasis>,
<emphasis>getchar_unlocked()</emphasis>,
<emphasis>putc_unlocked()</emphasis> and
<emphasis>putchar_unlocked()</emphasis> are defined
but are currently identical to their non-unlocked
equivalents.
</para>
</listitem>
<listitem>
<para>
<emphasis>strtok_r()</emphasis>, <emphasis>asctime_r()</emphasis>,
<emphasis>ctime_r()</emphasis>, <emphasis>gmtime_r()</emphasis>,
<emphasis>localtime_r()</emphasis> and
<emphasis>rand_r()</emphasis> are all currently in
the C library, alongside their non-reentrant versions.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ System Databases -->
<sect1 id="posix-system-databases">
<title>System Databases [POSIX Section 9]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
struct group *getgrgid( gid_t gid );
int getgrgid( gid_t gid, struct group *grp, char *buffer,
size_t bufsize, struct group **result );
struct group *getgrname( const char *name );
int getgrname_r( const char *name, struct group *grp,
char *buffer, size_t bufsize, struct group **result );
struct passwd *getpwuid( uid_t uid );
int getpwuid_r( uid_t uid, struct passwd *pwd,
char *buffer, size_t bufsize, struct passwd **result );
struct passwd *getpwnam( const char *name );
int getpwnam_r( const char *name, struct passwd *pwd,
char *buffer, size_t bufsize, struct passwd **result );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
None of the functions in this section are implemented.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Data Interchange Format -->
<sect1 id="posix-data-interchange-format">
<title>Data Interchange Format [POSIX Section 10]</title>
<para>
This section details <emphasis>tar</emphasis> and
<emphasis>cpio</emphasis> formats. Neither of these is supported by
eCos.
</para>
</sect1>
<!-- }}} -->
<!-- {{{ Synchronization -->
<sect1 id="posix-synchronization">
<title>Synchronization [POSIX Section 11]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int sem_init(sem_t *sem, int pshared, unsigned int value);
int sem_destroy(sem_t *sem);
int sem_wait(sem_t *sem);
int sem_trywait(sem_t *sem);
int sem_post(sem_t *sem);
int sem_getvalue(sem_t *sem, int *sval);
int pthread_mutexattr_init( pthread_mutexattr_t *attr);
int pthread_mutexattr_destroy( pthread_mutexattr_t *attr);
int pthread_mutex_init(pthread_mutex_t *mutex,
const pthread_mutexattr_t *mutex_attr);
int pthread_mutex_destroy(pthread_mutex_t *mutex);
int pthread_mutex_lock(pthread_mutex_t *mutex);
int pthread_mutex_trylock(pthread_mutex_t *mutex);
int pthread_mutex_unlock(pthread_mutex_t *mutex);
int pthread_condattr_init(pthread_condattr_t *attr);
int pthread_condattr_destroy(pthread_condattr_t *attr);
int pthread_cond_init(pthread_cond_t *cond,
const pthread_condattr_t *attr);
int pthread_cond_destroy(pthread_cond_t *cond);
int pthread_cond_signal(pthread_cond_t *cond);
int pthread_cond_broadcast(pthread_cond_t *cond);
int pthread_cond_wait(pthread_cond_t *cond,
pthread_mutex_t *mutex);
int pthread_cond_timedwait(pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
sem_t *sem_open(const char *name, int oflag, ...); // TBA
int sem_close(sem_t *sem); // TBA
int sem_unlink(const char *name); // TBA
int pthread_mutexattr_getpshared( const pthread_mutexattr_t *attr,
int *pshared );
int pthread_mutexattr_setpshared( const pthread_mutexattr_t *attr,
int pshared );
int pthread_condattr_getpshared( const pthread_condattr_t *attr,
int *pshared);
int pthread_condattr_setpshared( const pthread_condattr_t *attr,
int pshared);</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
The presence of semaphores is controlled by the
CYGPKG_POSIX_SEMAPHORES option. This in turn
causes the _POSIX_SEMAPHORES feature test
macro to be defined and the semaphore API to be made
available.
</para>
</listitem>
<listitem>
<para>
The <emphasis role="strong">pshared</emphasis> argument to
<emphasis>sem_init()</emphasis> is not implemented,
its value is ignored.
</para>
</listitem>
<listitem>
<para>
Functions <emphasis>sem_open()</emphasis>,
<emphasis>sem_close()</emphasis> and
<emphasis>sem_unlink()</emphasis> are present but
always return an error (ENOSYS).
</para>
</listitem>
<listitem>
<para>
The exact priority inversion protocols supported may be
controlled with the
_POSIX_THREAD_PRIO_INHERIT and
_POSIX_THREAD_PRIO_PROTECT
configuration options.
</para>
</listitem>
<listitem>
<para>
{_POSIX_THREAD_PROCESS_SHARED} is
not defined, so the
<emphasis role="strong">process-shared</emphasis> mutex
and condition variable attributes are not supported, and
neither are the functions
<emphasis>pthread_mutexattr_getpshared()</emphasis>,
<emphasis>pthread_mutexattr_setpshared()</emphasis>,
<emphasis>pthread_condattr_getpshared()</emphasis> and
<emphasis>pthread_condattr_setpshared()</emphasis>.
</para>
</listitem>
<listitem>
<para>
Condition variables do not become bound to a particular
mutex when
<emphasis>pthread_cond_wait()</emphasis> is
called. Hence different threads may wait on a condition
variable with different mutexes. This is at variance with
the standard, which requires a condition variable to
become (dynamically) bound by the first waiter, and
unbound when the last finishes. However, this difference
is largely benign, and the cost of policing this feature
is non-trivial.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Memory Management -->
<sect1 id="posix-memory-management">
<title>Memory Management [POSIX Section 12]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
int mlockall( int flags );
int munlockall( void );
int mlock( const void *addr, size_t len );
int munlock( const void *addr, size_t len );
void mmap( void *addr, size_t len, int prot, int flags,
int fd, off_t off );
int munmap( void *addr, size_t len );
int mprotect( const void *addr, size_t len, int prot );
int msync( void *addr, size_t len, int flags );
int shm_open( const char *name, int oflag, mode_t mode );
int shm_unlink( const char *name );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<para>
None of these functions are currently provided. Some may
be implemented in a restricted form in the future.
</para>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Execution Scheduling -->
<sect1 id="posix-execution-scheduling">
<title>Execution Scheduling [POSIX Section 13]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int sched_yield(void);
int sched_get_priority_max(int policy);
int sched_get_priority_min(int policy);
int sched_rr_get_interval(pid_t pid, struct timespec *t);
int pthread_attr_setscope(pthread_attr_t *attr, int scope);
int pthread_attr_getscope(const pthread_attr_t *attr, int *scope);
int pthread_attr_setinheritsched(pthread_attr_t *attr, int inherit);
int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inherit);
int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy);
int pthread_attr_setschedparam( pthread_attr_t *attr, const struct sched_param *param);
int pthread_attr_getschedparam( const pthread_attr_t *attr,
struct sched_param *param);
int pthread_setschedparam(pthread_t thread, int policy,
const struct sched_param *param);
int pthread_getschedparam(pthread_t thread, int *policy,
struct sched_param *param);
int pthread_mutexattr_setprotocol( pthread_mutexattr_t *attr,
int protocol);
int pthread_mutexattr_getprotocol( pthread_mutexattr_t *attr,
int *protocol);
int pthread_mutexattr_setprioceiling( pthread_mutexattr_t *attr,
int prioceiling);
int pthread_mutexattr_getprioceiling( pthread_mutexattr_t *attr,
int *prioceiling);
int pthread_mutex_setprioceiling( pthread_mutex_t *mutex,
int prioceiling,
int *old_ceiling);
int pthread_mutex_getprioceiling( pthread_mutex_t *mutex,
int *prioceiling);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<screen>
int sched_setparam(pid_t pid, const struct sched_param *param);
int sched_getparam(pid_t pid, struct sched_param *param);
int sched_setscheduler(pid_t pid, int policy,
const struct sched_param *param);
int sched_getscheduler(pid_t pid);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
The functions <emphasis>sched_setparam()</emphasis>,
<emphasis>sched_getparam()</emphasis>,
<emphasis>sched_setscheduler()</emphasis> and
<emphasis>sched_getscheduler()</emphasis> are present
but always return an error.
</para>
</listitem>
<listitem>
<para>
The scheduler policy <emphasis>SCHED_OTHER</emphasis> is
equivalent to <emphasis>SCHED_RR</emphasis>.
</para>
</listitem>
<listitem>
<para>
Only <emphasis>PTHREAD_SCOPE_SYSTEM</emphasis>
is supported as a
<emphasis role="strong">contentionscope</emphasis>
attribute.
</para>
</listitem>
<listitem>
<para>
The default thread scheduling attributes are:
<screen>
contentionscope PTHREAD_SCOPE_SYSTEM
inheritsched PTHREAD_INHERIT_SCHED
schedpolicy SCHED_OTHER
schedparam.sched 0
</screen>
</para>
</listitem>
<listitem>
<para>
Mutex priority inversion protection is controlled by a
number of kernel configuration options.
If CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_INHERIT
is defined then
{_POSIX_THREAD_PRIO_INHERIT}
will be defined and PTHREAD_PRIO_INHERIT may
be set as the protocol in a
<emphasis>pthread_mutexattr_t</emphasis>
object.
If CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_CEILING
is defined then
{_POSIX_THREAD_PRIO_PROTECT}
will be defined and PTHREAD_PRIO_PROTECT may
be set as the protocol in a
<emphasis>pthread_mutexattr_t</emphasis> object.
</para>
</listitem>
<listitem>
<para>
The default attribute values set by
<emphasis>pthread_mutexattr_init()</emphasis>
is to set the protocol attribute to
PTHREAD_PRIO_NONE and the prioceiling
attribute to zero.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Clocks and Timers -->
<sect1 id="posix-clocks-and-timers">
<title>Clocks and Timers [POSIX Section 14]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int clock_settime( clockid_t clock_id,
const struct timespec *tp);
int clock_gettime( clockid_t clock_id, struct timespec *tp);
int clock_getres( clockid_t clock_id, struct timespec *tp);
int timer_create( clockid_t clock_id, struct sigevent *evp,
timer_t *timer_id);
int timer_delete( timer_t timer_id );
int timer_settime( timer_t timerid, int flags,
const struct itimerspec *value,
struct itimerspec *ovalue );
int timer_gettime( timer_t timerid, struct itimerspec *value );
int timer_getoverrun( timer_t timerid );
int nanosleep( const struct timespec *rqtp, struct timespec *rmtp);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
Currently <emphasis>timer_getoverrun()</emphasis> only
reports timer notifications that are delayed in the timer
subsystem. If they are delayed in the signal subsystem, due to
signal masks for example, this is not counted as an overrun.
</para>
</listitem>
<listitem>
<para>
The option CYGPKG_POSIX_TIMERS allows the timer support to be
enabled or disabled, and causes _POSIX_TIMERS to be defined
appropriately. This will cause other parts of the POSIX system to
have limited functionality.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Message Passing -->
<sect1 id="posix-message-passing">
<title>Message Passing [POSIX Section 15]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
mqd_t mq_open( const char *name, int oflag, ... );
int mq_close( mqd_t mqdes );
int mq_unlink( const char *name );
int mq_send( mqd_t mqdes, const char *msg_ptr,
size_t msg_len, unsigned int msg_prio );
ssize_t mq_receive( mqd_t mqdes, char *msg_ptr,
size_t msg_len, unsigned int *msg_prio );
int mq_setattr( mqd_t mqdes, const struct mq_attr *mqstat,
struct mq_attr *omqstat );
int mq_getattr( mqd_t mqdes, struct mq_attr *mqstat );
int mq_notify( mqd_t mqdes, const struct sigevent *notification );
</screen>
<para>From POSIX 1003.1d draft: </para>
<screen>
int mq_send( mqd_t mqdes, const char *msg_ptr,
size_t msg_len, unsigned int msg_prio,
const struct timespec *abs_timeout );
ssize_t mq_receive( mqd_t mqdes, char *msg_ptr,
size_t msg_len, unsigned int *msg_prio,
const struct timespec *abs_timeout );
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
The presence of message queues is controlled by the
CYGPKG_POSIX_MQUEUES option. Setting this will
cause [_POSIX_MESSAGE_PASSING] to
be defined and the message queue API to be made available.
</para>
</listitem>
<listitem>
<para>
Message queues are not currently filesystem objects. They live in
their own name and descriptor spaces.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Thread Management -->
<sect1 id="posix-thread-management">
<title>Thread Management [POSIX Section 16]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int pthread_attr_init(pthread_attr_t *attr);
int pthread_attr_destroy(pthread_attr_t *attr);
int pthread_attr_setdetachstate(pthread_attr_t *attr,
int detachstate);
int pthread_attr_getdetachstate(const pthread_attr_t *attr,
int *detachstate);
int pthread_attr_setstackaddr(pthread_attr_t *attr,
void *stackaddr);
int pthread_attr_getstackaddr(const pthread_attr_t *attr,
void **stackaddr);
int pthread_attr_setstacksize(pthread_attr_t *attr,
size_t stacksize);
int pthread_attr_getstacksize(const pthread_attr_t *attr,
size_t *stacksize);
int pthread_create( pthread_t *thread,
const pthread_attr_t *attr,
void *(*start_routine)(void *),
void *arg);
pthread_t pthread_self( void );
int pthread_equal(pthread_t thread1, pthread_t thread2);
void pthread_exit(void *retval);
int pthread_join(pthread_t thread, void **thread_return);
int pthread_detach(pthread_t thread);
int pthread_once(pthread_once_t *once_control,
void (*init_routine)(void));
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
The presence of thread support as a whole is controlled by the the
CYGPKG_POSIX_PTHREAD configuration option. Note that disabling
this will also disable many other features of the POSIX package,
since these are intimately bound up with the thread mechanism.
</para>
</listitem>
<listitem>
<para>
The default (non-scheduling) thread attributes are:
</para>
<screen>
detachstate PTHREAD_CREATE_JOINABLE
stackaddr unset
stacksize unset
</screen>
</listitem>
<listitem>
<para>
Dynamic thread stack allocation is only provided if there is an
implementation of
<emphasis>malloc()</emphasis> configured (i.e. a package
implements the
CYGINT_MEMALLOC_MALLOC_ALLOCATORS
interface). If there is no malloc() available, then the thread
creator must supply a stack. If only a stack address is supplied
then the stack is assumed to be PTHREAD_STACK_MIN
bytes long. This size is seldom useful for any but the most
trivial of threads. If a different sized stack is used, both
the stack address and stack size must be supplied.
</para>
</listitem>
<listitem>
<para>
The value of PTHREAD_THREADS_MAX is supplied by
the CYGNUM_POSIX_PTHREAD_THREADS_MAX
option. This defines the maximum number of threads allowed. The
POSIX standard requires this value to be at least 64, and this
is the default value set.
</para>
</listitem>
<listitem>
<para>
When the POSIX package is installed, the thread that calls
<emphasis>main()</emphasis> is initialized as a POSIX thread. The
priority of that thread is controlled by the
CYGNUM_POSIX_MAIN_DEFAULT_PRIORITY option.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Thread-Specific Data -->
<sect1 id="posix-thread-specific-data">
<title>Thread-Specific Data [POSIX Section 17]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int pthread_key_create(pthread_key_t *key,
void (*destructor)(void *));
int pthread_setspecific(pthread_key_t key, const void *pointer);
void *pthread_getspecific(pthread_key_t key);
int pthread_key_delete(pthread_key_t key);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
The value of PTHREAD_DESTRUCTOR_ITERATIONS is
provided by the
CYGNUM_POSIX_PTHREAD_DESTRUCTOR_ITERATIONS
option. This controls the number of times that a key destructor
will be called while the data item remains non-NULL.
</para>
</listitem>
<listitem>
<para>
The value of PTHREAD_KEYS_MAX is provided
by the CYGNUM_POSIX_PTHREAD_KEYS_MAX
option. This defines the maximum number of per-thread data items
supported. The POSIX standard calls for this to be a minimum of
128, which is rather large for an embedded system. The default
value for this option is set to 128 for compatibility but it
should be reduced to a more usable value.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Thread Cancellation -->
<sect1 id="posix-thread-cancellation">
<title>Thread Cancellation [POSIX Section 18]</title>
<!-- =================================================================== -->
<sect2>
<title>Functions Implemented</title>
<screen>
int pthread_cancel(pthread_t thread);
int pthread_setcancelstate(int state, int *oldstate);
int pthread_setcanceltype(int type, int *oldtype);
void pthread_testcancel(void);
void pthread_cleanup_push( void (*routine)(void *),
void *arg);
void pthread_cleanup_pop( int execute);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Functions Omitted</title>
<para>
<none>
</para>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<para>
Asynchronous cancellation is only partially implemented. In
particular, cancellation may occur in unexpected places in some
functions. It is strongly recommended that only synchronous
cancellation be used.
</para>
</sect2>
</sect1>
<!-- }}} -->
<!-- {{{ Non-POSIX Functions -->
<sect1 id="posix-non-posix-functions">
<title>Non-POSIX Functions</title>
<para>
In addition to the standard POSIX functions defined above, the
following non-POSIX functions are defined in the FILEIO package.
</para>
<!-- =================================================================== -->
<sect2>
<title>General I/O Functions</title>
<screen>
int ioctl( int fd, CYG_ADDRWORD com, CYG_ADDRWORD data );
int select( int nfd, fd_set *in, fd_set *out, fd_set *ex, struct timeval *tv);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Socket Functions</title>
<screen>
int socket( int domain, int type, int protocol);
int bind( int s, const struct sockaddr *sa, unsigned int len);
int listen( int s, int len);
int accept( int s, struct sockaddr *sa, socklen_t *addrlen);
int connect( int s, const struct sockaddr *sa, socklen_t len);
int getpeername( int s, struct sockaddr *sa, socklen_t *len);
int getsockname( int s, struct sockaddr *sa, socklen_t *len);
int setsockopt( int s, int level, int optname, const void *optval,
socklen_t optlen);
int getsockopt( int s, int level, int optname, void *optval,
socklen_t *optlen);
ssize_t recvmsg( int s, struct msghdr *msg, int flags);
ssize_t recvfrom( int s, void *buf, size_t len, int flags,
struct sockaddr *from, socklen_t *fromlen);
ssize_t recv( int s, void *buf, size_t len, int flags);
ssize_t sendmsg( int s, const struct msghdr *msg, int flags);
ssize_t sendto( int s, const void *buf, size_t len, int flags,
const struct sockaddr *to, socklen_t tolen);
ssize_t send( int s, const void *buf, size_t len, int flags);
int shutdown( int s, int how);
</screen>
</sect2>
<!-- =================================================================== -->
<sect2>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>
The precise behaviour of these functions depends mainly on the
functionality of the underlying filesystem or network stack to
which they are applied.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<!-- }}} -->
</chapter>
<!-- {{{ Bibliography -->
<bibliography id="posix-references-and-bibliography">
<title>References and Bibliography</title>
<bibliomixed>
<bibliomisc>[Lewine]</bibliomisc>
<author>
<firstname>Donald</firstname>
<othername>A.</othername>
<surname>Lweine</surname>
</author>
<title>Posix Programmer’s Guide: Writing Portable Unix
Programs With the POSIX.1 Standard O’Reilly &
Associates; ISBN: 0937175730.</title></bibliomixed>
<bibliomixed>
<bibliomisc>[Lewis1]</bibliomisc>
<author>
<firstname>Bil</firstname>
<surname>Lewis</surname>
</author>
<author>
<firstname>Daniel</firstname>
<othername>J.</othername>
<surname>Berg</surname>
</author>
<title>Threads Primer: A Guide to Multithreaded Programming</title>
<publishername>Prentice Hall</publishername>
<isbn>ISBN: 013443698</isbn>
</bibliomixed>
<bibliomixed>
<bibliomisc>[Lewis2]</bibliomisc>
<author>
<firstname>Bil</firstname>
<surname>Lewis</surname>
</author>
<author>
<firstname>Daniel</firstname>
<othername>J.</othername>
<surname>Berg</surname>
</author>
<title>Multithreaded Programming With Pthreads</title>
<publisher>
<publishername>Prentice Hall Computer Books</publishername>
</publisher>
<isbn>ISBN: 0136807291</isbn>
</bibliomixed>
<bibliomixed>
<bibliomisc>[Nichols]</bibliomisc>
<author>
<firstname>Bradford</firstname>
<surname>Nichols</surname>
</author>
<author>
<firstname>Dick</firstname>
<surname>Buttlar</surname>
</author>
<author>
<firstname>Jacqueline</firstname>
<othername>Proulx</othername>
<surname>Farrell</surname>
</author>
<title>Pthreads Programming: A POSIX Standard for Better
Multiprocessing (O’Reilly Nutshell)</title>
<publisher><publishername>O’Reilly & Associates</publishername>
</publisher>
<isbn>ISBN: 1565921151</isbn>
</bibliomixed>
<bibliomixed>
<bibliomisc>[Norton]</bibliomisc>
<author>
<firstname>Scott</firstname>
<othername>J.</othername>
<surname>Norton</surname>
</author>
<author>
<firstname>Mark</firstname>
<othername>D.</othername>
<surname>Depasquale</surname>
</author>
<title>Thread Time: The MultiThreaded Programming Guide</title>
<publisher><publishername>Prentice Hall</publishername>
</publisher>
<isbn>ISBN: 0131900676</isbn></bibliomixed>
<bibliomixed>
<bibliomisc>[POSIX]</bibliomisc>
<title>Portable Operating System Interface(POSIX) -
Part 1: System Application Programming Interface (API)[C
Language]</title>
<corpauthor>ISO/IEC 9945-1:1996, IEEE</corpauthor></bibliomixed>
<bibliomixed>
<bibliomisc>[SUS2]</bibliomisc>
<title>Open Group; Single Unix Specification, Version 2</title>
<bibliomisc><ulink
url="http://www.opengroup.org/public/pubs/online/7908799/index.html">http://www.opengroup.org/public/pubs/online/7908799/index.html</ulink></bibliomisc>
</bibliomixed>
</bibliography>
<!-- }}} -->
</part>
Go to most recent revision | Compare with Previous | Blame | View Log