Chapter 142. POSIX Standard Support

Table of Contents

142.1. Process Primitives [POSIX Section 3]
142.1.1. Functions Implemented
142.1.2. Functions Omitted
142.1.3. Notes
142.2. Process Environment [POSIX Section 4]
142.2.1. Functions Implemented
142.2.2. Functions Omitted
142.2.3. Notes
142.3. Files and Directories [POSIX Section 5]
142.3.1. Functions Implemented
142.3.2. Functions Omitted
142.3.3. Notes
142.4. Input and Output [POSIX Section 6]
142.4.1. Functions Implemented
142.4.2. Functions Omitted
142.4.3. Notes
142.5. Device and Class Specific Functions [POSIX Section 7]
142.5.1. Functions Implemented
142.5.2. Functions Omitted
142.5.3. Notes
142.6. C Language Services [POSIX Section 8]
142.6.1. Functions Implemented
142.6.2. Functions Omitted
142.6.3. Notes
142.7. System Databases [POSIX Section 9]
142.7.1. Functions Implemented
142.7.2. Functions Omitted
142.7.3. Notes
142.8. Data Interchange Format [POSIX Section 10]
142.9. Synchronization [POSIX Section 11]
142.9.1. Functions Implemented
142.9.2. Functions Omitted
142.9.3. Notes
142.10. Memory Management [POSIX Section 12]
142.10.1. Functions Implemented
142.10.2. Functions Omitted
142.10.3. Notes
142.11. Execution Scheduling [POSIX Section 13]
142.11.1. Functions Implemented
142.11.2. Functions Omitted
142.11.3. Notes
142.12. Clocks and Timers [POSIX Section 14]
142.12.1. Functions Implemented
142.12.2. Functions Omitted
142.12.3. Notes
142.13. Message Passing [POSIX Section 15]
142.13.1. Functions Implemented
142.13.2. Functions Omitted
142.13.3. Notes
142.14. Thread Management [POSIX Section 16]
142.14.1. Functions Implemented
142.14.2. Functions Omitted
142.14.3. Notes
142.15. Thread-Specific Data [POSIX Section 17]
142.15.1. Functions Implemented
142.15.2. Functions Omitted
142.15.3. Notes
142.16. Thread Cancellation [POSIX Section 18]
142.16.1. Functions Implemented
142.16.2. Functions Omitted
142.16.3. Notes
142.17. Non-POSIX Functions
142.17.1. General I/O Functions
142.17.2. Socket Functions
142.17.3. Notes

eCos contains support for the POSIX Specification (ISO/IEC 9945-1)[POSIX].

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.

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.

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.

The remainder of this chapter broadly follows the structure of the POSIX Specification. References to the appropriate section of the Standard are included.

Omitted functions marked with “// TBA” are potential candidates for later implementation.

142.1. Process Primitives [POSIX Section 3]

142.1.1. Functions Implemented

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

142.1.2. Functions Omitted

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

142.1.3. Notes

  • 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.
  • kill() and sigqueue() may only take a pid argument of zero, which maps to the current process.
  • The SIGEV_THREAD notification type is not currently implemented.
  • Job Control and Memory Protection signals are not supported.
  • An extra implementation defined si_code value, SI_EXCEPT, is defined to distinguish hardware generated exceptions from others.
  • Extra signals are defined: _SIGTRAP_, _SIGIOT_, _SIGEMT_, _SIGSYS_ These are largely to maintain compatibility with the signal numbers used by GDB.

  • Signal delivery may currently occur at unexpected places in some API functions. Using longjmp() 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.

142.2. Process Environment [POSIX Section 4]

142.2.1. Functions Implemented

int uname( struct utsname *name );
time_t time( time_t *tloc );
char *getenv( const char *name );
int isatty( int fd );
long sysconf( int name );

142.2.2. Functions Omitted

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

142.2.3. Notes

  • The fields of the utsname structure are initialized as follows:

    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)

    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.

  • The time() function is currently implemented in the C library.
  • 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 environ variable.
  • At present isatty() 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.
  • 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 <limits.h>, or zero.

142.3. Files and Directories [POSIX Section 5]

142.3.1. Functions Implemented

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

142.3.2. Functions Omitted

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

142.3.3. Notes

  • If a call to open() or creat() supplies the third _mode_ parameter, it will currently be ignored.
  • Most of the functionality of these functions depends on the underlying filesystem.
  • Currently access() only checks the F_OK mode explicitly, the others are all assumed to be true by default.
  • 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.

142.4. Input and Output [POSIX Section 6]

142.4.1. Functions Implemented

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

142.4.2. Functions Omitted

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

142.4.3. Notes

  • Only the F_DUPFD command of fcntl() is currently implemented.
  • Most of the functionality of these functions depends on the underlying filesystem.

142.5. Device and Class Specific Functions [POSIX Section 7]

142.5.1. Functions Implemented

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

142.5.2. Functions Omitted

pid_t tcgetpgrp( int fd );
int tcsetpgrp( int fd, pid_t pgrp );

142.5.3. Notes

  • 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.
  • Only MIN = 0 and TIME = 0 functionality is provided.
  • Hardware flow control is supported if the underlying device driver and serial port support it.
  • Support for break, framing and parity errors depends on the functionality of the hardware and device driver.

142.6. C Language Services [POSIX Section 8]

142.6.1. Functions Implemented

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

142.6.2. Functions Omitted

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

142.6.3. Notes

  • setlocale() is implemented in the C library Internationalization package.
  • Functions fileno() and fdopen() are implemented in the C library STDIO package.
  • Functions getc_unlocked(), getchar_unlocked(), putc_unlocked() and putchar_unlocked() are defined but are currently identical to their non-unlocked equivalents.
  • strtok_r(), asctime_r(), ctime_r(), gmtime_r(), localtime_r() and rand_r() are all currently in the C library, alongside their non-reentrant versions.

142.7. System Databases [POSIX Section 9]

142.7.1. Functions Implemented


142.7.2. Functions Omitted

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

142.7.3. Notes

  • None of the functions in this section are implemented.

142.8. Data Interchange Format [POSIX Section 10]

This section details tar and cpio formats. Neither of these is supported by eCos.

142.9. Synchronization [POSIX Section 11]

142.9.1. Functions Implemented

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_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime);
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);

142.9.2. Functions Omitted

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

142.9.3. Notes

  • 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.
  • The pshared argument to sem_init() is not implemented, its value is ignored.
  • Functions sem_open(), sem_close() and sem_unlink() are present but always return an error (ENOSYS).
  • The exact priority inversion protocols supported may be controlled with the _POSIX_THREAD_PRIO_INHERIT and _POSIX_THREAD_PRIO_PROTECT configuration options.
  • {_POSIX_THREAD_PROCESS_SHARED} is not defined, so the process-shared mutex and condition variable attributes are not supported, and neither are the functions pthread_mutexattr_getpshared(), pthread_mutexattr_setpshared(), pthread_condattr_getpshared() and pthread_condattr_setpshared().
  • Condition variables do not become bound to a particular mutex when pthread_cond_wait() 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.

142.10. Memory Management [POSIX Section 12]

142.10.1. Functions Implemented


142.10.2. Functions Omitted

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

142.10.3. Notes

None of these functions are currently provided. Some may be implemented in a restricted form in the future.

142.11. Execution Scheduling [POSIX Section 13]

142.11.1. Functions Implemented

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

142.11.2. Functions Omitted

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

142.11.3. Notes

  • The functions sched_setparam(), sched_getparam(), sched_setscheduler() and sched_getscheduler() are present but always return an error.
  • The scheduler policy SCHED_OTHER is equivalent to SCHED_RR.
  • Only PTHREAD_SCOPE_SYSTEM is supported as a contentionscope attribute.
  • The default thread scheduling attributes are:

    contentionscope         PTHREAD_SCOPE_SYSTEM
    inheritsched            PTHREAD_INHERIT_SCHED
    schedpolicy             SCHED_OTHER
    chedparam.sched        0
  • 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 pthread_mutexattr_t 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 pthread_mutexattr_t object.
  • The default attribute values set by pthread_mutexattr_init() is to set the protocol attribute to PTHREAD_PRIO_NONE and the prioceiling attribute to zero.

142.12. Clocks and Timers [POSIX Section 14]

142.12.1. Functions Implemented

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);
int gettimeofday(struct timeval *tv, struct timezone* tz);

142.12.2. Functions Omitted


142.12.3. Notes

  • Currently timer_getoverrun() 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.
  • 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.

142.13. Message Passing [POSIX Section 15]

142.13.1. Functions Implemented

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

From POSIX 1003.1d draft:

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

142.13.2. Functions Omitted


142.13.3. Notes

  • 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.
  • Message queues are not currently filesystem objects. They live in their own name and descriptor spaces.

142.14. Thread Management [POSIX Section 16]

142.14.1. Functions Implemented

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

142.14.2. Functions Omitted


142.14.3. Notes

  • 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.
  • The default (non-scheduling) thread attributes are:

    detachstate            PTHREAD_CREATE_JOINABLE
    stackaddr              unset
    stacksize              unset
  • Dynamic thread stack allocation is only provided if there is an implementation of malloc() 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.
  • 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.
  • When the POSIX package is installed, the thread that calls main() is initialized as a POSIX thread. The priority of that thread is controlled by the CYGNUM_POSIX_MAIN_DEFAULT_PRIORITY option.

142.15. Thread-Specific Data [POSIX Section 17]

142.15.1. Functions Implemented

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

142.15.2. Functions Omitted


142.15.3. Notes

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

142.16. Thread Cancellation [POSIX Section 18]

142.16.1. Functions Implemented

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

142.16.2. Functions Omitted


142.16.3. Notes

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.

142.17. Non-POSIX Functions

In addition to the standard POSIX functions defined above, the following non-POSIX functions are defined in the FILEIO package.

142.17.1. General I/O Functions

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

142.17.2. Socket Functions

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

142.17.3. Notes

  • The precise behaviour of these functions depends mainly on the functionality of the underlying filesystem or network stack to which they are applied.