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. 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 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. 79It must be unlocked an equal number of times that it is locked. 80.It Sy 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.Sy mtx_recursive 116was created, a thread calling 117.Fn mtx_lock 118when it already holds 119.Fa mtx 120will cause the thread to deadlock. 121Othewrise, the lock will be successfully taken again. 122However, a thread must call 123.Fn mtx_unlock 124for each time that it has acquried 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.Sy 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.Sy 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 returns 168.Sy thrd_success. 169If there was insufficient memory to create the thread, 170it instead returns 171.Sy thrd_nomem . 172If any other error occurred, it returns 173.Sy thrd_error . 174.Pp 175The functions 176.Fn mtx_lock , 177and 178.Fn mtx_unlock 179return 180.Sy thrd_success . 181If they were unable to successfully complete the operation, they instead 182return 183.Sy thrd_error . 184.Pp 185Upon successful completion, the 186.Fn mtx_timedlock 187function returns 188.Sy thrd_success . 189If the timeout is reached and the calling thread is unable to obtain the 190mutex, then 191.Sy thrd_timedout 192is returned . 193If any other error occurs, then 194.Sy thrd_error is returned. 195.Pp 196Upon successful completion, the 197.Fn mtx_trylock 198function returns 199.Sy thrd_success . 200If the thread was unable to obtain the mutex because another thread owns 201it, then it returns 202.Sy thrd_busy . 203Otherwise, an error will have occurred and 204.Sy thrd_error 205is returned. 206.Sh INTERFACE STABILITY 207.Sy Standard 208.Sh MT-LEVEL 209.Sy MT-Safe 210.Sh SEE ALSO 211.Xr mutex_init 3C , 212.Xr pthread_mutex_destroy 3C , 213.Xr pthread_mutex_init 3C , 214.Xr pthread_mutex_lock 3C , 215.Xr pthread_mutex_timedlock 3C , 216.Xr pthread_mutex_trylock 3C , 217.Xr pthread_mutex_unlock 3C , 218.Xr threads.h 3HEAD , 219.Xr attributes 5 220