166492cf0SYuri Pankov.\" 266492cf0SYuri Pankov.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 366492cf0SYuri Pankov.\" permission to reproduce portions of its copyrighted documentation. 466492cf0SYuri Pankov.\" Original documentation from The Open Group can be obtained online at 5c10c16deSRichard Lowe.\" http://www.opengroup.org/bookstore/. 666492cf0SYuri Pankov.\" 766492cf0SYuri Pankov.\" The Institute of Electrical and Electronics Engineers and The Open 866492cf0SYuri Pankov.\" Group, have given us permission to reprint portions of their 966492cf0SYuri Pankov.\" documentation. 1066492cf0SYuri Pankov.\" 1166492cf0SYuri Pankov.\" In the following statement, the phrase ``this text'' refers to portions 1266492cf0SYuri Pankov.\" of the system documentation. 1366492cf0SYuri Pankov.\" 1466492cf0SYuri Pankov.\" Portions of this text are reprinted and reproduced in electronic form 1566492cf0SYuri Pankov.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 1666492cf0SYuri Pankov.\" Standard for Information Technology -- Portable Operating System 1766492cf0SYuri Pankov.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 1866492cf0SYuri Pankov.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 1966492cf0SYuri Pankov.\" Engineers, Inc and The Open Group. In the event of any discrepancy 2066492cf0SYuri Pankov.\" between these versions and the original IEEE and The Open Group 2166492cf0SYuri Pankov.\" Standard, the original IEEE and The Open Group Standard is the referee 2266492cf0SYuri Pankov.\" document. The original Standard can be obtained online at 2366492cf0SYuri Pankov.\" http://www.opengroup.org/unix/online.html. 2466492cf0SYuri Pankov.\" 25c10c16deSRichard Lowe.\" This notice shall appear on any product containing this material. 2666492cf0SYuri Pankov.\" 2766492cf0SYuri Pankov.\" The contents of this file are subject to the terms of the 2866492cf0SYuri Pankov.\" Common Development and Distribution License (the "License"). 2966492cf0SYuri Pankov.\" You may not use this file except in compliance with the License. 3066492cf0SYuri Pankov.\" 3166492cf0SYuri Pankov.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 3266492cf0SYuri Pankov.\" or http://www.opensolaris.org/os/licensing. 3366492cf0SYuri Pankov.\" See the License for the specific language governing permissions 3466492cf0SYuri Pankov.\" and limitations under the License. 3566492cf0SYuri Pankov.\" 3666492cf0SYuri Pankov.\" When distributing Covered Code, include this CDDL HEADER in each 3766492cf0SYuri Pankov.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 3866492cf0SYuri Pankov.\" If applicable, add the following below this CDDL HEADER, with the 3966492cf0SYuri Pankov.\" fields enclosed by brackets "[]" replaced with your own identifying 4066492cf0SYuri Pankov.\" information: Portions Copyright [yyyy] [name of copyright owner] 4166492cf0SYuri Pankov.\" 4266492cf0SYuri Pankov.\" 4366492cf0SYuri Pankov.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. 4466492cf0SYuri Pankov.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. 4566492cf0SYuri Pankov.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 467bb0eb34SAndy Fiddaman.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association. 4766492cf0SYuri Pankov.\" 48*4a8d6d7cSPeter Tribble.Dd February 17, 2023 497bb0eb34SAndy Fiddaman.Dt PTHREAD_MUTEX_INIT 3C 507bb0eb34SAndy Fiddaman.Os 517bb0eb34SAndy Fiddaman.Sh NAME 527bb0eb34SAndy Fiddaman.Nm pthread_mutex_init , 537bb0eb34SAndy Fiddaman.Nm pthread_mutex_destroy 547bb0eb34SAndy Fiddaman.Nd initialize or destroy a mutex 557bb0eb34SAndy Fiddaman.Sh SYNOPSIS 567bb0eb34SAndy Fiddaman.In pthread.h 577bb0eb34SAndy Fiddaman.Ft int 587bb0eb34SAndy Fiddaman.Fo pthread_mutex_init 597bb0eb34SAndy Fiddaman.Fa "pthread_mutex_t *restrict mutex" 607bb0eb34SAndy Fiddaman.Fa "const pthread_mutexattr_t *restrict attr" 617bb0eb34SAndy Fiddaman.Fc 627bb0eb34SAndy Fiddaman.Ft int 637bb0eb34SAndy Fiddaman.Fo pthread_mutex_destroy 647bb0eb34SAndy Fiddaman.Fa "pthread_mutex_t *mutex" 657bb0eb34SAndy Fiddaman.Fc 667bb0eb34SAndy Fiddaman.Vt pthread_mutex_t 677bb0eb34SAndy Fiddaman.Va mutex 687bb0eb34SAndy Fiddaman.No = 697bb0eb34SAndy Fiddaman.Dv PTHREAD_MUTEX_INITIALIZER ; 707bb0eb34SAndy Fiddaman.Vt pthread_mutex_t 717bb0eb34SAndy Fiddaman.Va ecmutex 727bb0eb34SAndy Fiddaman.No = 737bb0eb34SAndy Fiddaman.Dv PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP ; 747bb0eb34SAndy Fiddaman.Vt pthread_mutex_t 757bb0eb34SAndy Fiddaman.Va rmutex 767bb0eb34SAndy Fiddaman.No = 777bb0eb34SAndy Fiddaman.Dv PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP ; 787bb0eb34SAndy Fiddaman.Sh DESCRIPTION 797bb0eb34SAndy FiddamanThe 807bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 817bb0eb34SAndy Fiddamanfunction initializes the mutex referenced by 827bb0eb34SAndy Fiddaman.Fa mutex 837bb0eb34SAndy Fiddamanwith attributes specified by 847bb0eb34SAndy Fiddaman.Fa attr . 857bb0eb34SAndy FiddamanIf 867bb0eb34SAndy Fiddaman.Fa attr 877bb0eb34SAndy Fiddamanis 887bb0eb34SAndy Fiddaman.Dv NULL , 897bb0eb34SAndy Fiddamanthe default mutex attributes are used; the effect is the same as 907bb0eb34SAndy Fiddamanpassing the address of a default mutex attributes object. 917bb0eb34SAndy FiddamanUpon successful 92c10c16deSRichard Loweinitialization, the state of the mutex becomes initialized and unlocked. 937bb0eb34SAndy Fiddaman.Pp 94c10c16deSRichard LoweExcept for robust mutexes, attempting to initialize an already initialized 95c10c16deSRichard Lowemutex results in undefined behavior. 967bb0eb34SAndy Fiddaman.Pp 977bb0eb34SAndy FiddamanThe 987bb0eb34SAndy Fiddaman.Fn pthread_mutex_destroy 997bb0eb34SAndy Fiddamanfunction destroys the mutex object referenced by 1007bb0eb34SAndy Fiddaman.Fa mutex ; 1017bb0eb34SAndy Fiddamanthe mutex object becomes, in effect, uninitialized. 1027bb0eb34SAndy FiddamanA destroyed mutex object can be re-initialized using 1037bb0eb34SAndy Fiddaman.Fn pthread_mutex_init ; 1047bb0eb34SAndy Fiddamanthe results of otherwise referencing the object after it has been destroyed are 105c10c16deSRichard Loweundefined. 1067bb0eb34SAndy Fiddaman.Pp 1077bb0eb34SAndy FiddamanIt is safe to destroy an initialized mutex that is unlocked. 1087bb0eb34SAndy FiddamanAttempting to destroy a locked mutex results in undefined behavior. 1097bb0eb34SAndy Fiddaman.Pp 110c10c16deSRichard LoweIn cases where default mutex attributes are appropriate, the macro 1117bb0eb34SAndy Fiddaman.Dv PTHREAD_MUTEX_INITIALIZER 1127bb0eb34SAndy Fiddamancan be used to initialize mutexes that are statically allocated. 1137bb0eb34SAndy FiddamanThe effect is equivalent to dynamic initialization by a call to 1147bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 1157bb0eb34SAndy Fiddamanwith parameter 1167bb0eb34SAndy Fiddaman.Fa attr 1177bb0eb34SAndy Fiddamanspecified as 1187bb0eb34SAndy Fiddaman.Dv NULL . 1197bb0eb34SAndy Fiddaman.Pp 1207bb0eb34SAndy FiddamanIn cases where error checking mutex attributes are appropriate, the macro 1217bb0eb34SAndy Fiddaman.Dv PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP 1227bb0eb34SAndy Fiddamancan be used to initialize mutexes that are statically allocated. 1237bb0eb34SAndy FiddamanThe effect is equivalent to dynamic initialization by a call to 1247bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 1257bb0eb34SAndy Fiddamanwith parameter 1267bb0eb34SAndy Fiddaman.Fa attr 1277bb0eb34SAndy Fiddamaninitialized with 1287bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_init 3C 1297bb0eb34SAndy Fiddamanand its type set to 1307bb0eb34SAndy Fiddaman.Dv PTHREAD_MUTEX_ERRORCHECK . 1317bb0eb34SAndy Fiddaman.Pp 1327bb0eb34SAndy FiddamanIn cases where recursive mutex attributes are appropriate, the macro 1337bb0eb34SAndy Fiddaman.Dv PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP 1347bb0eb34SAndy Fiddamancan be used to initialize mutexes that are statically allocated. 1357bb0eb34SAndy FiddamanThe effect is equivalent to dynamic initialization by a call to 1367bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 1377bb0eb34SAndy Fiddamanwith parameter 1387bb0eb34SAndy Fiddaman.Fa attr 1397bb0eb34SAndy Fiddamaninitialized with 1407bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_init 3C 1417bb0eb34SAndy Fiddamanand its type set to 1427bb0eb34SAndy Fiddaman.Dv PTHREAD_MUTEX_RECURSIVE . 1437bb0eb34SAndy Fiddaman.Sh RETURN VALUES 1447bb0eb34SAndy FiddamanIf successful, the 1457bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 1467bb0eb34SAndy Fiddamanand 1477bb0eb34SAndy Fiddaman.Fn pthread_mutex_destroy 1487bb0eb34SAndy Fiddamanfunctions return 1497bb0eb34SAndy Fiddaman.Sy 0 . 1507bb0eb34SAndy FiddamanOtherwise, an error number is returned to indicate the error. 1517bb0eb34SAndy Fiddaman.Sh ERRORS 1527bb0eb34SAndy FiddamanThe 1537bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 1547bb0eb34SAndy Fiddamanfunction will fail if: 1557bb0eb34SAndy Fiddaman.Bl -tag -width Er 1567bb0eb34SAndy Fiddaman.It Er EAGAIN 1577bb0eb34SAndy FiddamanThe system lacked the necessary resources 1587bb0eb34SAndy Fiddaman.Pq other than memory 1597bb0eb34SAndy Fiddamanto initialize another mutex. 1607bb0eb34SAndy Fiddaman.It Er EBUSY 161c10c16deSRichard LoweAn attempt was detected to re-initialize a robust mutex previously initialized 1627bb0eb34SAndy Fiddamanbut not yet destroyed. 1637bb0eb34SAndy FiddamanSee 1647bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_setrobust 3C . 1657bb0eb34SAndy Fiddaman.It Ev EINVAL 166c10c16deSRichard LoweAn attempt was detected to re-initialize a robust mutex previously initialized 1677bb0eb34SAndy Fiddamanwith a different set of attributes. 1687bb0eb34SAndy FiddamanSee 1697bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_setrobust 3C . 1707bb0eb34SAndy Fiddaman.It Er ENOMEM 171c10c16deSRichard LoweInsufficient memory exists to initialize the mutex. 1727bb0eb34SAndy Fiddaman.It Er EPERM 173c10c16deSRichard LoweThe caller does not have the privilege to perform the operation. 1747bb0eb34SAndy Fiddaman.El 1757bb0eb34SAndy Fiddaman.Pp 1767bb0eb34SAndy FiddamanThe 1777bb0eb34SAndy Fiddaman.Fn pthread_mutex_init 1787bb0eb34SAndy Fiddamanfunction may fail if: 1797bb0eb34SAndy Fiddaman.Bl -tag -width Er 1807bb0eb34SAndy Fiddaman.It Er EBUSY 1817bb0eb34SAndy FiddamanAn attempt was detected to re-initialize the object referenced by 1827bb0eb34SAndy Fiddaman.Fa mutex , 183c10c16deSRichard Lowea mutex previously initialized but not yet destroyed. 1847bb0eb34SAndy Fiddaman.It Er EINVAL 1857bb0eb34SAndy FiddamanThe value specified by 1867bb0eb34SAndy Fiddaman.Fa attr 1877bb0eb34SAndy Fiddamanor 1887bb0eb34SAndy Fiddaman.Fa mutex 1897bb0eb34SAndy Fiddamanis invalid. 1907bb0eb34SAndy Fiddaman.El 1917bb0eb34SAndy Fiddaman.Pp 1927bb0eb34SAndy FiddamanThe 1937bb0eb34SAndy Fiddaman.Fn pthread_mutex_destroy 1947bb0eb34SAndy Fiddamanfunction may fail if: 1957bb0eb34SAndy Fiddaman.Bl -tag -width Er 1967bb0eb34SAndy Fiddaman.It Er EBUSY 1977bb0eb34SAndy FiddamanAn attempt was detected to destroy the object referenced by 1987bb0eb34SAndy Fiddaman.Fa mutex 1997bb0eb34SAndy Fiddamanwhile it is locked or referenced 2007bb0eb34SAndy Fiddaman.Po 2017bb0eb34SAndy Fiddamanfor example, while being used in a 2027bb0eb34SAndy Fiddaman.Xr pthread_cond_wait 3C 2037bb0eb34SAndy Fiddamanor 2047bb0eb34SAndy Fiddaman.Xr pthread_cond_timedwait 3C 2057bb0eb34SAndy Fiddaman.Pc 2067bb0eb34SAndy Fiddamanby another thread. 2077bb0eb34SAndy Fiddaman.It Er EINVAL 2087bb0eb34SAndy FiddamanThe value specified by 2097bb0eb34SAndy Fiddaman.Fa mutex 2107bb0eb34SAndy Fiddamanis invalid. 2117bb0eb34SAndy Fiddaman.El 2127bb0eb34SAndy Fiddaman.Sh INTERFACE STABILITY 2137bb0eb34SAndy Fiddaman.Sy Committed 2147bb0eb34SAndy Fiddaman.Sh MT-LEVEL 2157bb0eb34SAndy Fiddaman.Sy MT-Safe 2167bb0eb34SAndy Fiddaman.Sh SEE ALSO 2177bb0eb34SAndy Fiddaman.Xr pthread_cond_timedwait 3C , 2187bb0eb34SAndy Fiddaman.Xr pthread_cond_wait 3C , 2197bb0eb34SAndy Fiddaman.Xr pthread_mutex_lock 3C , 2207bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_init 3C , 2217bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_setrobust 3C , 2227bb0eb34SAndy Fiddaman.Xr pthread_mutexattr_settype 3C , 2237bb0eb34SAndy Fiddaman.Xr attributes 7 , 2247bb0eb34SAndy Fiddaman.Xr mutex 7 225