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 (c) 2014, Joyent, Inc.
13.\"
14.Dd "November 8, 2020"
15.Dt PTHREAD_MUTEXATTR_GETROBUST 3C
16.Os
17.Sh NAME
18.Nm pthread_mutexattr_getrobust ,
19.Nm pthread_mutexattr_setrobust
20.Nd get and set the mutex robust attribute
21.Sh SYNOPSIS
22.In pthread.h
23.Ft int
24.Fo pthread_mutexattr_getrobust
25.Fa "const pthread_mutexattr_t *attr"
26.Fa "int *robust"
27.Fc
28.Ft int
29.Fo pthread_mutexattr_setrobust
30.Fa "pthread_mutexattr_t *attr"
31.Fa "int robust"
32.Fc
33.Sh DESCRIPTION
34The
35.Fn pthread_mutexattr_getrobust
36and
37.Fn pthread_mutexattr_setrobust
38functions obtain and set a mutex's
39.Em robust
40attribute, putting it in, or obtaining it from
41.Va robust .
42The valid values for
43.Va robust
44include:
45.Bl -tag -width Dv
46.It Sy PTHREAD_MUTEX_STALLED
47The mutex referred to by
48.Va attr
49is a traditional mutex.
50When a thread holding an intra-process lock or a process holding an
51inter-process lock crashes or terminates without unlocking the mutex, then the
52lock will be
53.Sy stalled .
54For another thread or process to obtain the lock, something else must
55unlock it.
56.It Sy PTHREAD_MUTEX_ROBUST
57The mutex referred to by
58.Va attr
59is considered a robust mutex.
60When a process holding an inter-process lock crashes or terminates without
61unlocking the mutex, the attempt to lock it will return
62.Er EOWNERDEAD .
63This allows the new owner the chance to fix the internal state and call
64.Xr pthread_mutex_consistent 3C
65prior to unlocking the lock, allowing normal operation to proceed.
66Any crashes while in this state cause the next owner to obtain
67.Er EOWNERDEAD .
68.El
69.Sh RETURN VALUES
70Upon successful completion, the
71.Fn pthread_mutexattr_getrobust
72function will return
73.Sy 0
74and update
75.Fa robust
76with the current value of the robust attribute.
77Upon successful completion, the
78.Fn pthread_mutexattr_setrobust
79function will return
80.Sy 0
81and update the robust property of the attributes pointed to by
82.Va attr
83to
84.Va robust .
85If either function fails, an error code will be returned to indicate the
86error.
87Valid errors are defined below.
88.Sh ERRORS
89The
90.Fn pthread_mutexattr_getrobust
91function will fail if:
92.Bl -tag -width Er
93.It Er EINVAL
94.Va attr
95is invalid or a null pointer,
96.Va robust
97is a null pointer.
98.El
99.Lp
100The
101.Fn pthread_mutexattr_setrobust
102function will fail if:
103.Bl -tag -width Er
104.It Er EINVAL
105.Va attr
106is invalid or a null pointer,
107.Va robust
108is not one of
109.Sy PTHREAD_MUTEX_STALLED
110or
111.Sy PTHREAD_MUTEX_ROBUST .
112.El
113.Sh INTERFACE STABILITY
114.Sy Committed
115.Sh MT-LEVEL
116.Sy MT-Safe
117.Sh SEE ALSO
118.Xr pthread_mutex_consistent 3C ,
119.Xr pthread 3HEAD ,
120.Xr libpthread 3LIB ,
121.Xr attributes 7 ,
122.Xr mutex 7
123