'\" et
.TH PTHREAD_MUTEXATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
pthread_mutexattr_destroy,
pthread_mutexattr_init
\(em destroy and initialize the mutex attributes object
.SH SYNOPSIS
.LP
.nf
#include <pthread.h>
.P
int pthread_mutexattr_destroy(pthread_mutexattr_t *\fIattr\fP);
int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP);
.fi
.SH DESCRIPTION
The
\fIpthread_mutexattr_destroy\fR()
function shall destroy a mutex attributes object; the object becomes,
in effect, uninitialized. An implementation may cause
\fIpthread_mutexattr_destroy\fR()
to set the object referenced by
.IR attr
to an invalid value.
.P
A destroyed
.IR attr
attributes object can be reinitialized using
\fIpthread_mutexattr_init\fR();
the results of otherwise referencing the object after it
has been destroyed are undefined.
.P
The
\fIpthread_mutexattr_init\fR()
function shall initialize a mutex attributes object
.IR attr
with the default value for all of the attributes defined by the
implementation.
.P
Results are undefined if
\fIpthread_mutexattr_init\fR()
is called specifying an already initialized
.IR attr
attributes object.
.P
After a mutex attributes object has been used to initialize one or more
mutexes, any function affecting the attributes object (including
destruction) shall not affect any previously initialized mutexes.
.P
The behavior is undefined if the value specified by the
.IR attr
argument to
\fIpthread_mutexattr_destroy\fR()
does not refer to an initialized mutex attributes object.
.SH "RETURN VALUE"
Upon successful completion,
\fIpthread_mutexattr_destroy\fR()
and
\fIpthread_mutexattr_init\fR()
shall return zero; otherwise, an error number shall be returned to
indicate the error.
.SH ERRORS
The
\fIpthread_mutexattr_init\fR()
function shall fail if:
.TP
.BR ENOMEM
Insufficient memory exists to initialize the mutex attributes object.
.P
These functions shall not return an error code of
.BR [EINTR] .
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
If an implementation detects that the value specified by the
.IR attr
argument to
\fIpthread_mutexattr_destroy\fR()
does not refer to an initialized mutex attributes object, it is
recommended that the function should fail and report an
.BR [EINVAL] 
error.
.P
See
.IR "\fIpthread_attr_destroy\fR\^(\|)"
for a general explanation of attributes. Attributes objects allow
implementations to experiment with useful extensions and permit
extension of this volume of POSIX.1\(hy2017 without changing the existing functions. Thus, they
provide for future extensibility of this volume of POSIX.1\(hy2017 and reduce the temptation to
standardize prematurely on semantics that are not yet widely
implemented or understood.
.P
Examples of possible additional mutex attributes that have been
discussed are
.IR spin_only ,
.IR limited_spin ,
.IR no_spin ,
.IR recursive ,
and
.IR metered .
(To explain what the latter attributes might mean: recursive mutexes
would allow for multiple re-locking by the current owner; metered
mutexes would transparently keep records of queue length, wait time,
and so on.) Since there is not yet wide agreement on the usefulness of
these resulting from shared implementation and usage experience, they
are not yet specified in this volume of POSIX.1\(hy2017. Mutex attributes objects,
however, make it possible to test out these concepts for possible
standardization at a later time.
.SS "Mutex Attributes and Performance"
.P
Care has been taken to ensure that the default values of the mutex
attributes have been defined such that mutexes initialized with the
defaults have simple enough semantics so that the locking and unlocking
can be done with the equivalent of a test-and-set instruction (plus
possibly a few other basic instructions).
.P
There is at least one implementation method that can be used to reduce
the cost of testing at lock-time if a mutex has non-default
attributes. One such method that an implementation can employ (and
this can be made fully transparent to fully conforming POSIX
applications) is to secretly pre-lock any mutexes that are initialized
to non-default attributes. Any later attempt to lock such a mutex
causes the implementation to branch to the ``slow path'' as if the
mutex were unavailable; then, on the slow path, the implementation can
do the ``real work'' to lock a non-default mutex. The underlying
unlock operation is more complicated since the implementation never
really wants to release the pre-lock on this kind of mutex. This
illustrates that, depending on the hardware, there may be certain
optimizations that can be used so that whatever mutex attributes are
considered ``most frequently used'' can be processed most efficiently.
.SS "Process Shared Memory and Synchronization"
.P
The existence of memory mapping functions in this volume of POSIX.1\(hy2017 leads to the
possibility that an application may allocate the synchronization
objects from this section in memory that is accessed by multiple
processes (and therefore, by threads of multiple processes).
.P
In order to permit such usage, while at the same time keeping the usual
case (that is, usage within a single process) efficient, a
.IR process-shared
option has been defined.
.P
If an implementation supports the _POSIX_THREAD_PROCESS_SHARED
option, then the
.IR process-shared
attribute can be used to indicate that mutexes or condition variables
may be accessed by threads of multiple processes.
.P
The default setting of PTHREAD_PROCESS_PRIVATE
has been chosen for the
.IR process-shared
attribute so that the most efficient forms of these synchronization
objects are created by default.
.P
Synchronization variables that are initialized with the
PTHREAD_PROCESS_PRIVATE
.IR process-shared
attribute may only be operated on by threads in the process that
initialized them. Synchronization variables that are initialized with
the PTHREAD_PROCESS_SHARED
.IR process-shared
attribute may be operated on by any thread in any process that has
access to it. In particular, these processes may exist beyond the
lifetime of the initializing process. For example, the following code
implements a simple counting semaphore in a mapped file that may be
used by many processes.
.sp
.RS 4
.nf

/* sem.h */
struct semaphore {
    pthread_mutex_t lock;
    pthread_cond_t nonzero;
    unsigned count;
};
typedef struct semaphore semaphore_t;
.P
semaphore_t *semaphore_create(char *semaphore_name);
semaphore_t *semaphore_open(char *semaphore_name);
void semaphore_post(semaphore_t *semap);
void semaphore_wait(semaphore_t *semap);
void semaphore_close(semaphore_t *semap);
.P
/* sem.c */
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <pthread.h>
#include "sem.h"
.P
semaphore_t *
semaphore_create(char *semaphore_name)
{
int fd;
    semaphore_t *semap;
    pthread_mutexattr_t psharedm;
    pthread_condattr_t psharedc;
.P
    fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666);
    if (fd < 0)
        return (NULL);
    (void) ftruncate(fd, sizeof(semaphore_t));
    (void) pthread_mutexattr_init(&psharedm);
    (void) pthread_mutexattr_setpshared(&psharedm,
        PTHREAD_PROCESS_SHARED);
    (void) pthread_condattr_init(&psharedc);
    (void) pthread_condattr_setpshared(&psharedc,
        PTHREAD_PROCESS_SHARED);
    semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
            PROT_READ | PROT_WRITE, MAP_SHARED,
            fd, 0);
    close (fd);
    (void) pthread_mutex_init(&semap->lock, &psharedm);
    (void) pthread_cond_init(&semap->nonzero, &psharedc);
    semap->count = 0;
    return (semap);
}
.P
semaphore_t *
semaphore_open(char *semaphore_name)
{
    int fd;
    semaphore_t *semap;
.P
    fd = open(semaphore_name, O_RDWR, 0666);
    if (fd < 0)
        return (NULL);
    semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
            PROT_READ | PROT_WRITE, MAP_SHARED,
            fd, 0);
    close (fd);
    return (semap);
}
.P
void
semaphore_post(semaphore_t *semap)
{
    pthread_mutex_lock(&semap->lock);
    if (semap->count == 0)
        pthread_cond_signal(&semapx->nonzero);
    semap->count++;
    pthread_mutex_unlock(&semap->lock);
}
.P
void
semaphore_wait(semaphore_t *semap)
{
    pthread_mutex_lock(&semap->lock);
    while (semap->count == 0)
        pthread_cond_wait(&semap->nonzero, &semap->lock);
    semap->count--;
    pthread_mutex_unlock(&semap->lock);
}
.P
void
semaphore_close(semaphore_t *semap)
{
    munmap((void *) semap, sizeof(semaphore_t));
}
.fi
.P
.RE
.P
The following code is for three separate processes that create, post,
and wait on a semaphore in the file
.BR /tmp/semaphore .
Once the file is created, the post and wait programs increment and
decrement the counting semaphore (waiting and waking as required) even
though they did not initialize the semaphore.
.sp
.RS 4
.nf

/* create.c */
#include "pthread.h"
#include "sem.h"
.P
int
main()
{
    semaphore_t *semap;
.P
    semap = semaphore_create("/tmp/semaphore");
    if (semap == NULL)
        exit(1);
    semaphore_close(semap);
    return (0);
}
.P
/* post */
#include "pthread.h"
#include "sem.h"
.P
int
main()
{
    semaphore_t *semap;
.P
    semap = semaphore_open("/tmp/semaphore");
    if (semap == NULL)
        exit(1);
    semaphore_post(semap);
    semaphore_close(semap);
    return (0);
}
.P
/* wait */
#include "pthread.h"
#include "sem.h"
.P
int
main()
{
    semaphore_t *semap;
.P
    semap = semaphore_open("/tmp/semaphore");
    if (semap == NULL)
        exit(1);
    semaphore_wait(semap);
    semaphore_close(semap);
    return (0);
}
.fi
.P
.RE
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.ad l
.IR "\fIpthread_cond_destroy\fR\^(\|)",
.IR "\fIpthread_create\fR\^(\|)",
.IR "\fIpthread_mutex_destroy\fR\^(\|)"
.ad b
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<pthread.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .