1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. 44.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 45.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 46.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association. 47.\" 48.Dd February 17, 2023 49.Dt PTHREAD_MUTEX_INIT 3C 50.Os 51.Sh NAME 52.Nm pthread_mutex_init , 53.Nm pthread_mutex_destroy 54.Nd initialize or destroy a mutex 55.Sh SYNOPSIS 56.In pthread.h 57.Ft int 58.Fo pthread_mutex_init 59.Fa "pthread_mutex_t *restrict mutex" 60.Fa "const pthread_mutexattr_t *restrict attr" 61.Fc 62.Ft int 63.Fo pthread_mutex_destroy 64.Fa "pthread_mutex_t *mutex" 65.Fc 66.Vt pthread_mutex_t 67.Va mutex 68.No = 69.Dv PTHREAD_MUTEX_INITIALIZER ; 70.Vt pthread_mutex_t 71.Va ecmutex 72.No = 73.Dv PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP ; 74.Vt pthread_mutex_t 75.Va rmutex 76.No = 77.Dv PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP ; 78.Sh DESCRIPTION 79The 80.Fn pthread_mutex_init 81function initializes the mutex referenced by 82.Fa mutex 83with attributes specified by 84.Fa attr . 85If 86.Fa attr 87is 88.Dv NULL , 89the default mutex attributes are used; the effect is the same as 90passing the address of a default mutex attributes object. 91Upon successful 92initialization, the state of the mutex becomes initialized and unlocked. 93.Pp 94Except for robust mutexes, attempting to initialize an already initialized 95mutex results in undefined behavior. 96.Pp 97The 98.Fn pthread_mutex_destroy 99function destroys the mutex object referenced by 100.Fa mutex ; 101the mutex object becomes, in effect, uninitialized. 102A destroyed mutex object can be re-initialized using 103.Fn pthread_mutex_init ; 104the results of otherwise referencing the object after it has been destroyed are 105undefined. 106.Pp 107It is safe to destroy an initialized mutex that is unlocked. 108Attempting to destroy a locked mutex results in undefined behavior. 109.Pp 110In cases where default mutex attributes are appropriate, the macro 111.Dv PTHREAD_MUTEX_INITIALIZER 112can be used to initialize mutexes that are statically allocated. 113The effect is equivalent to dynamic initialization by a call to 114.Fn pthread_mutex_init 115with parameter 116.Fa attr 117specified as 118.Dv NULL . 119.Pp 120In cases where error checking mutex attributes are appropriate, the macro 121.Dv PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP 122can be used to initialize mutexes that are statically allocated. 123The effect is equivalent to dynamic initialization by a call to 124.Fn pthread_mutex_init 125with parameter 126.Fa attr 127initialized with 128.Xr pthread_mutexattr_init 3C 129and its type set to 130.Dv PTHREAD_MUTEX_ERRORCHECK . 131.Pp 132In cases where recursive mutex attributes are appropriate, the macro 133.Dv PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP 134can be used to initialize mutexes that are statically allocated. 135The effect is equivalent to dynamic initialization by a call to 136.Fn pthread_mutex_init 137with parameter 138.Fa attr 139initialized with 140.Xr pthread_mutexattr_init 3C 141and its type set to 142.Dv PTHREAD_MUTEX_RECURSIVE . 143.Sh RETURN VALUES 144If successful, the 145.Fn pthread_mutex_init 146and 147.Fn pthread_mutex_destroy 148functions return 149.Sy 0 . 150Otherwise, an error number is returned to indicate the error. 151.Sh ERRORS 152The 153.Fn pthread_mutex_init 154function will fail if: 155.Bl -tag -width Er 156.It Er EAGAIN 157The system lacked the necessary resources 158.Pq other than memory 159to initialize another mutex. 160.It Er EBUSY 161An attempt was detected to re-initialize a robust mutex previously initialized 162but not yet destroyed. 163See 164.Xr pthread_mutexattr_setrobust 3C . 165.It Ev EINVAL 166An attempt was detected to re-initialize a robust mutex previously initialized 167with a different set of attributes. 168See 169.Xr pthread_mutexattr_setrobust 3C . 170.It Er ENOMEM 171Insufficient memory exists to initialize the mutex. 172.It Er EPERM 173The caller does not have the privilege to perform the operation. 174.El 175.Pp 176The 177.Fn pthread_mutex_init 178function may fail if: 179.Bl -tag -width Er 180.It Er EBUSY 181An attempt was detected to re-initialize the object referenced by 182.Fa mutex , 183a mutex previously initialized but not yet destroyed. 184.It Er EINVAL 185The value specified by 186.Fa attr 187or 188.Fa mutex 189is invalid. 190.El 191.Pp 192The 193.Fn pthread_mutex_destroy 194function may fail if: 195.Bl -tag -width Er 196.It Er EBUSY 197An attempt was detected to destroy the object referenced by 198.Fa mutex 199while it is locked or referenced 200.Po 201for example, while being used in a 202.Xr pthread_cond_wait 3C 203or 204.Xr pthread_cond_timedwait 3C 205.Pc 206by another thread. 207.It Er EINVAL 208The value specified by 209.Fa mutex 210is invalid. 211.El 212.Sh INTERFACE STABILITY 213.Sy Committed 214.Sh MT-LEVEL 215.Sy MT-Safe 216.Sh SEE ALSO 217.Xr pthread_cond_timedwait 3C , 218.Xr pthread_cond_wait 3C , 219.Xr pthread_mutex_lock 3C , 220.Xr pthread_mutexattr_init 3C , 221.Xr pthread_mutexattr_setrobust 3C , 222.Xr pthread_mutexattr_settype 3C , 223.Xr attributes 7 , 224.Xr mutex 7 225