14521 bhyve should use error checking mutexes and check results

14522 Provide PTHREAD_{ERRORCHECK,RECURSIVE}_MUTEX_INITIALIZER_NP
Portions contributed by: Robert Mustacchi <rm@fingolfin.org>
Reviewed by: Robert Mustacchi <rm@fingolfin.org>
Reviewed by: Jason King <jason.brian.king@gmail.com>
Approved by: Dan McDonald <danmcd@joyent.com>

1 files changed, 170 insertions, 179 deletions

diff --git a/usr/src/man/man3c/pthread_mutex_init.3c b/usr/src/man/man3c/pthread_mutex_init.3c
index afaccd3574..2c34ddbe3a 100644
--- a/usr/src/man/man3c/pthread_mutex_init.3c
+++ b/usr/src/man/man3c/pthread_mutex_init.3c
@@ -43,192 +43,183 @@
 .\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association.
 .\"
-.TH PTHREAD_MUTEX_INIT 3C "Nov 11, 2008"
-.SH NAME
-pthread_mutex_init, pthread_mutex_destroy \- initialize or destroy a mutex
-.SH SYNOPSIS
-.LP
-.nf
-cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
-#include <pthread.h>
-
-\fBint\fR \fBpthread_mutex_init\fR(\fBpthread_mutex_t *restrict\fR \fImutex\fR,
-     \fBconst pthread_mutexattr_t *restrict\fR \fIattr\fR);
-.fi
-
-.LP
-.nf
-\fBint\fR \fBpthread_mutex_destroy\fR(\fBpthread_mutex_t *\fR\fImutex\fR);
-.fi
-
-.LP
-.nf
-\fBpthread_mutex_t\fR \fImutex\fR= \fBPTHREAD_MUTEX_INITIALIZER\fR;
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-The \fBpthread_mutex_init()\fR function initializes the mutex referenced by
-\fImutex\fR with attributes specified by \fIattr\fR. If \fIattr\fR is
-\fINULL\fR, the default mutex attributes are used; the effect is the same as
-passing the address of a default mutex attributes object. Upon successful
+.Dd February 18, 2022
+.Dt PTHREAD_MUTEX_INIT 3C
+.Os
+.Sh NAME
+.Nm pthread_mutex_init ,
+.Nm pthread_mutex_destroy
+.Nd initialize or destroy a mutex
+.Sh SYNOPSIS
+.In pthread.h
+.Ft int
+.Fo pthread_mutex_init
+.Fa "pthread_mutex_t *restrict mutex"
+.Fa "const pthread_mutexattr_t *restrict attr"
+.Fc
+.Ft int
+.Fo pthread_mutex_destroy
+.Fa "pthread_mutex_t *mutex"
+.Fc
+.Vt pthread_mutex_t
+.Va mutex
+.No =
+.Dv PTHREAD_MUTEX_INITIALIZER ;
+.Vt pthread_mutex_t
+.Va ecmutex
+.No =
+.Dv PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP ;
+.Vt pthread_mutex_t
+.Va rmutex
+.No =
+.Dv PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP ;
+.Sh DESCRIPTION
+The
+.Fn pthread_mutex_init
+function initializes the mutex referenced by
+.Fa mutex
+with attributes specified by
+.Fa attr .
+If
+.Fa attr
+is
+.Dv NULL ,
+the default mutex attributes are used; the effect is the same as
+passing the address of a default mutex attributes object.
+Upon successful
 initialization, the state of the mutex becomes initialized and unlocked.
-.sp
-.LP
+.Pp
 Except for robust mutexes, attempting to initialize an already initialized
 mutex results in undefined behavior.
-.sp
-.LP
-The \fBpthread_mutex_destroy()\fR function destroys the mutex object referenced
-by \fImutex\fR; the mutex object becomes, in effect, uninitialized. A destroyed
-mutex object can be re-initialized using \fBpthread_mutex_init()\fR; the
-results of otherwise referencing the object after it has been destroyed are
+.Pp
+The
+.Fn pthread_mutex_destroy
+function destroys the mutex object referenced by
+.Fa mutex ;
+the mutex object becomes, in effect, uninitialized.
+A destroyed mutex object can be re-initialized using
+.Fn pthread_mutex_init ;
+the results of otherwise referencing the object after it has been destroyed are
 undefined.
-.sp
-.LP
-It is safe to destroy an initialized mutex that is unlocked. Attempting to
-destroy a locked mutex results in undefined behavior.
-.sp
-.LP
+.Pp
+It is safe to destroy an initialized mutex that is unlocked.
+Attempting to destroy a locked mutex results in undefined behavior.
+.Pp
 In cases where default mutex attributes are appropriate, the macro
-\fBPTHREAD_MUTEX_INITIALIZER\fR can be used to initialize mutexes that are
-statically allocated. The effect is equivalent to dynamic initialization by a
-call to \fBpthread_mutex_init()\fR with parameter \fIattr\fR specified as
-\fINULL\fR, except that no error checks are performed.
-.SH RETURN VALUES
-.sp
-.LP
-If successful, the \fBpthread_mutex_init()\fR and \fBpthread_mutex_destroy()\fR
-functions return  \fB0\fR. Otherwise, an error number is returned to indicate
-the error.
-.SH ERRORS
-.sp
-.LP
-The \fBpthread_mutex_init()\fR function will fail if:
-.sp
-.ne 2
-.na
-\fB\fBEAGAIN\fR\fR
-.ad
-.RS 10n
-The system lacked the necessary resources (other than memory) to initialize
-another mutex.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEBUSY\fR\fR
-.ad
-.RS 10n
-An attempt was detected to  re-initialize a robust mutex previously initialized
-but not yet destroyed. See \fBpthread_mutexattr_setrobust\fR(3C).
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
+.Dv PTHREAD_MUTEX_INITIALIZER
+can be used to initialize mutexes that are statically allocated.
+The effect is equivalent to dynamic initialization by a call to
+.Fn pthread_mutex_init
+with parameter
+.Fa attr
+specified as
+.Dv NULL .
+.Pp
+In cases where error checking mutex attributes are appropriate, the macro
+.Dv PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP
+can be used to initialize mutexes that are statically allocated.
+The effect is equivalent to dynamic initialization by a call to
+.Fn pthread_mutex_init
+with parameter
+.Fa attr
+initialized with
+.Xr pthread_mutexattr_init 3C
+and its type set to
+.Dv PTHREAD_MUTEX_ERRORCHECK .
+.Pp
+In cases where recursive mutex attributes are appropriate, the macro
+.Dv PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP
+can be used to initialize mutexes that are statically allocated.
+The effect is equivalent to dynamic initialization by a call to
+.Fn pthread_mutex_init
+with parameter
+.Fa attr
+initialized with
+.Xr pthread_mutexattr_init 3C
+and its type set to
+.Dv PTHREAD_MUTEX_RECURSIVE .
+.Sh RETURN VALUES
+If successful, the
+.Fn pthread_mutex_init
+and
+.Fn pthread_mutex_destroy
+functions return
+.Sy 0 .
+Otherwise, an error number is returned to indicate the error.
+.Sh ERRORS
+The
+.Fn pthread_mutex_init
+function will fail if:
+.Bl -tag -width Er
+.It Er EAGAIN
+The system lacked the necessary resources
+.Pq other than memory
+to initialize another mutex.
+.It Er EBUSY
 An attempt was detected to re-initialize a robust mutex previously initialized
-with a different set of attributes. See \fBpthread_mutexattr_setrobust\fR(3C).
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENOMEM\fR\fR
-.ad
-.RS 10n
+but not yet destroyed.
+See
+.Xr pthread_mutexattr_setrobust 3C .
+.It Ev EINVAL
+An attempt was detected to re-initialize a robust mutex previously initialized
+with a different set of attributes.
+See
+.Xr pthread_mutexattr_setrobust 3C .
+.It Er ENOMEM
 Insufficient memory exists to initialize the mutex.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEPERM\fR\fR
-.ad
-.RS 10n
+.It Er EPERM
 The caller does not have the privilege to perform the operation.
-.RE
-
-.sp
-.LP
-The \fBpthread_mutex_init()\fR function may fail if:
-.sp
-.ne 2
-.na
-\fB\fBEBUSY\fR\fR
-.ad
-.RS 10n
-An attempt was detected to re-initialize the object referenced by \fImutex\fR,
+.El
+.Pp
+The
+.Fn pthread_mutex_init
+function may fail if:
+.Bl -tag -width Er
+.It Er EBUSY
+An attempt was detected to re-initialize the object referenced by
+.Fa mutex ,
 a mutex previously initialized but not yet destroyed.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
-The value specified by \fIattr\fR or \fImutex\fR is invalid.
-.RE
-
-.sp
-.LP
-The \fBpthread_mutex_destroy()\fR function may fail if:
-.sp
-.ne 2
-.na
-\fB\fBEBUSY\fR\fR
-.ad
-.RS 10n
-An attempt was detected to destroy the object referenced by \fImutex\fR while
-it is locked or referenced (for example, while being used in a
-\fBpthread_cond_wait\fR(3C) or \fBpthread_cond_timedwait\fR(3C)) by another
-thread.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
-The value specified by \fImutex\fR is invalid.
-.RE
-
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(7) for descriptions of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Interface Stability	Standard
-_
-MT-Level	MT-Safe
-.TE
-
-.SH SEE ALSO
-.sp
-.LP
-.BR pthread_cond_wait (3C),
-.BR pthread_mutex_lock (3C),
-.BR pthread_mutexattr_setprioceiling (3C),
-.BR pthread_mutexattr_setprotocol (3C),
-.BR pthread_mutexattr_setpshared (3C),
-.BR pthread_mutexattr_setrobust (3C),
-.BR pthread_mutexattr_settype (3C),
-.BR attributes (7),
-.BR mutex (7),
-.BR standards (7)
+.It Er EINVAL
+The value specified by
+.Fa attr
+or
+.Fa mutex
+is invalid.
+.El
+.Pp
+The
+.Fn pthread_mutex_destroy
+function may fail if:
+.Bl -tag -width Er
+.It Er EBUSY
+An attempt was detected to destroy the object referenced by
+.Fa mutex
+while it is locked or referenced
+.Po
+for example, while being used in a
+.Xr pthread_cond_wait 3C
+or
+.Xr pthread_cond_timedwait 3C
+.Pc
+by another thread.
+.It Er EINVAL
+The value specified by
+.Fa mutex
+is invalid.
+.El
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr pthread_cond_timedwait 3C ,
+.Xr pthread_cond_wait 3C ,
+.Xr pthread_muteattr_init 3C ,
+.Xr pthread_mutex_lock 3C ,
+.Xr pthread_mutexattr_init 3C ,
+.Xr pthread_mutexattr_setrobust 3C ,
+.Xr pthread_mutexattr_settype 3C ,
+.Xr attributes 7 ,
+.Xr mutex 7