ChorusOS man pages section 3POSIX: POSIX Library Functions

intro(3POSIX)

NAME

Intro- introduction to POSIX-compliant pthread and timer calls

DESCRIPTION

This section describes the API for the POSIX threads and timers in ChorusOS (see intro(2K)).

The POSIX threads provide a limited POSIX-compliant programming and execution environment including thread management and thread synchronization functions. It is complemented by the POSIX timers, which adds POSIX real-time clock and timer features. POSIX-THREADS is based on the draft standard P1003.1c (Threads Extension) Draft 8, POSIX-TIMERS on IEEE Std 1003.1b-1993.

NUMERICAL LIMITS

Symbols corresponding to POSIX numerical limits are defined in <limits.h>. However if a definition of one of the values defined by POSIX is omitted from <limits.h>, its actual value is provided by the sysconf(3POSIX) function.

SYMBOLIC CONSTANTS

As different POSIX profiles may be supported by the same set of header files, the POSIX-THREADS/POSIX-TIMERS option symbols are defined in <unistd.h>. An application may always choose to interrogate a value at run-time to take advantage of the current configuration using the sysconf(3POSIX) function.

The following POSIX option symbols are defined in the context of these features. For POSIX-THREADS:

_POSIX_SEMAPHORES
_POSIX_THREADS
_POSIX_THREAD_SAFE_FUNCTIONS
_POSIX_THREAD_PRIORITY_SCHEDULING
_POSIX_THREAD_ATTR_STACKSIZE
_POSIX_THREAD_ATTR_STACKADDR

For POSIX-TIMERS:

_POSIX_TIMERS

However, some features in the POSIX standards associated with these option symbols are not supported in ChorusOS. In other cases, the semantics provided are slightly different, as follows:

Thread cancellation: No interfaces related to thread cancellation are provided.
Priority queueing on synchronization objects: Threads are awakened by sem_post, pthread_mutex_unlock, and pthread_cond_signal in the order in which they had blocked on the respective synchronization object, rather than in priority order.
Resource limits: The symbols _SC_PTHREAD_THREADS_MAX and _SC_PTHREAD_KEYS_MAX respectively, define limits on the number of threads and the number of thread-specific data keys per system rather than per process (actor) as defined in POSIX.
Supervisor thread stacks: Most functions are identical in user and supervisor actors. However, an application running in supervisor mode may not create a thread with a pre-allocated stack.

In all other areas, an attempt has been made to conform precisely to the specifications of the two POSIX standards.

A POSIX application runs as a Chorus actor. The POSIX interfaces described in this manual are seen as extensions to the standard ChorusOS programming environment. In several areas, ChorusOS and POSIX semantics interact.

CHORUS-POSIX INTERACTIONS: SCHEDULING

The SCHED_FIFO and SCHED_RR scheduling policies are provided as specified in POSIX 1003.1b. (A third policy, SCHED_OTHER, is identical to SCHED_RR.) The SCHED_FIFO policy provides strict preemptive scheduling within a range of priorities that may be obtained using sched_get_priority_min and sched_get_priority_max. Except when thread priorities are dynamically modified, a running thread continues executing until it blocks voluntarily or is preempted by a thread of higher priority, in which case it is queued at the head of the list of runnable threads corresponding to its priority level. The SCHED_RR policy is the same except that a thread that executes longer than a pre-defined quantum (obtainable using sched_rr_get_interval) may be descheduled and queued behind any other runnable threads waiting to execute at the same priority.

The POSIX threads are mapped one-to-one onto ChorusOS threads: the POSIX SCHED_FIFO and SCHED_RR scheduling policies are mapped onto the K_SCHED_FIFO and K_SCHED_RR scheduling classes, respectively. The priority mapping is defined below. Note that the priority systems scales are reversed:

In the ChorusOS scheduling classes, a larger numeric priority value indicates a lower thread priority.
Under the SCHED_FIFO and SCHED_RR policies, a higher priority value indicates a higher thread priority.

<sched.h>

SCHED_FIFO: POSIX priorities in the range POSIX_FIFO_MIN (0) to POSIX_FIFO_MAX (255) are mapped one-to-one onto the CHORUS K_SCHED_FIFO class priority range K_FIFO_PRIOMIN (255) to K_FIFO_PRIOMAX (0).
SCHED_RR: POSIX priorities in the range POSIX_RR_MIN (0) to POSIX_RR_MAX (255) are mapped one-to-one onto the CHORUS K_SCHED_RR class priority range K_RR_PRIOMON (255) to K_RR_PRIOMAX (0).

The default policy and priority are determined as follows. The first invocation of a substantive function of either the POSIX-THREADS or the POSIX-TIMERS (if included) features triggers initialization of both features. (Calls that create or manipulate threads, thread attribute objects, or timers are considered substantive for this purpose.) At that point the calling thread, which is normally the initial thread of the actor, is transformed into a POSIX thread (pthread), as if it had been created using y pthread_create in the state PTHREAD_CREATE_DETACHED (see pthread_create(3POSIX), pthread_attr_init(3POSIX)). Its ChorusOS thread priority is obtained (see threadScheduler(2K)) and mapped into a POSIX policy and priority using the reverse of the mappings defined above. These policy and priority values become the defaults for threads created in PTHREAD_EXPLICIT_SCHED (see pthread_attr_init(3POSIX)). Note that this procedure can only operate correctly if the calling thread is in the ChorusOS K_SCHED_FIFO or K_SCHED_RR class. If the calling thread is in a different CHORUS scheduling class, then the default policy is set to SCHED_RR and the default priority is set to POSIX_RR_MIN.

All threads are scheduled on a system-wide basis, according to their priority (and scheduling class). Hence the POSIX option PTHREAD_SCOPE_PROCESS is not supported (see pthread_attr_setscope(3POSIX)).

CHORUS-POSIX INTERACTIONS: THREAD MANAGEMENT

POSIX applications are expected to use POSIX facilities for thread management wherever possible, rather than the corresponding ChorusOS facilities. However, some applications may involve threads which are not pthreads (not created by pthread_create), such as message handlers in supervisor actors. Furthermore, certain ChorusOS thread management services with no POSIX analogues may be useful in some applications.

When POSIX threads are created using the facilities in this manual, the POSIX thread identifier type pthread_t is equivalent to the ChorusOS thread local identifier. That is, the value returned by the thread argument of pthread_create is always equal to the threadli of the underlying ChorusOS thread.

As mentioned earlier, the first invocation of POSIX-THREADS or POSIX-TIMERS transforms the calling thread into a pthread. Other threads in the actor are not pthreads unless created by pthread_create. However, many POSIX services may be invoked by pure ChorusOS threads. In particular, POSIX mutexes, condition variables, and semaphores may be freely used for synchronization between and among POSIX threads and pure CHORUS threads. Certain POSIX functions have limitations regarding invocation from pure CHORUS threads.

pthread_create: May be used to create a POSIX thread; the PTHREAD_EXPLICIT_SCHED attribute is assumed. PTHREAD_INHERIT_SCHED is ignored if specified
pthread_exit: Deletes the calling thread, ignoring the status argument. (Non-pthreads cannot be joined using pthread_join)
timer_create: Requires that the caller be a POSIX thread; otherwise an error (ENOSYS) is returned

The following CHORUS Core Executive system calls may be useful in manipulating POSIX threads.

threadAbort and threadAborted
threadContext
threadName
threadStat

If a pthread is aborted while blocked or executing in certain POSIX functions, the result is the same as that defined in POSIX on arrival of a caught signal. In particular, pthread_join, sem_wait, sem_trywait, and nanosleep return EINTR and may take other actions in the event of a thread abort (see the corresponding manual pages for details). Otherwise, no support for thread abort is provided at the POSIX level.

INTERFACE TYPE DEFINITIONS

The following interface object types are used in the definition of the various POSIX functions. Formal definitions are found in <pthread.h>, <time.h>, <sched.h>, or <signal.h>.

pthread_t: POSIX thread identifier (equal to the corresponding threadli)
pthread_attr_t: POSIX thread attribute object (see pthread_attr_init(3POSIX))
pthread_mutex_t: Mutex, or blocking binary semaphore (see pthread_mutex_init(3POSIX))
pthread_mutexattr_t: Mutex attribute object; no attributes currently defined (see pthread_mutexattr_init(3POSIX))
pthread_cond_t: Condition variable (see pthread_cond_init(3POSIX))
pthread_condattr_t: Condition variable attribute object; no attributes currently defined (see pthread_condattr_init(3POSIX))
pthread_key_t: Key for lookup of per-thread data within actor (see pthread_key_create(3POSIX))
sem_t: Counting semaphore (see sem_init(3POSIX))
void *: (standard C type) used for passing an arbitrary untyped value (not necessarily a pointer) in pthread_exit, pthread_join, pthread_setspecific, and pthread_getspecific
pthread_once_t: Variable used to record the initialization of a dynamic library (see pthread_once(3POSIX))
struct sched_param: Scheduling parameter structure, defined for each scheduling policy. For the policies currently supported, there is only one member, sched_priority.
clockid_t: Clock identifier. Only one clock, the system realtime clock, is supported. (see clock_settime(3POSIX))
struct sigevent: Structure defining action to take on asynchronous event notification. Contains a notification routine address and a single argument (see timer_create(3POSIX))
timer_t: Identifier of one-shot or periodic timer (see timer_create(3POSIX))
struct timespec: Standard time interval specification, in terms of seconds and additional nanoseconds.
struct itimerspec: Timer setting. Contains one struct timespec defining the time interval or absolute time, and another specifying the reload interval for a periodic timer.
size_t: Object size in bytes.

ERROR CODES

WARNING: error reporting conventions are inconsistent by design in the POSIX-THREADS and POSIX-TIMERS features (see intro(2K)). Error returns from POSIX-compliant interfaces follow the corresponding POSIX standards precisely, in which two different styles of return code are used:

1003.1b functions: (those beginning with sem_, sched_, clock_, and timer_; and nanosleep) return -1 in case of error and store the error code in errno.
1003.1c functions: (those beginning with pthread_) return the error code directly and do not set errno.

In addition, error codes are used differently in some cases. For example, an unsuccessful sem_trywait (1003.1b) returns EAGAIN, whereas an unsuccessful pthread_mutex_try (1003.1c) returns EBUSY. Invalid virtual addresses are flagged with EFAULT in 1003.1b functions and EINVAL in 1003.1c functions. Individual man pages contain information about the error codes returned by each routine.

The EFAULT error code will be returned where possible. However the library implementation of the POSIX interface accesses pointer arguments. Hence bad virtual addresses can cause a segmentation fault, instead of returning EFAULT error code.

1 EPERM Non-recoverable error: Attempted to perform a restricted operation for which the caller does not have the privilege.
3 ESRCH Object not found: A pthread call designated a non-existent target thread, or a thread which is not a pthread.
4 EINTR Interrupted function: The thread was aborted while blocked or executing in the function.
11 EAGAIN Resource temporarily exhausted: Some object or resource was unavailable, but the call may succeed if retried.
12 ENOMEM Insufficient memory available: Memory was unavailable, but the call may succeed if retried.
14 EFAULT Bad virtual address: A pointer argument contained an unmapped or inaccessible virtual address (user mode only).
16 EBUSY Object in use: Some object or resource was in use by another thread.
22 EINVAL Invalid argument: An argument was invalid, or a virtual address was unmapped or inaccessible (user mode only).
33 EDOM Math arg out of domain of function
34 ERANGE Math result not representable
45 EDEADLK Deadlock condition: A thread attempted to join (pthread_join) with itself.
80 ENOSYS Function not implemented: The function is not provided in the mode of the current actor.
108 ETIMEDOUT Timeout: The specified interval expired before the function completed.
133 ENOTSUP Option not supported: The requested option is not supported.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

Name: Description
btree(3POSIX): btree database access method
cfgetispeed(3POSIX): See tcsetattr(3POSIX)
cfgetospeed(3POSIX): See tcsetattr(3POSIX)
cfmakeraw(3POSIX): See tcsetattr(3POSIX)
cfsetispeed(3POSIX): See tcsetattr(3POSIX)
cfsetospeed(3POSIX): See tcsetattr(3POSIX)
cfsetspeed(3POSIX): See tcsetattr(3POSIX)
clock_getres(3POSIX): See clock_settime(3POSIX)
clock_gettime(3POSIX): See clock_settime(3POSIX)
clock_settime(3POSIX): get or set clock to specified value, or get clock resolution
closedir(3POSIX): See directory(3POSIX)
dbopen(3POSIX): database access methods
directory(3POSIX): directory operations
endnetent(3POSIX): See getnetent(3POSIX)
endnetgrent(3POSIX): See getnetgrent(3POSIX)
endprotoent(3POSIX): See getprotoent(3POSIX)
endservent(3POSIX): See getservent(3POSIX)
err(3POSIX): formatted error messages
getcwd(3POSIX): get working directory pathname
getdiskbyname(3POSIX): get generic disk description by its name
getmntinfo(3POSIX): get information about mounted file systems
getnetbyaddr(3POSIX): See getnetent(3POSIX)
getnetbyname(3POSIX): See getnetent(3POSIX)
getnetent(3POSIX): get network entry
getnetgrent(3POSIX): netgroup database operations
getprotobyname(3POSIX): See getprotoent(3POSIX)
getprotobynumber(3POSIX): See getprotoent(3POSIX)
getprotoent(3POSIX): get protocol entry
getservbyname(3POSIX): See getservent(3POSIX)
getservbyport(3POSIX): See getservent(3POSIX)
getservent(3POSIX): get service entry
getwd(3POSIX): See getcwd(3POSIX)
glob(3POSIX): generate pathnames matching a pattern
globfree(3POSIX): See glob(3POSIX)
hash(3POSIX): hash database access method
innetgr(3POSIX): See getnetgrent(3POSIX)
link_addr(3POSIX): elementary address specification routines for link level access
link_ntoa(3POSIX): See link_addr(3POSIX)
mpool(3POSIX): shared memory buffer pool
nanosleep(3POSIX): delay the current thread with high resolution
ns_addr(3POSIX): Xerox NS address conversion routines
ns_ntoa(3POSIX): See ns_addr(3POSIX)
opendir(3POSIX): See directory(3POSIX)
pthread_attr_destroy(3POSIX): See pthread_attr_init(3POSIX)
pthread_attr_getdetachstate(3POSIX): See pthread_attr_init(3POSIX)
pthread_attr_getinheritsched(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_getschedparam(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_getschedpolicy(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_getscope(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_getstackaddr(3POSIX): See pthread_attr_init(3POSIX)
pthread_attr_getstacksize(3POSIX): See pthread_attr_init(3POSIX)
pthread_attr_init(3POSIX): Initialize a thread attribute object; Destroy a thread attribute object; Set the stacksize attribute; Get the stacksize attribute; Set the stackaddr attribute; Get the stackaddr attribute; Set the detachstate attribute; Get the detachstate attribute
pthread_attr_setdetachstate(3POSIX): See pthread_attr_init(3POSIX)
pthread_attr_setinheritsched(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_setschedparam(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_setschedpolicy(3POSIX): See pthread_attr_setscope(3POSIX)
pthread_attr_setscope(3POSIX): Set the contention scope attribute; Get the contention scope attribute; Set the scheduling inheritance attribute; Get the scheduling inheritance attribute; Set the scheduling policy attribute; Get the scheduling policy attribute; Set the scheduling parameter attribute; Get the scheduling parameter attribute
pthread_attr_setstackaddr(3POSIX): See pthread_attr_init(3POSIX)
pthread_attr_setstacksize(3POSIX): See pthread_attr_init(3POSIX)
pthread_cond_broadcast(3POSIX): See pthread_cond_init(3POSIX)
pthread_cond_destroy(3POSIX): See pthread_cond_init(3POSIX)
pthread_cond_init(3POSIX): initialize and use a condition variable
pthread_cond_signal(3POSIX): See pthread_cond_init(3POSIX)
pthread_cond_timedwait(3POSIX): See pthread_cond_init(3POSIX)
pthread_cond_wait(3POSIX): See pthread_cond_init(3POSIX)
pthread_condattr_destroy(3POSIX): See pthread_condattr_init(3POSIX)
pthread_condattr_init(3POSIX): initialize or destroy a condition variable attribute object
pthread_create(3POSIX): create a thread
pthread_equal(3POSIX): compare thread identifiers
pthread_exit(3POSIX): terminate the calling thread
pthread_getschedparam(3POSIX): See pthread_setschedparam(3POSIX)
pthread_getspecific(3POSIX): See pthread_setspecific(3POSIX)
pthread_join(3POSIX): wait for thread termination
pthread_key_create(3POSIX): create or delete a thread-specific data key
pthread_key_delete(3POSIX): See pthread_key_create(3POSIX)
pthread_kill(3POSIX): send a deletion signal to a thread
pthread_mutex_destroy(3POSIX): See pthread_mutex_init(3POSIX)
pthread_mutex_init(3POSIX): initialize and use a mutex
pthread_mutex_lock(3POSIX): See pthread_mutex_init(3POSIX)
pthread_mutex_trylock(3POSIX): See pthread_mutex_init(3POSIX)
pthread_mutex_unlock(3POSIX): See pthread_mutex_init(3POSIX)
pthread_mutexattr_destroy(3POSIX): See pthread_mutexattr_init(3POSIX)
pthread_mutexattr_init(3POSIX): initialize or destroy a mutex attribute object
pthread_once(3POSIX): initialize a library dynamically
pthread_self(3POSIX): get the identifier of the calling thread
pthread_setschedparam(3POSIX): set or get current scheduling policy and parameters of a thread
pthread_setspecific(3POSIX): set or get the thread-specific value associated with a key
pthread_yield(3POSIX): yield processor to another thread
readdir(3POSIX): See directory(3POSIX)
recno(3POSIX): record number database access method
rewinddir(3POSIX): See directory(3POSIX)
sched_get_priority_max(3POSIX): get priority and time quantum information for scheduling policy
sched_get_priority_min(3POSIX): See sched_get_priority_max(3POSIX)
sched_rr_get_interval(3POSIX): See sched_get_priority_max(3POSIX)
sched_yield(3POSIX): See pthread_yield(3POSIX)
seekdir(3POSIX): See directory(3POSIX)
sem_destroy(3POSIX): See sem_init(3POSIX)
sem_getvalue(3POSIX): See sem_init(3POSIX)
sem_init(3POSIX): initialize and use a semaphore
sem_post(3POSIX): See sem_init(3POSIX)
sem_trywait(3POSIX): See sem_init(3POSIX)
sem_wait(3POSIX): See sem_init(3POSIX)
setnetent(3POSIX): See getnetent(3POSIX)
setnetgrent(3POSIX): See getnetgrent(3POSIX)
setprotoent(3POSIX): See getprotoent(3POSIX)
setservent(3POSIX): See getservent(3POSIX)
sysconf(3POSIX): get configurable system variables
sysctl(3POSIX): get or set system information
sysctlbyname(3POSIX): See sysctl(3POSIX)
tcgetattr(3POSIX): See tcsetattr(3POSIX)
tcsetattr(3POSIX): manipulating the termios structure
telldir(3POSIX): See directory(3POSIX)
timer_create(3POSIX): create or delete a timer
timer_delete(3POSIX): See timer_create(3POSIX)
timer_getoverrun(3POSIX): See timer_settime(3POSIX)
timer_gettime(3POSIX): See timer_settime(3POSIX)
timer_settime(3POSIX): set and arm or disarm a timer, obtain remaining interval for an active timer, or obtain current overrun count for a timer
verr(3POSIX): See err(3POSIX)
verrx(3POSIX): See err(3POSIX)
vwarn(3POSIX): See err(3POSIX)
vwarnx(3POSIX): See err(3POSIX)
warn(3POSIX): See err(3POSIX)
warnx(3POSIX): See err(3POSIX)

ChorusOS 4.0 Last Revised December 1999