diff options
Diffstat (limited to 'usr/src/man')
| -rw-r--r-- | usr/src/man/man3c/Makefile | 57 | ||||
| -rw-r--r-- | usr/src/man/man3c/aligned_alloc.3c | 74 | ||||
| -rw-r--r-- | usr/src/man/man3c/call_once.3c | 89 | ||||
| -rw-r--r-- | usr/src/man/man3c/cnd.3c | 183 | ||||
| -rw-r--r-- | usr/src/man/man3c/mtx.3c | 216 | ||||
| -rw-r--r-- | usr/src/man/man3c/nanosleep.3c | 57 | ||||
| -rw-r--r-- | usr/src/man/man3c/quick_exit.3c | 92 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_create.3c | 90 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_current.3c | 46 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_detach.3c | 56 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_equal.3c | 56 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_exit.3c | 64 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_join.3c | 81 | ||||
| -rw-r--r-- | usr/src/man/man3c/thrd_yield.3c | 38 | ||||
| -rw-r--r-- | usr/src/man/man3c/timespec_get.3c | 81 | ||||
| -rw-r--r-- | usr/src/man/man3c/tss.3c | 151 | ||||
| -rw-r--r-- | usr/src/man/man3head/assert.h.3head | 12 | ||||
| -rw-r--r-- | usr/src/man/man3head/stddef.h.3head | 18 | ||||
| -rw-r--r-- | usr/src/man/man3head/time.h.3head | 24 | ||||
| -rw-r--r-- | usr/src/man/man5/standards.5 | 16 | ||||
| -rw-r--r-- | usr/src/man/man5/threads.5 | 434 |
21 files changed, 1682 insertions, 253 deletions
diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index 5348d83bf8..67861882e4 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -14,7 +14,7 @@ # Copyright 2013 Nexenta Systems, Inc. All rights reserved. # Copyright 2013, OmniTI Computer Consulting, Inc. All rights reserved. # Copyright 2014 Garrett D'Amore <garrett@damore.org> -# Copyright (c) 2015, Joyent, Inc. All rights reserved. +# Copyright 2016 Joyent, Inc. # include $(SRC)/Makefile.master @@ -40,6 +40,7 @@ MANFILES= __fbufsize.3c \ aiocancel.3c \ aioread.3c \ aiowait.3c \ + aligned_alloc.3c \ arc4random.3c \ assert.3c \ atexit.3c \ @@ -58,6 +59,7 @@ MANFILES= __fbufsize.3c \ bsearch.3c \ bstring.3c \ btowc.3c \ + call_once.3c \ catgets.3c \ catopen.3c \ cfgetispeed.3c \ @@ -68,6 +70,7 @@ MANFILES= __fbufsize.3c \ clock_settime.3c \ closedir.3c \ closefrom.3c \ + cnd.3c \ cond_init.3c \ confstr.3c \ crypt.3c \ @@ -249,6 +252,7 @@ MANFILES= __fbufsize.3c \ mq_setattr.3c \ mq_unlink.3c \ msync.3c \ + mtx.3c \ mutex_init.3c \ nanosleep.3c \ ndbm.3c \ @@ -362,6 +366,7 @@ MANFILES= __fbufsize.3c \ putspent.3c \ putws.3c \ qsort.3c \ + quick_exit.3c \ raise.3c \ rand.3c \ random.3c \ @@ -471,11 +476,19 @@ MANFILES= __fbufsize.3c \ thr_stksegment.3c \ thr_suspend.3c \ thr_yield.3c \ + thrd_create.3c \ + thrd_current.3c \ + thrd_detach.3c \ + thrd_equal.3c \ + thrd_exit.3c \ + thrd_join.3c \ + thrd_yield.3c \ timer_create.3c \ timer_delete.3c \ timer_settime.3c \ timeradd.3c \ timerfd_create.3c \ + timespec_get.3c \ tmpfile.3c \ tmpnam.3c \ toascii.3c \ @@ -485,6 +498,7 @@ MANFILES= __fbufsize.3c \ towupper.3c \ truncate.3c \ tsearch.3c \ + tss.3c \ ttyname.3c \ ttyslot.3c \ u8_strcmp.3c \ @@ -565,6 +579,7 @@ MANLINKS= FD_CLR.3c \ asctime.3c \ asctime_r.3c \ asprintf.3c \ + at_quick_exit.3c \ atof.3c \ atoi.3c \ atol.3c \ @@ -696,6 +711,12 @@ MANLINKS= FD_CLR.3c \ clock_getres.3c \ clock_gettime.3c \ closelog.3c \ + cnd_broadcast.3c \ + cnd_destroy.3c \ + cnd_init.3c \ + cnd_signal.3c \ + cnd_timedwait.3c \ + cnd_wait.3c \ cond_broadcast.3c \ cond_destroy.3c \ cond_reltimedwait.3c \ @@ -954,6 +975,12 @@ MANLINKS= FD_CLR.3c \ mq_timedreceive.3c \ mq_timedsend.3c \ mrand48.3c \ + mtx_destroy.3c \ + mtx_init.3c \ + mtx_lock.3c \ + mtx_timedlock.3c \ + mtx_trylock.3c \ + mtx_unlock.3c \ munlock.3c \ munlockall.3c \ mutex_consistent.3c \ @@ -1210,6 +1237,7 @@ MANLINKS= FD_CLR.3c \ thr_setconcurrency.3c \ thr_setprio.3c \ thr_setspecific.3c \ + thrd_sleep.3c \ timegm.3c \ timer_getoverrun.3c \ timer_gettime.3c \ @@ -1226,6 +1254,10 @@ MANLINKS= FD_CLR.3c \ towctrans_l.3c \ towlower_l.3c \ towupper_l.3c \ + tss_create.3c \ + tss_delete.3c \ + tss_get.3c \ + tss_set.3c \ ttyname_r.3c \ twalk.3c \ tzset.3c \ @@ -1366,6 +1398,8 @@ aiowrite.3c := LINKSRC = aioread.3c arc4random_buf.3c := LINKSRC = arc4random.3c arc4random_uniform.3c := LINKSRC = arc4random.3c +at_quick_exit.3c := LINKSRC = quick_exit.3c + atomic_add_16.3c := LINKSRC = atomic_add.3c atomic_add_16_nv.3c := LINKSRC = atomic_add.3c atomic_add_32.3c := LINKSRC = atomic_add.3c @@ -1499,6 +1533,13 @@ clock_gettime.3c := LINKSRC = clock_settime.3c fdwalk.3c := LINKSRC = closefrom.3c +cnd_broadcast.3c := LINKSRC = cnd.3c +cnd_destroy.3c := LINKSRC = cnd.3c +cnd_init.3c := LINKSRC = cnd.3c +cnd_signal.3c := LINKSRC = cnd.3c +cnd_timedwait.3c := LINKSRC = cnd.3c +cnd_wait.3c := LINKSRC = cnd.3c + cond_broadcast.3c := LINKSRC = cond_init.3c cond_destroy.3c := LINKSRC = cond_init.3c cond_reltimedwait.3c := LINKSRC = cond_init.3c @@ -1891,12 +1932,21 @@ mq_timedreceive.3c := LINKSRC = mq_receive.3c mq_reltimedsend_np.3c := LINKSRC = mq_send.3c mq_timedsend.3c := LINKSRC = mq_send.3c +mtx_destroy.3c := LINKSRC = mtx.3c +mtx_init.3c := LINKSRC = mtx.3c +mtx_lock.3c := LINKSRC = mtx.3c +mtx_timedlock.3c := LINKSRC = mtx.3c +mtx_trylock.3c := LINKSRC = mtx.3c +mtx_unlock.3c := LINKSRC = mtx.3c + mutex_consistent.3c := LINKSRC = mutex_init.3c mutex_destroy.3c := LINKSRC = mutex_init.3c mutex_lock.3c := LINKSRC = mutex_init.3c mutex_trylock.3c := LINKSRC = mutex_init.3c mutex_unlock.3c := LINKSRC = mutex_init.3c +thrd_sleep.3c := LINKSRC = nanosleep.3c + dbm_clearerr.3c := LINKSRC = ndbm.3c dbm_close.3c := LINKSRC = ndbm.3c dbm_delete.3c := LINKSRC = ndbm.3c @@ -2278,6 +2328,11 @@ tdelete.3c := LINKSRC = tsearch.3c tfind.3c := LINKSRC = tsearch.3c twalk.3c := LINKSRC = tsearch.3c +tss_create.3c := LINKSRC = tss.3c +tss_delete.3c := LINKSRC = tss.3c +tss_get.3c := LINKSRC = tss.3c +tss_set.3c := LINKSRC = tss.3c + ttyname_r.3c := LINKSRC = ttyname.3c uconv_u16tou8.3c := LINKSRC = uconv_u16tou32.3c diff --git a/usr/src/man/man3c/aligned_alloc.3c b/usr/src/man/man3c/aligned_alloc.3c new file mode 100644 index 0000000000..d3c6f43c32 --- /dev/null +++ b/usr/src/man/man3c/aligned_alloc.3c @@ -0,0 +1,74 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Mar 26, 2016" +.Dt ALIGNED_ALLOC 3C +.Os +.Sh NAME +.Nm aligned_alloc +.Nd aligned memory allocation +.Sh SYNOPSIS +.In stdlib.h +.Ft "void *" +.Fo aligned_alloc +.Fa "size_t alignment" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +The +.Fn aligned_alloc +function allocates +.Fa size +bytes aligned on the specified alignment boundary +.Fa alignment . +The value of +.Fa alignment +is constrained, it must be a power of two and it must be greater than or +equal to the size of a word on the platform. +.Sh RETURN VALUES +Upon successful completion, the +.Fn aligned_alloc +function returns a pointer to suitably aligned memory at least +.Fa size +bytes large. Otherwise, a +.Sy NULL +pointer is returned and +.Sy errno +is set to indicate the error. +.Sh ERRORS +The +.Fn aligned_alloc +function will fail if: +.Bl -tag -width Er +.It Er ENOMEM +The physical limits of the system are exceeded by +.Fa size +bytes of memory which cannot be allocated. +.It Er EAGAIN +There is not enough memory available to allocate +.Fa size +bytes of memory; but the application could try again later. +.It Er EINVAL +An invalid value for +.Fa alignment +was passed in. It is not a power of two multiple of the word size. +.El +.Sh INTERFACE STABILITY +.Sy STANDARD +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr malloc 3C , +.Xr memalgin 3C , +.Xr posix_memalign 3C , +.Xr attributes 5 diff --git a/usr/src/man/man3c/call_once.3c b/usr/src/man/man3c/call_once.3c new file mode 100644 index 0000000000..5cc1ba56a9 --- /dev/null +++ b/usr/src/man/man3c/call_once.3c @@ -0,0 +1,89 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt CALL_ONCE 3C +.Os +.Sh NAME +.Nm call_once +.Nd ensure function is only called once +.Sh SYNOPSIS +.In treads.h +.Vt "once_flag once = ONCE_FLAG_INIT;" +.Ft void +.Fo call_once +.Fa "once_flag *once" +.Fa "void (*func)(void)" +.Fc +.Sh DESCRIPTION +The +.Fn call_once +function is used to ensure that an operation occurs only once, even +across multiple threads. Each instance of a properly initialized +.Ft once_flag +can be pased to the +.Ft call_once +function; however, only a single caller will successfully execute the +specified function, +.Fa func . +This ensures that the argument +.Fa func +is called only once. Note, the argument +.Fa once +is the only thing used as a point of synchronization. If multiple +callers use the same pointer for +.Fa once , +but use different values for +.Fa func , +then only one of the functions will be successfully called. +.Pp +The argument +.Fn once +should always be initialized to the symbol +.Sy ONCE_FLAG_INIT +before calling +.Fn call_once . +Failure to do so will result in undefined behavior. +.Pp +Like +.Xr pthread_once 3C , +the +.Fn call_once +function is not itself a cancellation point; however, if the thread +calling +.Fn func +encounters a cancellation point and is cancelled, then the value pointed +to by +.Fa once +will be as though +.Fn call_once +had not been called, as +.Fn func +had not completed successfully. +.Sh RETURN VALUES +The +.Fn call_once +function does not return any values. Upon its completion, it is guaranteed that +.Fa func +will have been called at most once across the liftime of the +.Fa once +argument . +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_once 3C , +.Xr threads.h 3HEAD , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/cnd.3c b/usr/src/man/man3c/cnd.3c new file mode 100644 index 0000000000..7e2ce29d66 --- /dev/null +++ b/usr/src/man/man3c/cnd.3c @@ -0,0 +1,183 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt CND 3C +.Os +.Sh NAME +.Nm cnd +.Nm cnd_broadcast , +.Nm cnd_destroy , +.Nm cnd_init , +.Nm cnd_signal , +.Nm cnd_timedwait , +.Nm cnd_wait +.Nd C11 condition variable functions +.Sh SYNOPSIS +.In threads.h +.Ft int +.Fo cnd_init +.Fa "cnd_t *cnd" +.Fc +.Ft void +.Fo cnd_destroy +.Fa "cnd_t *cnd" +.Fc +.Ft int +.Fo cnd_broadcast +.Fa "cnd_t *cnd" +.Fc +.Ft int +.Fo cnd_signal +.Fa "cnd_t *cnd" +.Fc +.Ft int +.Fo cnd_timedwait +.Fa "cnd_t *restrict cnd" +.Fa "mtx_t *restrict mtx" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fo cnd_wait +.Fa "cnd_t *restrict cnd" +.Fa "mtx_t *restrict mtx" +.Fc +.Sh DESCRIPTION +The +.Sy cnd +family of functions implement condition variables which allow threads +within a process to wait until a condition occurs and be signaled when +it does. These functions behave similar to both the POSIX threads and +illumos threads; however, they have slightly different call signatures +and return values. For more information, see +.Xr threads 5 . +Importantly, they do not allow for inter-process synchronization. +.Ss Creating and Destroy Condition Variables +The function +.Fn cnd_init +initializes the condition variable referred to by +.Fa cnd . +The condition variable is suitable for intra-process use. Initializing +an already initialized condition variable results in undefined behavior. +.Pp +The function +.Fn cnd_destroy +destroys an initialized condition variable at which point it is illegal +to use it, though it may be initialized again. +.Ss Condition Waiting +The function +.Fn cond_wait +can be used to wait on a condition variable. A thread that waits on a +condition variable blocks until another thread signals that the +condition has changed, generally after making the condition that was +false, true. +.Pp +The function +.Fn cond_wait +atomically release the mutex pointed to by +.Fa mtx +and blocks on the condition variable +.Fa cond . +When the thread returns, it will once again be holding +.Fa mtx +and must check the current state of the condition. There is no +guarantee that another thread has not gotten in and changed the value +before being woken. In addition, a thread blocking on a condition +variable, may be woken spuriously, such as when a signal is received or +.Fn fork +is called . +.Pp +The function +.Fn cond_timedwait +allows a thread to block in a similar fashion to +.Fn cond_wait , +except that when the absolute time specified in seconds since the epoch +(based on +.Sy CLOCK_REALTIME ) +in UTC, expires, then the thread will be woken up. The timeout is +specified in +.Fa abstime . +.Ss Conditional Signaling +The +.Fn cnd_signal +and +.Fn cnd_broadcast +functions can be used to signal threads waiting on the condition variable +.Fa cnd +that they should be woken up and check the variable again. The +.Fn cnd_signal +function will only wake a single thread that is blocked on the +condition variable +.Fa cnd ; +while +.Fn cnd_broadcast +will wake up every thread waiting on the condition variable +.Fa cnd . +.Pp +A thread calling either +.Fn cnd_signal +or +.Fn cnd_broadcast +is not required to hold any of the mutexes that are associated with the +condition variable. +.Pp +If there are no threads currently blocked in the condition variable +.Fa cnd +then neither function has an effect. +.Sh RETURN VALUES +Upon successful completion, the +.Fn cond_init +function returns +.Sy thrd_success. +If insufficient memory was available, then +.Sy thrd_nomem +is returned; otherwise, if any other error occurred, +.Sy thrd_error +is returned. +.Pp +Upon successful completion, the +.Fn cond_broadcast , +.Fn cond_signal , +and +.Fn cond_wait +functions return +.Sy thrd_success . +Otherwise, they return +.Sy thrd_error +to indicate that an error occurred and they were unable to complete. +.Pp +Upon successful completion, the +.Fn cond_timedwait +function returns +.Sy thrd_success . +If +.Fa abstime +expires without being signaled, it instead returns +.Sy thrd_timedout . +Otherwise, +.Sy thrd_error +is returned to indicate an error. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr cond_braodcast 3C , +.Xr cond_destroy 3C , +.Xr cond_init 3C , +.Xr cond_signal 3C , +.Xr cond_timedwait 3C , +.Xr cond_wait 3C , +.Xr threads 3HEAD , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/mtx.3c b/usr/src/man/man3c/mtx.3c new file mode 100644 index 0000000000..7a2a89b11e --- /dev/null +++ b/usr/src/man/man3c/mtx.3c @@ -0,0 +1,216 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt MTX 3C +.Os +.Sh NAME +.Nm mtx , +.Nm mtx_destroy , +.Nm mtx_init , +.Nm mtx_lock , +.Nm mtx_timedlock , +.Nm mtx_trylock , +.Nm mtx_unlock +.Nd C11 mutex operations +.Sh SYNOPSIS +.In threads.h +.Ft int +.Fo mtx_init +.Fa "mtx_t *mtx" +.Fa "int type" +.Fc +.Ft void +.Fo mtx_destroy +.Fa "mtx_t *mtx" +.Fc +.Ft int +.Fo mtx_lock +.Fa "mtx_t *mtx" +.Fc +.Ft int +.Fo mtx_timedlock +.Fa "mtx_t *mtx" +.Fa "const struct timespec *restrict ts" +.Fc +.Ft int +.Fo mtx_trylock +.Fa "mtx_t *mtx" +.Fc +.Ft int +.Fo mtx_unlock +.Fa "mtx_t *mtx" +.Fc +.Sh DESCRIPTION +The +.Sy mtx +family of functions implement mutual exclusion locks (mutexes) and behave +similarly to both POSIX threads and illumos threads; however, they have +slightly different call signatures and return values. For more +information, see +.Xr threads 5 . +Importantly, they do not allow for inter-process synchronization. +.Ss Creating and Destroying Mutexes +The +.Fn mtx_init +function initializes the mutex specified by +.Fa mtx . +The following types of mutexes are valid and may be specified by the +.Fa type +argument: +.Bl -tag -width Dv +.It Sy mtx_plain +A simple, intra-process mutex. +.It Sy mtx_timed +A simple, intra-process mutex, which allows timed locking operations. +.It Sy mtx_plain | mtx_recursive +An intra-process mutex that may be acquired recursively by the same +thread. It must be unlocked an equal number of times that it is locked. +.It Sy mtx_timed | mtx_recursive +An intra-process mutex that supports timed locking operations and may be +acquired recursively by the same thread. It must be unlocked an equal +number of times that it is locked. +.El +For more information on the different kind of mutexes, see +.Xr mutex_init 3C . +.Pp +The +.Fn mtx_destroy +function destroys the mutex pointed to by +.Fa mtx . +It is illegal for threads to be blocked waiting for +.Fa mtx +when +.Fn mtx_destroy +is called . +.Ss Locking and Unlocking Mutexes +The +.Fn mtx_lock +function attempts to lock the mutex +.Fa mtx . +When the function returns, it will be the sole owner of the mutex and +must call +.Fn mtx_unlock +when it is done, or risk inducing a deadlock in the process. Other +threads that make calls to +.Fn mtx_lock +after another thread has successfully completed its call to +.Fn mtx_lock +will block. +When they finally return, then they will have obtained the mutex +.Fa mtx . +.Pp +Unless a lock of type +.Sy mtx_recursive +was created, a thread calling +.Fn mtx_lock +when it already holds +.Fa mtx +will cause the thread to deadlock. Othewrise, the lock will be +successfully taken again. However, a thread must call +.Fn mtx_unlock +for each time that it has acquried +.Fa mtx . +.Pp +The +.Fn mtx_trylock +function will attempt to obtain the mutex pointed to by +.Fa mtx . +However, unlike +.Fn mtx_lock , +if +.Fa mtx +is locked, then it will not block and wait for +.Fa mtx +and instead return +.Sy thrd_busy +to indicate that the lock is currently held. +.Pp +The +.Fn mtx_timedlock +function attempts to obtain the mutex pointed to by +.Fa mtx . +If it is unable to obtain it, then it will block for a set amount of +time dictated by +.Fa ts . +The timeout in +.Fa ts +is treated as an absolute time in UTC to block until, measured based on +the +.Sy CLOCK_REALTIME +clock. +.Pp +The +.Fn mtx_unlock +function unlocks the mutex pointed to by +.Fa mtx , +which allows another thread the opportunity to obtain it. If any threads +are actively blocking on the mutex, one of them will obtain it and be +woken up. It is an error to call +.Fn mtx_unlock +on a mutex which the calling thread does not currently own. +.Sh RETURN VALUES +Upon successful completion, the function +.Fn mtx_init returns +.Sy thrd_success. +If there was insufficient memory to create the thread, +it instead returns +.Sy thrd_nomem . +If any other error occurred, it returns +.Sy thrd_error . +.Pp +The functions +.Fn mtx_lock , +and +.Fn mtx_unlock +return +.Sy thrd_success . +If they were unable to successfully complete the operation, they instead +return +.Sy thrd_error . +.Pp +Upon sucessful completion, the +.Fn mtx_timedlock +function returns +.Sy thrd_success . +If the timeout is reached and the calling thread is unable to obtain the +mutex, then +.Sy thrd_timedout +is returned . +If any other error occurs, then +.Sy thrd_error is returned. +.Pp +Upon successful completion, the +.Fn mtx_trylock +function returns +.Sy thrd_success . +If the thread was unable to obtain the mutex because another thread owns +it, then it returns +.Sy thrd_busy . +Otherwise, an error will have occurred and +.Sy thrd_error +is returned. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr mutex_init 3C , +.Xr pthread_mutex_destroy 3C , +.Xr pthread_mutex_init 3C , +.Xr pthread_mutex_lock 3C , +.Xr pthread_mutex_timedlock 3C , +.Xr pthread_mutex_trylock 3C , +.Xr pthread_mutex_unlock 3C , +.Xr threads.h 3HEAD , +.Xr attributes 5 diff --git a/usr/src/man/man3c/nanosleep.3c b/usr/src/man/man3c/nanosleep.3c index fbfc47dd45..617cc35555 100644 --- a/usr/src/man/man3c/nanosleep.3c +++ b/usr/src/man/man3c/nanosleep.3c @@ -1,5 +1,6 @@ '\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2016 Joyent, Inc. .\" Copyright 1989 AT&T .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at @@ -9,9 +10,9 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH NANOSLEEP 3C "Feb 5, 2008" +.TH NANOSLEEP 3C "Mar 27, 2016" .SH NAME -nanosleep \- high resolution sleep +nanosleep, thrd_sleep \- high resolution sleep .SH SYNOPSIS .LP .nf @@ -21,27 +22,32 @@ nanosleep \- high resolution sleep \fBstruct timespec *\fR\fIrmtp\fR); .fi +.nf +#include <threads.h> + +\fBint\fR \fBthrd_sleep\fR(\fBconst struct timespec *\fR\fIrqtp\fR, + \fBstruct timespec *\fR\fIrmtp\fR); + .SH DESCRIPTION -.sp .LP -The \fBnanosleep()\fR function causes the current thread to be suspended from -execution until either the time interval specified by the \fIrqtp\fR argument -has elapsed or a signal is delivered to the calling thread and its action is to -invoke a signal-catching function or to terminate the process. The suspension -time may be longer than requested because the argument value is rounded up to -an integer multiple of the sleep resolution or because of the scheduling of -other activity by the system. But, except for the case of being interrupted by -a signal, the suspension time will not be less than the time specified by -\fIrqtp\fR, as measured by the system clock, \fBCLOCK_REALTIME\fR. +The \fBnanosleep()\fR and \fBthrd_sleep()\fR functions cause the current thread +to be suspended from execution until either the time interval specified by the +\fIrqtp\fR argument has elapsed or a signal is delivered to the calling thread +and its action is to invoke a signal-catching function or to terminate the +process. The suspension time may be longer than requested because the argument +value is rounded up to an integer multiple of the sleep resolution or because of +the scheduling of other activity by the system. But, except for the case of +being interrupted by a signal, the suspension time will not be less than the +time specified by \fIrqtp\fR, as measured by the system clock, +\fBCLOCK_REALTIME\fR. .sp .LP -The use of the \fBnanosleep()\fR function has no effect on the action or -blockage of any signal. +The use of the \fBnanosleep()\fR and \fBthrd_sleep()\fR functions has no effect +on the action or blockage of any signal. .SH RETURN VALUES -.sp .LP -If the \fBnanosleep()\fR function returns because the requested time has -elapsed, its return value is \fB0\fR. +If the \fBnanosleep()\fR or \fBthrd_sleep()\fR function returns because the +requested time has elapsed, its return value is \fB0\fR. .sp .LP If the \fBnanosleep()\fR function returns because it has been interrupted by a @@ -55,9 +61,22 @@ returned. .LP If \fBnanosleep()\fR fails, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. -.SH ERRORS .sp .LP + +The +.B thrd_sleep() +function may fail for identical reasons as the +.B nanosleep() +function and returns \(mi1; however, the C11 standard does not define that +.B errno +should be set, therefore callers of \fBthrd_sleep()\fR cannot rely on +.B errno +being set or staying the same across a call to +.B thrd_sleep() . + +.SH ERRORS +.LP The \fBnanosleep()\fR function will fail if: .sp .ne 2 @@ -88,7 +107,6 @@ The \fBnanosleep()\fR function is not supported by this implementation. .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -108,6 +126,5 @@ Standard See \fBstandards\fR(5). .TE .SH SEE ALSO -.sp .LP \fBsleep\fR(3C), \fBtime.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/quick_exit.3c b/usr/src/man/man3c/quick_exit.3c new file mode 100644 index 0000000000..e3e17603b4 --- /dev/null +++ b/usr/src/man/man3c/quick_exit.3c @@ -0,0 +1,92 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Mar 26, 2016" +.Dt QUICK_EXIT 3C +.Os +.Sh NAME +.Nm at_quick_exit , +.Nm quick_exit +.Nd terminate a running process with minimal teardown +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fo at_quick_exit +.Fa "void (*func)(void)" +.Fc +.Ft _Noreturn void +.Fo quick_exit +.Fa "int status" +.Fc +.Sh DESCRIPTION +The +.Fn quick_exit +and +.Fn at_quick_exit +functions provide a veneer around +.Xr _Exit 3C +that allows for registered functions to be called before terminating. +Like +.Xr _Exit 3C , +standard library termination is not done. +.Xr atexit 3C +functions are not called and various standard termination that occurs +when calling +.Xr exit 3C +may not occur. +.Pp +Functions that are registered with +.Fn at_quick_exit +will be called in reverse order upon calling +.Fn quick_exit . +Functions registered with +.Fn at_quick_exit +will not be called at any other time. Functions that are registered with +.Fn at_quick_exit +should not make use of +.Xr longjump 3C +and related functions. +.Pp +After calling all registered functions, the +.Fn quick_exit +function will terminate the calling program and its exit status will be +.Fa status . +.Sh RETURN VALUES +The +.Fn quick_exit +function does not return. +.Pp +The +.Fn at_quick_exit +function returns +.Sy 0 +on success. Otherwise, a non-zero error value is returned to indicate +failure. +.Sh ERRORS +The +.Fn at_quick_exit +function may fail if: +.Bl -tag -width Er +.It Er ENOMEM +Insufficient storage space is available. +.El +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy Safe +.Sh SEE ALSO +.Xr _Exit 3C , +.Xr atexit 3C , +.Xr exit 3C , +.Xr attributes 5 , +.Xr standards 5 diff --git a/usr/src/man/man3c/thrd_create.3c b/usr/src/man/man3c/thrd_create.3c new file mode 100644 index 0000000000..ffaf9bf11c --- /dev/null +++ b/usr/src/man/man3c/thrd_create.3c @@ -0,0 +1,90 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 13, 2015" +.Dt THRD_CREATE 3C +.Os +.Sh NAME +.Nm thrd_create +.Nd create a thread +.Sh SYNOPSIS +.In threads.h +.Vt "typedef int (*thrd_start_t)(void *);" +.Ft int +.Fo thrd_create +.Fa "thrd_t *thrdp" +.Fa "thrd_start_t func" +.Fa "void *arg" +.Fc +.Sh DESCRIPTION +The +.Fn thrd_create +function creates a new thread of execution inside of the current +process and stores its identifier in +.Fa thrdp . +Each thread operates concurrently within the process. +.Pp +When a thread is created, it begins its execution at the function +.Fa func +with the argument +.Fa arg . +A created thread has access to all global data within a process; +however, it has its own private stack. Currently 32-bit processes have a +default stack of 1 megabyte, while 64-bit systems have a default stack +size of 2 megabytes. In addition, newly created threads inherit the +signal mask of the thread which created them; however, they do not +inherit any pending signals. +.Pp +Once created, a thread will continue to execute until either, it returns +from its initial function, the thread explicitly calls +.Xr thrd_exit 3C , +or the process itself terminates, such as with a call to +.Xr exit 2 . +When the initial function returns, it behaves as though a call to +.Xr thrd_exit +was made, and, if the thread has not been detached with a call to +.Xr thrd_detach, +the exit status remains available and the corresponding thread ID will +not be reused until a process calls +.Xr thrd_join 3C . +This is similar to how a parent must call +.Xr wait 2 , +to clean up a child process that has terminated. +.Pp +For a richer interface interface with more control over aspects of the +newly created thread, such as stack size, stack placement, and the like, +see +.Xr thr_create 3C +and +.Xr pthread_create 3C . +.Sh RETURN VALUES +Upon successful completion, the +.Fn thrd_create +function returns +.Sy thrd_success . +If insufficient memory was available, then +.Sy thrd_nomem +is returned. Otherwise, +.Sy thrd_error +is returned, indicating that a non-memory related error. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_create 3C , +.Xr thr_create 3C , +.Xr thrd_detach 3C , +.Xr thrd_join 3C , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/thrd_current.3c b/usr/src/man/man3c/thrd_current.3c new file mode 100644 index 0000000000..9cc41795ab --- /dev/null +++ b/usr/src/man/man3c/thrd_current.3c @@ -0,0 +1,46 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt THRD_CURRENT 3C +.Os +.Sh NAME +.Nm thrd_current +.Nd obtain current thread's ID +.Sh SYNOPSIS +.In threads.h +.Ft thrd_t +.Fo thrd_current +.Fa void +.Fc +.Sh DESCRIPTION +The +.Fn thrd_current +function returns the thread ID of the current calling thread. Note, this +ID may be different from the thread ID returned when using +.Xr thr_self 3C +or +.Xr pthread_self 3C ; +however, it still uniquely identifies the thread. +.Sh ERRORS +No errors are defined. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-Level +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_self 3C , +.Xr thr_self 3C , +.Xr thrd_create 3C , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/thrd_detach.3c b/usr/src/man/man3c/thrd_detach.3c new file mode 100644 index 0000000000..8749b53c1b --- /dev/null +++ b/usr/src/man/man3c/thrd_detach.3c @@ -0,0 +1,56 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2015, Joyent, Inc. +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 13, 2015" +.Dt THRD_DETACH 3C +.Os +.Sh NAME +.Nm thrd_detach +.Nd detach a thread +.Sh SYNOPSIS +.In threads.h +.Ft int +.Fo thrd_detach +.Fa "thrd_t thrd" +.Fc +.Sh DESCRIPTION +The +.Fn thrd_detach +function causes a thread to be considered detached from the rest of the +execution environment. While detached threads are still fully +observable, they cannot be joined with, calls to +.Fn thrd_join +will fail. In addition, if all non-detached +threads have terminated, the program will terminate; detached threads +cannot keep a program running. The act of calling +.Fn thrd_detach +on a thread does not cause it to terminate. +.Sh RETURN VALUES +Upon successful completion, the +.Xr thrd_detach +function returns +.Sy thrd_success . +Otherwise, it returns +.Sy thrd_error , +indicating that an error has occurred. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-safe +.Sh SEE ALSO +.Xr pthread_detach 3C , +.Xr thrd_create 3C , +.Xr thrd_join 3C , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/thrd_equal.3c b/usr/src/man/man3c/thrd_equal.3c new file mode 100644 index 0000000000..6c77a72138 --- /dev/null +++ b/usr/src/man/man3c/thrd_equal.3c @@ -0,0 +1,56 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt THRD_EQUAL 3C +.Os +.Sh NAME +.Nm thrd_equal +.Nd determine if threads are equal +.Sh SYNOPSIS +.In threads.h +.Ft int +.Fo thrd_equal +.Fa "thrd_t thrd0" +.Fa "thrd_t thrd1" +.Fc +.Sh DESCRIPTION +The +.Fn thrd_equal +function compares +.Fa thrd0 +and +.Fa thrd1 +and determines whether or not they refer to the same thread. +.Sh RETURN VALUES +The +.Fn thrd_equal +function returns +.Sy 0 +if +.Fa thrd0 +and +.Fa thrd1 +refer to the same thread. Otherwise, a non-zero value is returned, +indicating that +.Fa thrd0 +and +.Fa thrd1 +are different threads. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/thrd_exit.3c b/usr/src/man/man3c/thrd_exit.3c new file mode 100644 index 0000000000..3dcf682cd9 --- /dev/null +++ b/usr/src/man/man3c/thrd_exit.3c @@ -0,0 +1,64 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 13, 2015" +.Dt THRD_EXIT 3C +.Os +.Sh NAME +.Nm thrd_exit +.Nd terminate a thread +.Sh SYNOPSIS +.In threads.h +.Ft "_Noreturn void" +.Fo thrd_exit +.Fa "int res" +.Fc +.Sh DESCRIPTION +The +.Fn thrd_exit +function terminates the calling thread, in a similar way that +.Xr exit 3C +terminates the calling process. If the calling thread has not been +detached, then the exit status information provided in +.Fa res +is saved and can be retrieved by the use of the +.Xr thrd_join 3C +function. +.Pp +When the thread exits, all signals will be blocked and various +destructors and clean up handlers will be called, such as those +registered with +.Xr tss_create 3C . +The act of thread termination does not cause any process-wide resources, +such as mutexes and file descriptors to be released. +.Pp +If a thread, other than the thread in which +.Fn main +was first invoked returns from its starting routine, it will implicitly +call +.Fn thrd_exit +and set the return value to be its exit status. +.Sh RETURN VALUES +The +.Fn thrd_exit +function does not return, the calling thread is terminated. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_exit 3C , +.Xr thr_exit 3C , +.Xr attributes 5 , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/thrd_join.3c b/usr/src/man/man3c/thrd_join.3c new file mode 100644 index 0000000000..d2cb8c83ea --- /dev/null +++ b/usr/src/man/man3c/thrd_join.3c @@ -0,0 +1,81 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 13, 2015" +.Dt THRD_JOIN 3C +.Os +.Sh NAME +.Nm thrd_join +.Nd wait for thread termination +.Sh SYNOPSIS +.In threads.h +.Ft int +.Fo thrd_join +.Fa "thrd_t thrd" +.Fa "int *res" +.Fc +.Sh DESCRIPTION +The +.Fn thrd_join +function suspends the exection of the current thread and waits for the +thread indicated by +.Fa thrd +to terminate and stores the exit status, as set by a call to +.Xr thrd_exit 3C , +for that thread in +.Fa res , +if +.Fa res +is non-null. The +.Fa thrd +argument must be a member of the current process and it cannot be +detached. If +.Fa thrd +has already terminated and another caller has not called +.Fn thrd_join +then the exit status will be returned to the caller without blocking +execution of the thread. +.Pp +If multiple threads call +.Fn thrd_join +on the same thread, then both will be suspended until that thread +terminates; however, only one thread will return successfully and obtain +the actual status and the other will instead return with an error. +.Pp +For additional information on the thread joining interfaces supported by +the system, see +.Xr pthread_join 3C +and +.Xr thr_join 3C . +.Sh RETURN_VALUES +Upon successful completion, the +.Fn thrd_join +function returns +.Sy thrd_success +and if +.Fa res +is a non-null pointer, it will be filled in with the exit status of +.Xr thrd . +If an error occurs, +.Sy thrd_error +will be returned. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_join 3C , +.Xr thrd_create 3C , +.Xr thrd_detach 3C , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/thrd_yield.3c b/usr/src/man/man3c/thrd_yield.3c new file mode 100644 index 0000000000..a37ca39007 --- /dev/null +++ b/usr/src/man/man3c/thrd_yield.3c @@ -0,0 +1,38 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt THRD_YIELD 3C +.Os +.Sh NAME +.Nm thrd_yield +.Nd yield the CPU to another thread +.Sh SYNOPSIS +.In threads.h +.Ft void +.Fo thrd_yield +.Fa void +.Fc +.Sh DESCRIPTION +The +.Fn thrd_yield +function causes the current thread to yield the CPU and allow other +threads with the same or greater priority to run. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-Level +.Sy MT-Safe +.Sh SEE ALSO +.Xr yield 2 , +.Xr attributes 5 , +.Xr threads 5 diff --git a/usr/src/man/man3c/timespec_get.3c b/usr/src/man/man3c/timespec_get.3c new file mode 100644 index 0000000000..7ae55f7b55 --- /dev/null +++ b/usr/src/man/man3c/timespec_get.3c @@ -0,0 +1,81 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Mar 25, 2016" +.Dt TIMESPEC_GET 3C +.Os +.Sh NAME +.Nm timespec_get +.Nd get time information +.Sh SYNOPSIS +.In time.h +.Ft int +.Fo timespec_get +.Fa "struct timespec *ts" +.Fa "int base" +.Fc +.Sh DESCRIPTION +The +.Fn timespec_get +function provides access nanosecond resolution time. The +meaning and source of time is defined by the +.Fa base +argument. The following values are defined for +.Fa base : +.Bl -tag -width Ds +.It Sy TIME_UTC +Obtain the current time of day from the realtime clock on the system. It +represents the amount of time in second and nanoseconds since the Epoch. +This is logically equivalent to calling +.Xr clock_gettime 3C +with +.Sy CLOCK_REALTIME . +.El +.Pp +For the definition of the +.Sy timespec +structure, see +.Xr time.h 3HEAD . +.Sh RETURN VALUES +Upon successful completion, the +.Fn timespec_get +function returns the passed in value of +.Fa base . +Otherwise, +.Sy 0 +is returned to represent an error. +.Sh ERRORS +Unlike other functions, the +.Fn timespec_get +function is not defined to set +.Sy errno . +However, the +.Fn timespec_get +function will fail if: +.Bl -bullet -offset indent +.It +The value of +.Fa base +does not refer to a known time specification. +.It +There was an error obtaining the time for +.Fa base . +.El +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr clock_gettime 3C , +.Xr time.h 3HEAD , +.Xr attributes 5 diff --git a/usr/src/man/man3c/tss.3c b/usr/src/man/man3c/tss.3c new file mode 100644 index 0000000000..37ae52bd97 --- /dev/null +++ b/usr/src/man/man3c/tss.3c @@ -0,0 +1,151 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd "Jan 11, 2015" +.Dt TSS 3C +.Os +.Sh NAME +.Nm tss , +.Nm tss_create , +.Nm tss_destroy , +.Nm tss_get , +.Nm tss_set +.Nd thread-specific storage +.Sh SYNOPSIS +.In threads.h +.Vt "typedef void (*tss_dtor_t)(void *);" +.Ft int +.Fo tss_create +.Fa "tss_t *key" +.Fa "tss_dtor_t dtor" +.Fc +.Ft void +.Fo tss_delete +.Fa "tss_t key" +.Fc +.Ft void * +.Fo tss_get +.Fa "tss_t key" +.Fc +.Ft int +.Fo tss_set +.Fa "tss_t key" +.Fa "void *val" +.Fc +.Sh DESCRIPTION +The +.Sy tss +family of functions create, get, set, and destroy thread-specific +storage. +.Ss Creating and Destorying Thread-Specific Storage +The +.Fn tss_create +function creates a new thread-specific data key. The key space is opaque +and global to all threads in the process. Each thread has its own +value-space which can be mainpulated with the +.Fn tss_get +and +.Fn tss_set +functions. A given key persists until +.Fn tss_destroy +is called. +.Pp +When a key is created, the value +.Dv NULL +is associated with all current threads. When a thread is created, the +value +.Dv NULL +is assigned as the value for the entire key-space. +.Pp +A key may optionally be created with a destructor function +.Fa dtor . +The function +.Fa dtor +will run when the thread exits (see +.Xr thrd_exit 3C ) +if the value for the key is not +.Dv NULL . +The key space's destructors may be run in any order. When the destructor +is run due to a thread exiting, all signals will be blocked. +.Pp +The +.Fn tss_delete +function deletes the key identify by +.Fa key +from the global name-space. When a key is deleted, no registered +destructor is called, it is up to the calling program to free any +storage that was associated with +.Fa key +across all threads. Because of this propety, it is legal to call +.Fn tss_delete +from inside a destructor. Any destructors that had been assocaited with +.Fa key +will no longer be called when a thread terminates. +.Ss Obtaining Values +The +.Fn tss_get +function may be used to obtain the value associated with +.Fa key +for the calling thread. Note that if the calling thread has never set a +value, then it will receive the default value, +.Dv NULL . +.Fn tss_get +may be called from a tss destructor. +.Ss Setting Values +The +.Fn tss_set +function sets the value of the key +.Fa key +for the callling thread to +.Fa value , +which may be obtained by subsequent calls to +.Fa tss_get . +To remove a value for a specific thread, one may pass +.Dv NULL +in as +.Fa value . +Changing the value of a key with +.Fn tss_set +does not cause any destructors to be invoked. This means that +.Fn tss_set +may be used in the context of a destructor, but special care must be +taken to avoid leaking storage or causing an infinite loop. +.Sh RETURN VALUES +Upon successful completion, the +.Fn tss_create +and +.Fn tss_set +functions return +.Sy thrd_success . +Otherwise, they return +.Sy thrd_error +to indicate that an error occurred. +.Pp +Upon successful completion, the +.Fn tss_get +function returns the thread-specific value associated with the given +.Fa key . +If no thread-specific value is associated with the key or an invalid key +was passed in, then +.Dv NULL +is returned. +.Sh INTERFACE STABILITY +.Sy Standard +.Sh MT-LEVEL +.Sy MT-Safe +.Sh SEE ALSO +.Xr pthread_getspecific 3C , +.Xr pthread_key_create 3C , +.Xr pthread_key_delete 3C , +.Xr pthread_setspecific 3C , +.Xr attributes 5 diff --git a/usr/src/man/man3head/assert.h.3head b/usr/src/man/man3head/assert.h.3head index 864cb09e4f..3f8c8e68c6 100644 --- a/usr/src/man/man3head/assert.h.3head +++ b/usr/src/man/man3head/assert.h.3head @@ -1,4 +1,5 @@ '\" te +.\" Copyright 2016 Joyent, Inc. .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.> .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. @@ -7,7 +8,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH ASSERT.H 3HEAD "Sep 10, 2004" +.TH ASSERT.H 3HEAD "Jan 14, 2015" .SH NAME assert.h, assert \- verify program assertion .SH SYNOPSIS @@ -17,7 +18,6 @@ assert.h, assert \- verify program assertion .fi .SH DESCRIPTION -.sp .LP The <\fBassert.h\fR> header defines the \fBassert()\fR macro. It refers to the macro \fBNDEBUG\fR which is not defined in the header. If \fBNDEBUG\fR is @@ -42,9 +42,14 @@ The \fBassert()\fR macro is redefined according to the current state of The \fBassert()\fR macro is implemented as a macro, not as a function. If the macro definition is suppressed in order to access an actual function, the behavior is undefined. -.SH ATTRIBUTES .sp .LP +The <\fBassert.h\fR> header also defines the \fBstatic_assert()\fR macro. This +macros is similar to \fBassert()\fR; however, while \fBassert()\fR is used at +program execution time, \fBstatic_assert()\fR is evaluated and checked by the +compiler at compilation-time. +.SH ATTRIBUTES +.LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -59,6 +64,5 @@ Interface Stability Standard .TE .SH SEE ALSO -.sp .LP \fBassert\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3head/stddef.h.3head b/usr/src/man/man3head/stddef.h.3head index 96d56558d3..a06493bf39 100644 --- a/usr/src/man/man3head/stddef.h.3head +++ b/usr/src/man/man3head/stddef.h.3head @@ -1,4 +1,5 @@ '\" te +.\" Copyright 2016, Joyent, Inc. .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. @@ -7,7 +8,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH STDDEF.H 3HEAD "Sep 10, 2004" +.TH STDDEF.H 3HEAD "Jan 14, 2015" .SH NAME stddef.h, stddef \- standard type definitions .SH SYNOPSIS @@ -17,7 +18,6 @@ stddef.h, stddef \- standard type definitions .fi .SH DESCRIPTION -.sp .LP The <\fBstddef.h\fR> header defines the following macros: .sp @@ -77,6 +77,18 @@ Unsigned integer type of the result of the \fBsizeof\fR operator. .RE .sp +.ne 2 +.na +.B max_align_t +.ad +.RS 13n +A type that represents the maximum alignment supported by the platform. +The type may or may not be an integer type, it may or may not be signed, +no assumptions should be made, other than that it has the maximum +fundamental alignment of the platform. +.RE + +.sp .LP The implementation supports one or more programming environments in which the widths of \fBptrdiff_t\fR, \fBsize_t\fR, and \fBwchar_t\fR are no greater than @@ -84,7 +96,6 @@ the width of type \fBlong\fR. The names of these programming environments can be obtained using the \fBconfstr\fR(3C) function or the \fBgetconf\fR(1) utility. .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -100,7 +111,6 @@ Interface Stability Standard .TE .SH SEE ALSO -.sp .LP \fBgetconf\fR(1), \fBconfstr\fR(3C), \fBtypes.h\fR(3HEAD), \fBwchar.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3head/time.h.3head b/usr/src/man/man3head/time.h.3head index b739369f1e..47c349e280 100644 --- a/usr/src/man/man3head/time.h.3head +++ b/usr/src/man/man3head/time.h.3head @@ -1,6 +1,7 @@ '\" te .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. .\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2016 Joyent, Inc. .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. @@ -18,7 +19,6 @@ time.h, time \- time types .fi .SH DESCRIPTION -.sp .LP The <\fBtime.h\fR> header declares the structure \fBtm\fR, which includes the following members: @@ -143,6 +143,16 @@ implementation-defined. See \fBclock_settime\fR(3C). .RE .sp +.ne 2 +.na +\fB\fBTIME_UTC\fR\fR +.ad +.RS 19n +The identifier for the system-wide realtime clock with no time zone +translation. Used in \fBtimespec_get\fR(). +.RE + +.sp .LP The \fBclock_t\fR, \fBsize_t\fR, \fBtime_t\fR, \fBclockid_t\fR, and \fBtimer_t\fR types are defined as described in <\fBsys/types.h\fR>. See @@ -172,7 +182,6 @@ extern char *tzname[]; Inclusion of the <\fBtime.h\fR> header can make visible all symbols from the <\fBsignal.h\fR> header. .SH USAGE -.sp .LP The range [0,60] for \fBtm_sec\fR allows for the occasional leap second. .sp @@ -185,7 +194,6 @@ To obtain the number of clock ticks per second returned by the \fBtimes()\fR function, applications should call \fBsysconf(_SC_CLK_TCK)\fR. See \fBtimes\fR(2) and \fBsysconf\fR(3C). .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -203,10 +211,10 @@ Standard See \fBstandards\fR(5). .TE .SH SEE ALSO -.sp .LP \fBtime\fR(2), \fButime\fR(2), \fBclock\fR(3C), \fBctime\fR(3C), -\fBdifftime\fR(3C), \fBgetdate\fR(3C), \fBmktime\fR(3C), \fBstrftime\fR(3C), -\fBstrptime\fR(3C), \fBtypes.h\fR(3HEAD), \fBclock_settime\fR(3C), -\fBnanosleep\fR(3C), \fBtimer_create\fR(3C), \fBtimer_delete\fR(3C), -\fBtimer_settime\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +\fBdifftime\fR(3C), \fBgetdate\fR(3C), \fBmktime\fR(3C), +\fBstrftime\fR(3C), \fBstrptime\fR(3C), \fBtypes.h\fR(3HEAD), +\fBclock_settime\fR(3C), \fBnanosleep\fR(3C), \fBtimer_create\fR(3C), +\fBtimer_delete\fR(3C), \fBtimer_settime\fR(3C), \fBtimespec_get\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man5/standards.5 b/usr/src/man/man5/standards.5 index b1b1e2a730..766890ea52 100644 --- a/usr/src/man/man5/standards.5 +++ b/usr/src/man/man5/standards.5 @@ -3,13 +3,12 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH STANDARDS 5 "Nov 08, 2014" +.TH STANDARDS 5 "Jan 11, 2015" .SH NAME standards, ANSI, C, C++, ISO, POSIX, POSIX.1, POSIX.2, SUS, SUSv2, SUSv3, SVID, SVID3, XNS, XNS4, XNS5, XPG, XPG3, XPG4, XPG4v2 \- standards and specifications supported by Solaris .SH DESCRIPTION -.sp .LP Solaris 10 supports IEEE Std 1003.1 and IEEE Std 1003.2, commonly known as POSIX.1 and POSIX.2, respectively. The following table lists each version of @@ -126,7 +125,6 @@ When \fBSun Studio C++ Compiler 5.6\fR is installed, Solaris releases 2.5.1 through 10 support ISO/IEC 14882:1998 Programming Languages - C++. Unsupported features of that standard are described in the compiler README file. .SS "Utilities" -.sp .LP If the behavior required by POSIX.2, POSIX.2a, XPG4, SUS, or SUSv2 conflicts with historical Solaris utility behavior, the original Solaris version of the @@ -246,7 +244,6 @@ other directories containing binaries needed by the application .RE .SS "Feature Test Macros" -.sp .LP Feature test macros are used by applications to indicate additional sets of features that are desired beyond those specified by the C standard. If an @@ -260,12 +257,10 @@ with access to all interfaces and headers not in conflict with the specified standard. The application must define \fB__EXTENSIONS__\fR either on the compile command line or within the application source files. .SS "1989 ANSI C, 1990 ISO C, 1999 ISO C" -.sp .LP No feature test macros need to be defined to indicate that an application is a conforming C application. .SS "ANSI/ISO C++" -.sp .LP ANSI/ISO C++ does not define any feature test macros. If the standard C++ announcement macro \fB__cplusplus\fR is predefined to value 199711 or greater, @@ -281,7 +276,6 @@ test macros such as \fB_POSIX_SOURCE\fR, \fB_POSIX_C_SOURCE\fR, and \fB_XOPEN_SOURCE\fR can result in compilation errors due to conflicting requirements of standard C++ and those specifications. .SS "POSIX" -.sp .LP Applications that are intended to be conforming POSIX.1 applications must define the feature test macros specified by the standard before including any @@ -310,13 +304,11 @@ POSIX.1-2001 \fB_POSIX_C_SOURCE=200112L\fR .TE .SS "SVID3" -.sp .LP The SVID3 specification does not specify any feature test macros to indicate that an application is written to meet SVID3 requirements. The SVID3 specification was written before the C standard was completed. .SS "X/Open CAE" -.sp .LP To build or compile an application that conforms to one of the X/Open CAE specifications, use the following guidelines. Applications need not set the @@ -372,7 +364,6 @@ The application must define \fB_XOPEN_SOURCE=600\fR. .RE .SS "Compilation" -.sp .LP A POSIX.1 (1988-1996)-, XPG4-, SUS-, or SUSv2-conforming implementation must include an ANSI X3.159-1989 (ANSI C Language) standard-conforming compilation @@ -423,6 +414,9 @@ _________________________________________________________________________ _________________________________________________________________________ 1999 ISO C c99 none _________________________________________________________________________ +2011 ISO C c11 none + gcc -stdc=c11 +_________________________________________________________________________ SVID3 cc -Xt -xc99=none none _________________________________________________________________________ POSIX.1-1990 c89 _POSIX_SOURCE @@ -479,7 +473,6 @@ c99 $(getconf POSIX_V6_LP64_OFF64_CFLAGS) -D_XOPEN_SOURCE=600 \e .in -2 .SS "SUSv3" -.sp .ne 2 .na \fB\fBc99\fR\fR @@ -489,7 +482,6 @@ c99 $(getconf POSIX_V6_LP64_OFF64_CFLAGS) -D_XOPEN_SOURCE=600 \e .RE .SH SEE ALSO -.sp .LP \fBcsh\fR(1), \fBksh\fR(1), \fBsh\fR(1), \fBexec\fR(2), \fBsysconf\fR(3C), \fBsystem\fR(3C), \fBenviron\fR(5), \fBlf64\fR(5) diff --git a/usr/src/man/man5/threads.5 b/usr/src/man/man5/threads.5 index d60037ca9a..5d882e7d45 100644 --- a/usr/src/man/man5/threads.5 +++ b/usr/src/man/man5/threads.5 @@ -1,16 +1,17 @@ '\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2016 Joyent, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH THREADS 5 "Nov 11, 2008" +.TH THREADS 5 "Mar 27, 2016" .SH NAME -threads, pthreads \- POSIX pthreads and Solaris threads concepts +threads, pthreads \- POSIX pthreads, c11, and illumos threads concepts .SH SYNOPSIS .SS "POSIX" .LP .nf -cc -mt [ \fIflag\fR... ] \fIfile\fR... [ -lrt \fIlibrary\fR... ] +gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] .fi .LP @@ -18,10 +19,21 @@ cc -mt [ \fIflag\fR... ] \fIfile\fR... [ -lrt \fIlibrary\fR... ] #include <pthread.h> .fi -.SS "Solaris" +.SS "C11" .LP .nf -cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +gcc -std=c11 -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +.fi + +.LP +.nf +#include <threads.h> +.fi + +.SS "illumos" +.LP +.nf +gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] .fi .LP @@ -35,26 +47,52 @@ cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] .fi .SH DESCRIPTION +.LP +A thread is an independent source of execution within a process. Every process +is created with a single thread, which calls the +.B main +function. A process may have multiple threads, all of which are scheduled +independently by the system and may run concurrently. Threads within a process +all use the same address space and as a result can access all data in the +process; however, each thread is created with its own attributes and its own +stack. When a thread is created, it inherits the signal mask of the thread which +created it, but it has no pending signals. +.sp +.LP +All threads of execution have their own, independent life time, though it is +ultimately bounded by the life time of the process. If the process terminates +for any reason, whether due to a call to \fBexit\fR(3C), the receipt of a fatal +signal, or some other reason, then all threads within the process are +terminated. Threads may themselves exit and status information of them may be +obtained, for more information, see the \fBpthread_detach\fR(3C), +\fBpthread_join\fR(3C), and \fBpthread_exit\fR(3C) functions, and their +equivalents as described in the tables later on in the manual. .sp .LP -POSIX and Solaris threads each have their own implementation within -\fBlibc\fR(3LIB). Both implementations are interoperable, their functionality +Most hardware platforms do not have any special synchronization for data objects +which may be accessed concurrently from multiple threads of execution. To avoid +such problems, programs may use atomic operations (see \fBatomic_ops\fR(3C)) and +locking primitives, such as mutexes, readers/writer locks, condition variables, +and semaphores. Note, that depending on the hardware platform, memory +synchronization may be necesary, for more information, see \fBmembar_ops\fR(3C). +.LP +POSIX, C11, and illumos threads each have their own implementation within +\fBlibc\fR(3LIB). All implementations are interoperable, their functionality similar, and can be used within the same application. Only POSIX threads are -guaranteed to be fully portable to other POSIX-compliant environments. POSIX -and Solaris threads require different source, include files and linking -libraries. See \fBSYNOPSIS\fR. +guaranteed to be fully portable to other POSIX-compliant environments. C11 +threads are an optional part of ISO C11 and may not exist on every ISO C11 +platform. POSIX, C11, and illumos threads require different source and include +files. See \fBSYNOPSIS\fR. .SS "Similarities" -.sp .LP -Most of the POSIX and Solaris threading functions have counterparts with each +Most of the POSIX and illumos threading functions have counterparts with each other. POSIX function names, with the exception of the semaphore names, have a -"\fBpthread\fR" prefix. Function names for similar POSIX and Solaris functions -have similar endings. Typically, similar POSIX and Solaris functions have the +"\fBpthread\fR" prefix. Function names for similar POSIX and illumos functions +have similar endings. Typically, similar POSIX and illumos functions have the same number and use of arguments. .SS "Differences" -.sp .LP -POSIX pthreads and Solaris threads differ in the following ways: +POSIX pthreads and illumos threads differ in the following ways: .RS +4 .TP .ie t \(bu @@ -90,278 +128,267 @@ POSIX pthreads allow for clean-up handlers for \fBfork\fR(2) calls. .TP .ie t \(bu .el o -Solaris threads can be suspended and continued. +illumos threads can be suspended and continued. .RE .RS +4 .TP .ie t \(bu .el o -Solaris threads implement daemon threads, for whose demise the process does not +illumos threads implement daemon threads, for whose demise the process does not wait. .RE -.SH FUNCTION COMPARISON +.SS "Comparison to C11 Threads" +.LP +C11 threads are not as functional as either POSIX or illumos threads. C11 +threads only support intra-process locking and do not have any form of +readers/writer locking or semaphores. In general, POSIX threads will be more +portable than C11 threads, all POSIX-compliant systems support pthreads; +however, not all C environments support C11 Threads. .sp .LP -The following table compares the POSIX pthreads and Solaris threads functions. -When a comparable interface is not available either in POSIX pthreads or -Solaris threads, a hyphen (\fB-\fR) appears in the column. +In addition to lacking other common synchronization primitives, the ISO/IEC +standard for C11 threads does not have rich error semantics. In an effort to not +extend the set of error numbers standardized in ISO/IEC C11, none of the +routines set errno and instead multiple distinguishable errors, aside from the +equivalent to ENOMEM and EBUSY, are all squashed into one. As such, users of the +platform are encouraged to use POSIX threads, unless a portability concern +dictates otherwise. + +.SH FUNCTION COMPARISON +.LP +The following table compares the POSIX pthreads, C11 threads, and illumos +threads functions. When a comparable interface is not available either in POSIX +pthreads, C11 threads or illumos threads, a hyphen (\fB-\fR) appears in the +column. .SS "Functions Related to Creation" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_create()\fR \fBthr_create()\fR -\fBpthread_attr_init()\fR \fB-\fR -\fBpthread_attr_setdetachstate()\fR \fB-\fR -\fBpthread_attr_getdetachstate()\fR \fB-\fR -\fBpthread_attr_setinheritsched()\fR \fB-\fR -\fBpthread_attr_getinheritsched()\fR \fB-\fR -\fBpthread_attr_setschedparam()\fR \fB-\fR -\fBpthread_attr_getschedparam()\fR \fB-\fR -\fBpthread_attr_setschedpolicy()\fR \fB-\fR -\fBpthread_attr_getschedpolicy()\fR \fB-\fR -\fBpthread_attr_setscope()\fR \fB-\fR -\fBpthread_attr_getscope()\fR \fB-\fR -\fBpthread_attr_setstackaddr()\fR \fB-\fR -\fBpthread_attr_getstackaddr()\fR \fB-\fR -\fBpthread_attr_setstacksize()\fR \fB-\fR -\fBpthread_attr_getstacksize()\fR \fB-\fR -\fBpthread_attr_getguardsize()\fR \fB-\fR -\fBpthread_attr_setguardsize()\fR \fB-\fR -\fBpthread_attr_destroy()\fR \fB-\fR -\fB-\fR \fBthr_min_stack()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_create()\fR \fBthr_create()\fR \fBthrd_create()\fR +\fBpthread_attr_init()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setdetachstate()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getdetachstate()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setinheritsched()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getinheritsched()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setschedparam()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getschedparam()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setschedpolicy()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getschedpolicy()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setscope()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getscope()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setstackaddr()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getstackaddr()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setstacksize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getstacksize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getguardsize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setguardsize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_destroy()\fR \fB-\fR \fB-\fR +\fB-\fR \fBthr_min_stack()\fR \fB-\fR .TE .SS "Functions Related to Exit" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_exit()\fR \fBthr_exit()\fR -\fBpthread_join()\fR \fBthr_join()\fR -\fBpthread_detach()\fR \fB-\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_exit()\fR \fBthr_exit()\fR \fBthrd_exit()\fR +\fBpthread_join()\fR \fBthr_join()\fR \fBthrd_join()\fR +\fBpthread_detach()\fR \fB-\fR \fBthrd_detach()\fR .TE .SS "Functions Related to Thread Specific Data" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_key_create()\fR \fBthr_keycreate()\fR -\fBpthread_setspecific()\fR \fBthr_setspecific()\fR -\fBpthread_getspecific()\fR \fBthr_getspecific()\fR -\fBpthread_key_delete()\fR \fB-\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_key_create()\fR \fBthr_keycreate()\fR \fBtss_create()\fR +\fBpthread_setspecific()\fR \fBthr_setspecific()\fR \fBtss_set()\fR +\fBpthread_getspecific()\fR \fBthr_getspecific()\fR \fBtss_get()\fR +\fBpthread_key_delete()\fR \fB-\fR \fBtss_delete()\fR .TE .SS "Functions Related to Signals" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_sigmask()\fR \fBthr_sigsetmask()\fR -\fBpthread_kill()\fR \fBthr_kill()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_sigmask()\fR \fBthr_sigsetmask()\fR \fB-\fR +\fBpthread_kill()\fR \fBthr_kill()\fR \fB-\fR .TE .SS "Functions Related to IDs" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_self()\fR \fBthr_self()\fR -\fBpthread_equal()\fR \fB-\fR -\fB-\fR \fBthr_main()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBc11\fR +\fBpthread_self()\fR \fBthr_self()\fR \fBthrd_current()\fR +\fBpthread_equal()\fR \fB-\fR \fBthrd_equal()\fR +\fB-\fR \fBthr_main()\fR \fB-\fR .TE .SS "Functions Related to Scheduling" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fB-\fR \fBthr_yield()\fR -\fB-\fR \fBthr_suspend()\fR -\fB-\fR \fBthr_continue()\fR -\fBpthread_setconcurrency()\fR \fBthr_setconcurrency()\fR -\fBpthread_getconcurrency()\fR \fBthr_getconcurrency()\fR -\fBpthread_setschedparam()\fR \fBthr_setprio()\fR -\fBpthread_setschedprio()\fR \fBthr_setprio()\fR -\fBpthread_getschedparam()\fR \fBthr_getprio()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fB-\fR \fBthr_yield()\fR \fBthrd_yield()\fR +\fB-\fR \fBthr_suspend()\fR \fB-\fR +\fB-\fR \fBthr_continue()\fR \fB-\fR +\fBpthread_setconcurrency()\fR \fBthr_setconcurrency()\fR \fB-\fR +\fBpthread_getconcurrency()\fR \fBthr_getconcurrency()\fR \fB-\fR +\fBpthread_setschedparam()\fR \fBthr_setprio()\fR \fB-\fR +\fBpthread_setschedprio()\fR \fBthr_setprio()\fR \fB-\fR +\fBpthread_getschedparam()\fR \fBthr_getprio()\fR \fB-\fR .TE .SS "Functions Related to Cancellation" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_cancel()\fR \fB-\fR -\fBpthread_setcancelstate()\fR \fB-\fR -\fBpthread_setcanceltype()\fR \fB-\fR -\fBpthread_testcancel()\fR \fB-\fR -\fBpthread_cleanup_pop()\fR \fB-\fR -\fBpthread_cleanup_push()\fR \fB-\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_cancel()\fR \fB-\fR \fB-\fR +\fBpthread_setcancelstate()\fR \fB-\fR \fB-\fR +\fBpthread_setcanceltype()\fR \fB-\fR \fB-\fR +\fBpthread_testcancel()\fR \fB-\fR \fB-\fR +\fBpthread_cleanup_pop()\fR \fB-\fR \fB-\fR +\fBpthread_cleanup_push()\fR \fB-\fR \fB-\fR .TE .SS "Functions Related to Mutexes" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_mutex_init()\fR \fBmutex_init()\fR -\fBpthread_mutexattr_init()\fR \fB-\fR -\fBpthread_mutexattr_setpshared()\fR \fB-\fR -\fBpthread_mutexattr_getpshared()\fR \fB-\fR -\fBpthread_mutexattr_setprotocol()\fR \fB-\fR -\fBpthread_mutexattr_getprotocol()\fR \fB-\fR -\fBpthread_mutexattr_setprioceiling()\fR \fB-\fR -\fBpthread_mutexattr_getprioceiling()\fR \fB-\fR -\fBpthread_mutexattr_settype()\fR \fB-\fR -\fBpthread_mutexattr_gettype()\fR \fB-\fR -\fBpthread_mutexattr_setrobust()\fR \fB-\fR -\fBpthread_mutexattr_getrobust()\fR \fB-\fR -\fBpthread_mutexattr_destroy()\fR \fB-\fR -\fBpthread_mutex_setprioceiling()\fR \fB-\fR -\fBpthread_mutex_getprioceiling()\fR \fB-\fR -\fBpthread_mutex_lock()\fR \fBmutex_lock()\fR -\fBpthread_mutex_trylock()\fR \fBmutex_trylock()\fR -\fBpthread_mutex_unlock()\fR \fBmutex_unlock()\fR -\fBpthread_mutex_destroy()\fR \fBmutex_destroy()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBc11\fR +\fBpthread_mutex_init()\fR \fBmutex_init()\fR \fBmtx_init()\fR +\fBpthread_mutexattr_init()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setpshared()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getpshared()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setprotocol()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getprotocol()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_settype()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_gettype()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setrobust()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getrobust()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_destroy()\fR \fB-\fR \fBmtx_destroy()\fR +\fBpthread_mutex_setprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutex_getprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutex_lock()\fR \fBmutex_lock()\fR \fBmtx_lock()\fR +\fBpthread_mutex_timedlock()\fR \fB-\fR \fBmtx_timedlock()\fR +\fBpthread_mutex_trylock()\fR \fBmutex_trylock()\fR \fBmtx_trylock()\fR +\fBpthread_mutex_unlock()\fR \fBmutex_unlock()\fR \fBmtx_unlcok()\fR +\fBpthread_mutex_destroy()\fR \fBmutex_destroy()\fR \fBmtx_destroy()\fR .TE .SS "Functions Related to Condition Variables" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_cond_init()\fR \fBcond_init()\fR -\fBpthread_condattr_init()\fR \fB-\fR -\fBpthread_condattr_setpshared()\fR \fB-\fR -\fBpthread_condattr_getpshared()\fR \fB-\fR -\fBpthread_condattr_destroy()\fR \fB-\fR -\fBpthread_cond_wait()\fR \fBcond_wait()\fR -\fBpthread_cond_timedwait()\fR \fBcond_timedwait()\fR -\fBpthread_cond_signal()\fR \fBcond_signal()\fR -\fBpthread_cond_broadcast()\fR \fBcond_broadcast()\fR -\fBpthread_cond_destroy()\fR \fBcond_destroy()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_cond_init()\fR \fBcond_init()\fR \fBcnd_init()\fR +\fBpthread_condattr_init()\fR \fB-\fR \fB-\fR +\fBpthread_condattr_setpshared()\fR \fB-\fR \fB-\fR +\fBpthread_condattr_getpshared()\fR \fB-\fR \fB-\fR +\fBpthread_condattr_destroy()\fR \fB-\fR \fB-\fR +\fBpthread_cond_wait()\fR \fBcond_wait()\fR \fBcnd_wait()\fR +\fBpthread_cond_timedwait()\fR \fBcond_timedwait()\fR \fBcond_timedwait()\fR +\fBpthread_cond_signal()\fR \fBcond_signal()\fR \fBcnd_signal()\fR +\fBpthread_cond_broadcast()\fR \fBcond_broadcast()\fR \fBcnd_broadcast()\fR +\fBpthread_cond_destroy()\fR \fBcond_destroy()\fR \fBcnd_destroy()\fR .TE .SS "Functions Related to Reader/Writer Locking" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_rwlock_init()\fR \fBrwlock_init()\fR -\fBpthread_rwlock_rdlock()\fR \fBrw_rdlock()\fR -\fBpthread_rwlock_tryrdlock()\fR \fBrw_tryrdlock()\fR -\fBpthread_rwlock_wrlock()\fR \fBrw_wrlock()\fR -\fBpthread_rwlock_trywrlock()\fR \fBrw_trywrlock()\fR -\fBpthread_rwlock_unlock()\fR \fBrw_unlock()\fR -\fBpthread_rwlock_destroy()\fR \fBrwlock_destroy()\fR -\fBpthread_rwlockattr_init()\fR \fB-\fR -\fBpthread_rwlockattr_destroy()\fR \fB-\fR -\fBpthread_rwlockattr_getpshared()\fR \fB-\fR -\fBpthread_rwlockattr_setpshared()\fR \fB-\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_rwlock_init()\fR \fBrwlock_init()\fR \fB-\fR +\fBpthread_rwlock_rdlock()\fR \fBrw_rdlock()\fR \fB-\fR +\fBpthread_rwlock_tryrdlock()\fR \fBrw_tryrdlock()\fR \fB-\fR +\fBpthread_rwlock_wrlock()\fR \fBrw_wrlock()\fR \fB-\fR +\fBpthread_rwlock_trywrlock()\fR \fBrw_trywrlock()\fR \fB-\fR +\fBpthread_rwlock_unlock()\fR \fBrw_unlock()\fR \fB-\fR +\fBpthread_rwlock_destroy()\fR \fBrwlock_destroy()\fR \fB-\fR +\fBpthread_rwlockattr_init()\fR \fB-\fR \fB-\fR +\fBpthread_rwlockattr_destroy()\fR \fB-\fR \fB-\fR +\fBpthread_rwlockattr_getpshared()\fR \fB-\fR \fB-\fR +\fBpthread_rwlockattr_setpshared()\fR \fB-\fR \fB-\fR .TE .SS "Functions Related to Semaphores" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBsem_init()\fR \fBsema_init()\fR -\fBsem_open()\fR \fB-\fR -\fBsem_close()\fR \fB-\fR -\fBsem_wait()\fR \fBsema_wait()\fR -\fBsem_trywait()\fR \fBsema_trywait()\fR -\fBsem_post()\fR \fBsema_post()\fR -\fBsem_getvalue()\fR \fB-\fR -\fBsem_unlink()\fR \fB-\fR -\fBsem_destroy()\fR \fBsema_destroy()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBsem_init()\fR \fBsema_init()\fR \fB-\fR +\fBsem_open()\fR \fB-\fR \fB-\fR +\fBsem_close()\fR \fB-\fR \fB-\fR +\fBsem_wait()\fR \fBsema_wait()\ \fB-\fR +\fBsem_trywait()\fR \fBsema_trywait()\fR \fB-\fR +\fBsem_post()\fR \fBsema_post()\fR \fB-\fR +\fBsem_getvalue()\fR \fB-\fR \fB-\fR +\fBsem_unlink()\fR \fB-\fR \fB-\fR +\fBsem_destroy()\fR \fBsema_destroy()\fR \fB-\fR .TE .SS "Functions Related to fork(\|) Clean Up" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_atfork()\fR \fB-\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_atfork()\fR \fB-\fR \fB-\fR .TE .SS "Functions Related to Limits" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fBpthread_once()\fR \fB-\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_once()\fR \fB-\fR \fBcall_once()\fR .TE .SS "Functions Related to Debugging" -.sp -.sp .TS -l l -l l . -\fBPOSIX\fR \fBSolaris\fR -\fB-\fR \fBthr_stksegment()\fR +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fB-\fR \fBthr_stksegment()\fR \fB-\fR .TE .SH LOCKING .SS "Synchronization" -.sp .LP Multithreaded behavior is asynchronous, and therefore, optimized for concurrent and parallel processing. As threads, always from within the same process and sometimes from multiple processes, share global data with each other, they are not guaranteed exclusive access to the shared data at any point in time. Securing mutually exclusive access to shared data requires -synchronization among the threads. Both POSIX and Solaris implement four +synchronization among the threads. Both POSIX and illumos implement four synchronization mechanisms: mutexes, condition variables, reader/writer locking -(\fIoptimized frequent-read occasional-write mutex\fR), and semaphores. +(\fIoptimized frequent-read occasional-write mutex\fR), and semaphores, where as +C11 threads only implement two mechanisms: mutexes and condition variables. .sp .LP Synchronizing multiple threads diminishes their concurrency. The coarser the grain of synchronization, that is, the larger the block of code that is locked, the lesser the concurrency. .SS "MT \fBfork()\fR" -.sp .LP If a threads program calls \fBfork\fR(2), it implicitly calls \fBfork1\fR(2), which replicates only the calling thread. Should there be any outstanding @@ -370,9 +397,8 @@ mutexes throughout the process, the application should call \fBfork()\fR. .SH SCHEDULING .SS "POSIX Threads" -.sp .LP -Solaris supports the following three POSIX scheduling policies: +illumos supports the following three POSIX scheduling policies: .sp .ne 2 .na @@ -409,7 +435,7 @@ process must have a effective user \fBID\fR of \fB0\fR. .sp .LP -In addition to the POSIX-specified scheduling policies above, Solaris also +In addition to the POSIX-specified scheduling policies above, illumos also supports these scheduling policies: .sp .ne 2 @@ -441,26 +467,27 @@ Threads are scheduled according to the Fixed-Priority Class (FX) policy as described in \fBpriocntl\fR(2). .RE -.SS "Solaris Threads" -.sp +.SS "illumos Threads" .LP Only scheduling policy supported is \fBSCHED_OTHER\fR, which is timesharing, based on the \fBTS\fR scheduling class. .SH ERRORS -.sp .LP In a multithreaded application, \fBEINTR\fR can be returned from blocking -system calls when another thread calls \fBforkall\fR(2). +system calls when another thread calls \fBforkall\fR(2). .SH USAGE .SS "\fB-mt\fR compiler option" -.sp .LP The \fB-mt\fR compiler option compiles and links for multithreaded code. It compiles source files with \(mi\fBD_REENTRANT\fR and augments the set of support libraries properly. -.SH ATTRIBUTES .sp .LP +Users of other compilers such as gcc and clang should manually set +\(mi\fBD_REENTRANT\fR on the compilation line. There are no other libraries or +flags necessary. +.SH ATTRIBUTES +.LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -475,7 +502,6 @@ MT-Level MT-Safe, Fork 1-Safe .TE .SH SEE ALSO -.sp .LP \fBcrle\fR(1), \fBfork\fR(2), \fBpriocntl\fR(2), \fBlibpthread\fR(3LIB), \fBlibrt\fR(3LIB), \fBlibthread\fR(3LIB), \fBpthread_atfork\fR(3C), |