1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2016 Joyent, Inc. 13.\" 14.Dd "Jan 11, 2015" 15.Dt MTX 3C 16.Os 17.Sh NAME 18.Nm mtx , 19.Nm mtx_destroy , 20.Nm mtx_init , 21.Nm mtx_lock , 22.Nm mtx_timedlock , 23.Nm mtx_trylock , 24.Nm mtx_unlock 25.Nd C11 mutex operations 26.Sh SYNOPSIS 27.In threads.h 28.Ft int 29.Fo mtx_init 30.Fa "mtx_t *mtx" 31.Fa "int type" 32.Fc 33.Ft void 34.Fo mtx_destroy 35.Fa "mtx_t *mtx" 36.Fc 37.Ft int 38.Fo mtx_lock 39.Fa "mtx_t *mtx" 40.Fc 41.Ft int 42.Fo mtx_timedlock 43.Fa "mtx_t *mtx" 44.Fa "const struct timespec *restrict ts" 45.Fc 46.Ft int 47.Fo mtx_trylock 48.Fa "mtx_t *mtx" 49.Fc 50.Ft int 51.Fo mtx_unlock 52.Fa "mtx_t *mtx" 53.Fc 54.Sh DESCRIPTION 55The 56.Sy mtx 57family of functions implement mutual exclusion locks (mutexes) and behave 58similarly to both POSIX threads and illumos threads; however, they have 59slightly different call signatures and return values. For more 60information, see 61.Xr threads 5 . 62Importantly, they do not allow for inter-process synchronization. 63.Ss Creating and Destroying Mutexes 64The 65.Fn mtx_init 66function initializes the mutex specified by 67.Fa mtx . 68The following types of mutexes are valid and may be specified by the 69.Fa type 70argument: 71.Bl -tag -width Dv 72.It Sy mtx_plain 73A simple, intra-process mutex. 74.It Sy mtx_timed 75A simple, intra-process mutex, which allows timed locking operations. 76.It Sy mtx_plain | mtx_recursive 77An intra-process mutex that may be acquired recursively by the same 78thread. It must be unlocked an equal number of times that it is locked. 79.It Sy mtx_timed | mtx_recursive 80An intra-process mutex that supports timed locking operations and may be 81acquired recursively by the same thread. It must be unlocked an equal 82number of times that it is locked. 83.El 84For more information on the different kind of mutexes, see 85.Xr mutex_init 3C . 86.Pp 87The 88.Fn mtx_destroy 89function destroys the mutex pointed to by 90.Fa mtx . 91It is illegal for threads to be blocked waiting for 92.Fa mtx 93when 94.Fn mtx_destroy 95is called . 96.Ss Locking and Unlocking Mutexes 97The 98.Fn mtx_lock 99function attempts to lock the mutex 100.Fa mtx . 101When the function returns, it will be the sole owner of the mutex and 102must call 103.Fn mtx_unlock 104when it is done, or risk inducing a deadlock in the process. Other 105threads that make calls to 106.Fn mtx_lock 107after another thread has successfully completed its call to 108.Fn mtx_lock 109will block. 110When they finally return, then they will have obtained the mutex 111.Fa mtx . 112.Pp 113Unless a lock of type 114.Sy mtx_recursive 115was created, a thread calling 116.Fn mtx_lock 117when it already holds 118.Fa mtx 119will cause the thread to deadlock. Othewrise, the lock will be 120successfully taken again. However, a thread must call 121.Fn mtx_unlock 122for each time that it has acquried 123.Fa mtx . 124.Pp 125The 126.Fn mtx_trylock 127function will attempt to obtain the mutex pointed to by 128.Fa mtx . 129However, unlike 130.Fn mtx_lock , 131if 132.Fa mtx 133is locked, then it will not block and wait for 134.Fa mtx 135and instead return 136.Sy thrd_busy 137to indicate that the lock is currently held. 138.Pp 139The 140.Fn mtx_timedlock 141function attempts to obtain the mutex pointed to by 142.Fa mtx . 143If it is unable to obtain it, then it will block for a set amount of 144time dictated by 145.Fa ts . 146The timeout in 147.Fa ts 148is treated as an absolute time in UTC to block until, measured based on 149the 150.Sy CLOCK_REALTIME 151clock. 152.Pp 153The 154.Fn mtx_unlock 155function unlocks the mutex pointed to by 156.Fa mtx , 157which allows another thread the opportunity to obtain it. If any threads 158are actively blocking on the mutex, one of them will obtain it and be 159woken up. It is an error to call 160.Fn mtx_unlock 161on a mutex which the calling thread does not currently own. 162.Sh RETURN VALUES 163Upon successful completion, the function 164.Fn mtx_init returns 165.Sy thrd_success. 166If there was insufficient memory to create the thread, 167it instead returns 168.Sy thrd_nomem . 169If any other error occurred, it returns 170.Sy thrd_error . 171.Pp 172The functions 173.Fn mtx_lock , 174and 175.Fn mtx_unlock 176return 177.Sy thrd_success . 178If they were unable to successfully complete the operation, they instead 179return 180.Sy thrd_error . 181.Pp 182Upon sucessful completion, the 183.Fn mtx_timedlock 184function returns 185.Sy thrd_success . 186If the timeout is reached and the calling thread is unable to obtain the 187mutex, then 188.Sy thrd_timedout 189is returned . 190If any other error occurs, then 191.Sy thrd_error is returned. 192.Pp 193Upon successful completion, the 194.Fn mtx_trylock 195function returns 196.Sy thrd_success . 197If the thread was unable to obtain the mutex because another thread owns 198it, then it returns 199.Sy thrd_busy . 200Otherwise, an error will have occurred and 201.Sy thrd_error 202is returned. 203.Sh INTERFACE STABILITY 204.Sy Standard 205.Sh MT-LEVEL 206.Sy MT-Safe 207.Sh SEE ALSO 208.Xr mutex_init 3C , 209.Xr pthread_mutex_destroy 3C , 210.Xr pthread_mutex_init 3C , 211.Xr pthread_mutex_lock 3C , 212.Xr pthread_mutex_timedlock 3C , 213.Xr pthread_mutex_trylock 3C , 214.Xr pthread_mutex_unlock 3C , 215.Xr threads.h 3HEAD , 216.Xr attributes 5 217