Differential D32243 Diff 96249 share/man/man3/pthread_mutexattr.3

Changeset View

Standalone View

View Options

share/man/man3/pthread_mutexattr.3

Show All 20 Lines

.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR

.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,

.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE

.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,

.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

.\"

.\" $FreeBSD$

.Dd August 17, 2018

.Dd October 1, 2021

.Dt PTHREAD_MUTEXATTR 3

.Os

.Sh NAME

.Nm pthread_mutexattr_init ,

.Nm pthread_mutexattr_destroy ,

.Nm pthread_mutexattr_setprioceiling ,

.Nm pthread_mutexattr_getprioceiling ,

.Nm pthread_mutexattr_setprotocol ,

.Nm pthread_mutexattr_getprotocol ,

.Nm pthread_mutexattr_setpshared ,

.Nm pthread_mutexattr_getpshared ,

.Nm pthread_mutexattr_setrobust ,

.Nm pthread_mutexattr_getrobust ,

.Nm pthread_mutexattr_settype ,

.Nm pthread_mutexattr_gettype

.Nd mutex attribute operations

.Sh LIBRARY

.Lb libpthread

.Sh SYNOPSIS

Show All 12 Lines

.Fc

.Ft int

.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"

.Ft int

.Fo pthread_mutexattr_getprotocol

.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict protocol"

.Fc

.Ft int

.Fo pthread_mutexattr_setpshared

.Fa "pthread_mutexattr_t *attr" "int shared"

.Fc

.Ft int

.Fo pthread_mutexattr_getpshared

.Fa "const pthread_mutexattr_t *attr" "int *shared"

.Fc

.Ft int

.Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust"

.Ft int

.Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust"

.Ft int

.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"

.Ft int

.Fo pthread_mutexattr_gettype

.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict type"

Show All 14 Lines

The

.Fn pthread_mutexattr_destroy

function destroys

.Fa attr .

.Pp

The

.Fn pthread_mutexattr_set*

functions set the attribute that corresponds to each function name.

.Pp

markjUnsubmitted

Done

.Fn pthread_mutexattr_setprioceiling

- function set the priority ceiling for the mutex, used

+ function sets the priority ceiling for the mutex, used

by threads executed under

markj:

The

markjUnsubmitted

Done

function set the priority ceiling for the mutex, used

- by threads executed under

+ by threads executed under the

.Dv PTHREAD_PRIO_PROTECT

markj:

.Fn pthread_mutexattr_get*

functions copy the value of the attribute that corresponds to each function name

to the location pointed to by the second function parameter.

.Sh RETURN VALUES

If successful, these functions return 0.

Otherwise, an error number is returned to indicate the error.

.Sh ERRORS

The

.Fn pthread_mutexattr_init

function will fail if:

.Bl -tag -width Er

.It Bq Er ENOMEM

Out of memory.

.El

.Pp

The

markjUnsubmitted

Done

Request priority-inheritance protocol, where the thread owning the mutex

- is executed at highest priority among priorities of all threads waiting

+ is executed at the highest priority among priorities of all threads waiting

on any mutex owned by this thread.

markj:

.Fn pthread_mutexattr_destroy

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

markjUnsubmitted

Done

Is "priority ceiling" explained anywhere? It is mentioned above with pthread_mutexattr_setprioceiling() but not really explained.

markj: Is "priority ceiling" explained anywhere? It is mentioned above with…

kibAuthorUnsubmitted

Done

Basically the sentence above is the definition of the ceiling. SUSv8 contains much more elaborate description, I am not sure that we want to copy/paste it there.

Might be in the next iteration, some text could be composed.

kib: Basically the sentence above is the definition of the ceiling. SUSv8 contains much more…

.Fa attr .

.El

.Pp

The

.Fn pthread_mutexattr_setprioceiling

markjUnsubmitted

Done

I think it should be "the robustness attribute" or something like that. Otherwise it seems like "robust" is an adjective for "attribute" and it reads strangely.

markj: I think it should be "the robustness attribute" or something like that. Otherwise it seems like…

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

.Fa attr ,

or invalid value for

.Fa prioceiling .

markjUnsubmitted

Done

"owning the mutex" and "while holding the mutex lock" are saying the same thing.

markj: "owning the mutex" and "while holding the mutex lock" are saying the same thing.

.El

markjUnsubmitted

Done

In what scenario can another thread unlock a mutex held by a terminated thread?

markj: In what scenario can another thread unlock a mutex held by a terminated thread?

kibAuthorUnsubmitted

Done

This is mostly literal text from SUSv8. For normal and default non-robust types, they state that unlocking locked but not owned mutex is UB. They also talk about an option of not storing id of the owning thread for such mutexes in rationale. It is as if they want to avoid preventing an implementation from disallowing that.

And for robust mutexes, unlock from other thread is the way in which the abandoned mutex is handled. This is described by the PTHREAD_MUTEX_ROBUST item below.

kib: This is mostly literal text from SUSv8. For normal and default non-robust types, they state…

.Pp

The

.Fn pthread_mutexattr_getprioceiling

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

.Fa attr .

.El

.Pp

The

.Fn pthread_mutexattr_setprotocol

function will fail if:

markjUnsubmitted

Done

.Xr pthread_mutex_unlock 3

- can unlock the mutex lock but also put it unreparaible state,

+ can unlock the mutex lock but also put it in an irreparable state,

where all further attempts to acquire it result in the

or "unrecoverable"

markj: or "unrecoverable"

kibAuthorUnsubmitted

Done

I believe I took the term from SUS.

kib: I believe I took the term from SUS.

markjUnsubmitted

Done

SUS seems to say "unusable"? In any case, I forgot that "unrepairable" is also an option, there was a typo in the initial version is all. I have no preference, they all seem correct.

markj: SUS seems to say "unusable"? In any case, I forgot that "unrepairable" is also an option, there…

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

.Fa attr ,

or invalid value for

.Fa protocol .

.El

.Pp

markjUnsubmitted

Done

.Fn pthread_mutexattr_settype

- sets the type of the mutex.

+ function sets the type of the mutex.

Type affects the behavior of calls which lock and unlock the mutex.

markj:

The

markjUnsubmitted

Done

"The type" or ".Va type"

markj: "The type" or ".Va type"

.Fn pthread_mutexattr_getprotocol

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

.Fa attr .

markjUnsubmitted

Done

.It PTHREAD_MUTEX_NORMAL

- Both recursive locking and unlock when the lock is not owned by the current

+ Both recursive locking and unlocking when the lock is not owned by the current

thread cause an error returned from the corresponding functions.

I'd add commas after "recursive locking" and "current thread". Otherwise it sounds like "recursive" applies to both locking and unlocking.

markj: I'd add commas after "recursive locking" and "current thread". Otherwise it sounds like…

.El

markjUnsubmitted

Done

Both recursive locking and unlock when the lock is not owned by the current

- thread cause an error returned from the corresponding functions.

+ thread cause an error to be returned from the corresponding functions.

This matches

markj:

.Pp

The

.Fn pthread_mutexattr_setpshared

markjUnsubmitted

Done

.Dv PTHREAD_MUTEX_ERRORCHECK

- but somewhat contradicts to the behavior mandated by POSIX.

+ but somewhat contradicts the behavior mandated by POSIX.

.It PTHREAD_MUTEX_ERRORCHECK

markj:

function will fail if:

.Bl -tag -width Er

markjUnsubmitted

Done

Same comment about commas.

markj: Same comment about commas.

.It Bq Er EINVAL

Invalid value for

.Fa attr ,

or invalid value for

.Fa shared .

markjUnsubmitted

Done

Attempt to unlock when current thread is not an owner of the lock results

- in an error returned.

+ in an error.

.It PTHREAD_MUTEX_DEFAULT

or "causes an error to be returned" as you wrote above.

markj: or "causes an error to be returned" as you wrote above.

.El

.Pp

The

.Fn pthread_mutexattr_getpshared

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

.Fa attr .

.El

.Pp

The

.Fn pthread_mutexattr_settype

function will fail if:

.Bl -tag -width Er

.It Bq Er EINVAL

Invalid value for

.Fa attr ,

or invalid value for

.Fa type .

Show All 37 Lines

functions conform to

.St -p1003.1-96

.Pp

The

.Fn pthread_mutexattr_setprioceiling ,

.Fn pthread_mutexattr_getprioceiling ,

.Fn pthread_mutexattr_setprotocol ,

.Fn pthread_mutexattr_getprotocol ,

.Fn pthread_mutexattr_setpshared ,

.Fn pthread_mutexattr_getpshared ,

.Fn pthread_mutexattr_settype ,

and

.Fn pthread_mutexattr_gettype

functions conform to

.St -susv2 .

The

.Fn pthread_mutexattr_setrobust

and

.Fn pthread_mutexattr_getrobust

functions conform to

.St -susv4 .