Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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>

NetBSD 10.99                   October 16, 2016                   NetBSD 10.99