1.\" $NetBSD: mtx.3,v 1.2 2019/04/27 10:57:11 wiz Exp $ 2.\" 3.\" Copyright (c) 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kamil Rytarowski. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 16, 2016 31.Dt MTX 3 32.Os 33.Sh NAME 34.Nm mtx 35.Nd mutex functions 36.Sh LIBRARY 37.Lb libpthread 38.Sh SYNOPSIS 39.In threads.h 40.Ft void 41.Fn mtx_destroy "mtx_t *mtx" 42.Ft int 43.Fn mtx_init "mtx_t *mtx" "int type" 44.Ft int 45.Fn mtx_lock "mtx_t *mtx" 46.Ft int 47.Fn mtx_timedlock "mtx_t *__restrict mtx" "const struct timespec *__restrict ts" 48.Ft int 49.Fn mtx_trylock "mtx_t *mtx" 50.Ft int 51.Fn mtx_unlock "mtx_t *mtx" 52.Sh DESCRIPTION 53The 54.Fn mtx_destroy 55function releases the resources of 56.Fa mtx . 57It is not allowed to block the same 58.Fa mtx 59during the 60.Fn mtx_destroy 61call. 62.Pp 63The 64.Fn mtx_init 65function initialized the 66.Fa mtx 67object uniquely identificable with the 68.Fa type 69properties. 70The allowed values of 71.Fa type 72are as follows: 73.Bl -column "mtx_plain | mtx_recursive" 74.It Sy "Type" Ta Sy "Description" 75.It Dv mtx_plain Ta basic mutex 76.It Dv mtx_timed Ta mutex with timeout support 77.It Dv mtx_plain | Dv mtx_recursive Ta basic recursive mutex 78.It Dv mtx_timed | Dv mtx_recursive Ta recursive mutex with timeout support 79.El 80.Pp 81The underlying 82.Nx 83implementation of mutex types does not distinguish between 84.Dv mtx_plain 85and 86.Dv mtx_timed , 87however portable code must keep the distinction. 88.Pp 89The 90.Fn mtx_lock 91function locks the 92.Fa mtx 93object. 94It is required to never lock the same 95.Fa mtx 96object without the 97.Dv mtx_recursive 98property multiple times. 99If the 100.Fa mtx 101object is already locked by another thread, 102the caller of 103.Fa mtx_lock 104blocks until the lock becomes available. 105.Pp 106The 107.Fn mtx_timedlock 108function tries to lock the 109.Fa mtx 110object. 111In case of blocked resource by another thread, 112this call blocks for the specified timeout in the 113.Fa ts 114argument. 115The timeout argument is 116.Dv TIME_UTC 117based time of 118.Dv timespec 119type. 120It is required to never lock the same 121.Fa mtx 122object without the 123.Dv mtx_recursive 124property multiple times. 125In portable code, a 126.Fa mtx 127object with the 128.Dv mtx_recursive 129property must be used in such a case. 130.Pp 131The 132.Fn mtx_trylock 133function call attempts to lock the 134.Fa mtx 135object. 136This function does not block if another thread already locked the 137.Fa mtx 138object, but immediately returns indicating proper status. 139.Pp 140The 141.Fn mtx_unlock 142function unlocks the 143.Fa mtx 144object. 145This call must be preceded with a matching 146.Fn mtx_lock 147call in the same thread. 148.Sh RETURN VALUES 149The 150.Fn mtx_destroy 151function returns no value. 152.Pp 153The 154.Fn mtx_init 155function returns 156.Dv thrd_success 157on success or 158.Dv thrd_error 159on failure. 160.Pp 161The 162.Fn mtx_lock 163function returns 164.Dv thrd_success 165on success or 166.Dv thrd_error 167on failure. 168.Pp 169The 170.Fn mtx_lock 171function returns 172.Dv thrd_success 173on success, 174otherwise 175.Dv thrd_timedout 176to indicate that system time has reached or exceeded the time specified in 177.Dv ts , 178or 179.Dv thrd_error 180on failure. 181.Pp 182The 183.Fn mtx_trylock 184function returns 185.Dv thrd_success 186on success, 187otherwise 188.Dv thrd_timedout 189to indicate that 190.Fa mtx 191object is already locked, or 192.Dv thrd_error 193on failure. 194.Pp 195The 196.Fn mtx_unlock 197function returns 198.Dv thrd_success 199on success, 200otherwise 201.Dv thrd_timedout 202to indicate that 203.Fa mtx 204object is already locked, or 205.Dv thrd_error 206on failure. 207.Sh SEE ALSO 208.Xr pthread_mutex 3 , 209.Xr threads 3 210.Sh STANDARDS 211The 212.Nm 213interface conforms to 214.St -isoC-2011 . 215.Sh HISTORY 216This interface first appeared in 217.Nx 9 . 218.Sh AUTHORS 219.An Kamil Rytarowski Aq Mt kamil@NetBSD.org 220