MTX(3)

MTX(3) | Library Functions Manual | MTX(3)

# NAME

`mtx` —
mutex functions

# LIBRARY

POSIX Threads Library (libpthread, -lpthread)

# SYNOPSIS

`#include <threads.h>`

void
`mtx_destroy`(mtx_t *mtx);

int
`mtx_init`(mtx_t *mtx, int type);

int
`mtx_lock`(mtx_t *mtx);

int
`mtx_timedlock`(mtx_t *__restrict mtx, const struct timespec *__restrict ts);

int
`mtx_trylock`(mtx_t *mtx);

int
`mtx_unlock`(mtx_t *mtx);

# DESCRIPTION

The `mtx_destroy`() function releases the resources of mtx. It is not allowed to block the same mtx during the `mtx_destroy`() call.

The `mtx_init`() function initialized the mtx object uniquely identificable with the type properties. The allowed values of type are as follows:

Type | Description
`mtx_plain` | basic mutex
`mtx_timed` | mutex with timeout support
`mtx_plain` | `mtx_recursive` | basic recursive mutex
`mtx_timed` | `mtx_recursive` | recursive mutex with timeout support

The underlying NetBSD implementation of mutex types does not distinguish between `mtx_plain` and `mtx_timed`, however portable code must keep the distinction.

The `mtx_lock`() function locks the mtx object. It is required to never lock the same mtx object without the `mtx_recursive` property multiple times. If the mtx object is already locked by another thread, the caller of mtx_lock blocks until the lock becomes available.

The `mtx_timedlock`() function tries to lock the mtx object. In case of blocked resource by another thread, this call blocks for the specified timeout in the ts argument. The timeout argument is `TIME_UTC` based time of `timespec` type. It is required to never lock the same mtx object without the `mtx_recursive` property multiple times. In portable code, a mtx object with the `mtx_recursive` property must be used in such a case.

The `mtx_trylock`() function call attempts to lock the mtx object. This function does not block if another thread already locked the mtx object, but immediately returns indicating proper status.

The `mtx_unlock`() function unlocks the mtx object. This call must be preceded with a matching `mtx_lock`() call in the same thread.

# RETURN VALUES

The `mtx_destroy`() function returns no value.

The `mtx_init`() function returns `thrd_success` on success or `thrd_error` on failure.

The `mtx_lock`() function returns `thrd_success` on success or `thrd_error` on failure.

The `mtx_lock`() function returns `thrd_success` on success, otherwise `thrd_timedout` to indicate that system time has reached or exceeded the time specified in `ts`, or `thrd_error` on failure.

The `mtx_trylock`() function returns `thrd_success` on success, otherwise `thrd_timedout` to indicate that mtx object is already locked, or `thrd_error` on failure.

The `mtx_unlock`() function returns `thrd_success` on success, otherwise `thrd_timedout` to indicate that mtx object is already locked, or `thrd_error` on failure.

# SEE ALSO

pthread_mutex(3), threads(3)

# STANDARDS

The `mtx` interface conforms to ISO/IEC 9899:2011 (“ISO C11”).

# HISTORY

This interface first appeared in NetBSD 9.

# AUTHORS

Kamil Rytarowski <kamil@NetBSD.org>

October 16, 2016 | NetBSD 9.0