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 "February 14, 2020" 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. 60For more information, 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 Dv mtx_plain 73A simple, intra-process mutex. 74.It Dv mtx_timed 75A simple, intra-process mutex, which allows timed locking operations. 76.It Dv mtx_plain | mtx_recursive 77An intra-process mutex that may be acquired recursively by the same 78thread. 79It must be unlocked an equal number of times that it is locked. 80.It Dv mtx_timed | mtx_recursive 81An intra-process mutex that supports timed locking operations and may be 82acquired recursively by the same thread. 83It must be unlocked an equal number of times that it is locked. 84.El 85For more information on the different kind of mutexes, see 86.Xr mutex_init 3C . 87.Pp 88The 89.Fn mtx_destroy 90function destroys the mutex pointed to by 91.Fa mtx . 92It is illegal for threads to be blocked waiting for 93.Fa mtx 94when 95.Fn mtx_destroy 96is called . 97.Ss Locking and Unlocking Mutexes 98The 99.Fn mtx_lock 100function attempts to lock the mutex 101.Fa mtx . 102When the function returns, it will be the sole owner of the mutex and 103must call 104.Fn mtx_unlock 105when it is done, or risk inducing a deadlock in the process. 106Other threads that make calls to 107.Fn mtx_lock 108after another thread has successfully completed its call to 109.Fn mtx_lock 110will block. 111When they finally return, then they will have obtained the mutex 112.Fa mtx . 113.Pp 114Unless a lock of type 115.Dv mtx_recursive 116was created, a thread calling 117.Fn mtx_lock 118when it already holds 119.Fa mtx 120will cause the thread to deadlock. 121Otherwise, the lock will be successfully taken again. 122However, a thread must call 123.Fn mtx_unlock 124for each time that it has acquired 125.Fa mtx . 126.Pp 127The 128.Fn mtx_trylock 129function will attempt to obtain the mutex pointed to by 130.Fa mtx . 131However, unlike 132.Fn mtx_lock , 133if 134.Fa mtx 135is locked, then it will not block and wait for 136.Fa mtx 137and instead return 138.Dv thrd_busy 139to indicate that the lock is currently held. 140.Pp 141The 142.Fn mtx_timedlock 143function attempts to obtain the mutex pointed to by 144.Fa mtx . 145If it is unable to obtain it, then it will block for a set amount of 146time dictated by 147.Fa ts . 148The timeout in 149.Fa ts 150is treated as an absolute time in UTC to block until, measured based on 151the 152.Dv CLOCK_REALTIME 153clock. 154.Pp 155The 156.Fn mtx_unlock 157function unlocks the mutex pointed to by 158.Fa mtx , 159which allows another thread the opportunity to obtain it. 160If any threads are actively blocking on the mutex, one of them will obtain it 161and be woken up. 162It is an error to call 163.Fn mtx_unlock 164on a mutex which the calling thread does not currently own. 165.Sh RETURN VALUES 166Upon successful completion, the function 167.Fn mtx_init 168returns 169.Dv thrd_success . 170If there was insufficient memory to create the thread, 171it instead returns 172.Dv thrd_nomem . 173If any other error occurred, it returns 174.Dv thrd_error . 175.Pp 176The functions 177.Fn mtx_lock , 178and 179.Fn mtx_unlock 180return 181.Dv thrd_success . 182If they were unable to successfully complete the operation, they instead 183return 184.Dv thrd_error . 185.Pp 186Upon successful completion, the 187.Fn mtx_timedlock 188function returns 189.Dv thrd_success . 190If the timeout is reached and the calling thread is unable to obtain the 191mutex, then 192.Dv thrd_timedout 193is returned. 194If any other error occurs, then 195.Dv thrd_error 196is returned. 197.Pp 198Upon successful completion, the 199.Fn mtx_trylock 200function returns 201.Dv thrd_success . 202If the thread was unable to obtain the mutex because another thread owns 203it, then it returns 204.Dv thrd_busy . 205Otherwise, an error will have occurred and 206.Dv thrd_error 207is returned. 208.Sh INTERFACE STABILITY 209.Sy Standard 210.Sh MT-LEVEL 211.Sy MT-Safe 212.Sh SEE ALSO 213.Xr mutex_init 3C , 214.Xr pthread_mutex_destroy 3C , 215.Xr pthread_mutex_init 3C , 216.Xr pthread_mutex_lock 3C , 217.Xr pthread_mutex_timedlock 3C , 218.Xr pthread_mutex_trylock 3C , 219.Xr pthread_mutex_unlock 3C , 220.Xr threads.h 3HEAD , 221.Xr attributes 5 222