MTX(3)

NAME
mtx - mutex functions

LIBRARY
libpthread

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 isoC-2011.

HISTORY
This interface first appeared in NetBSD 9.

AUTHORS
Kamil Rytarowski <kamil@NetBSD.org>