PTHREAD_MUTEXATTR_DESTROY(3)POSIX Programmer's ManuaPlTHREAD_MUTEXATTR_DESTROY(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       pthread_mutexattr_destroy, pthread_mutexattr_init -- destroy and
       initialize the mutex attributes object

SSYYNNOOPPSSIISS
       #include <pthread.h>

       int pthread_mutexattr_destroy(pthread_mutexattr_t *_a_t_t_r);
       int pthread_mutexattr_init(pthread_mutexattr_t *_a_t_t_r);

DDEESSCCRRIIPPTTIIOONN
       The _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___d_e_s_t_r_o_y() function shall destroy a mutex
       attributes object; the object becomes, in effect, uninitialized. An
       implementation may cause _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___d_e_s_t_r_o_y() to set the object
       referenced by _a_t_t_r to an invalid value.

       A destroyed _a_t_t_r attributes object can be reinitialized using
       _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___i_n_i_t(); the results of otherwise referencing the
       object after it has been destroyed are undefined.

       The _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___i_n_i_t() function shall initialize a mutex
       attributes object _a_t_t_r with the default value for all of the attributes
       defined by the implementation.

       Results are undefined if _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___i_n_i_t() is called specifying
       an already initialized _a_t_t_r attributes object.

       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.

       The behavior is undefined if the value specified by the _a_t_t_r argument
       to _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___d_e_s_t_r_o_y() does not refer to an initialized mutex
       attributes object.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___d_e_s_t_r_o_y() and
       _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___i_n_i_t() shall return zero; otherwise, an error number
       shall be returned to indicate the error.

EERRRROORRSS
       The _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___i_n_i_t() function shall fail if:

       EENNOOMMEEMM Insufficient memory exists to initialize the mutex attributes
              object.

       These functions shall not return an error code of [[EEIINNTTRR]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       If an implementation detects that the value specified by the _a_t_t_r
       argument to _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___d_e_s_t_r_o_y() does not refer to an
       initialized mutex attributes object, it is recommended that the
       function should fail and report an [[EEIINNVVAALL]] error.

       See _p_t_h_r_e_a_d___a_t_t_r___d_e_s_t_r_o_y() for a general explanation of attributes.
       Attributes objects allow implementations to experiment with useful
       extensions and permit extension of this volume of POSIX.1-2017 without
       changing the existing functions. Thus, they provide for future
       extensibility of this volume of POSIX.1-2017 and reduce the temptation
       to standardize prematurely on semantics that are not yet widely
       implemented or understood.

       Examples of possible additional mutex attributes that have been
       discussed are _s_p_i_n___o_n_l_y, _l_i_m_i_t_e_d___s_p_i_n, _n_o___s_p_i_n, _r_e_c_u_r_s_i_v_e, and _m_e_t_e_r_e_d.
       (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-2017. Mutex attributes
       objects, however, make it possible to test out these concepts for
       possible standardization at a later time.

   MMuutteexx AAttttrriibbuutteess aanndd PPeerrffoorrmmaannccee
       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).

       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.

   PPrroocceessss SShhaarreedd MMeemmoorryy aanndd SSyynncchhrroonniizzaattiioonn
       The existence of memory mapping functions in this volume of
       POSIX.1-2017 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).

       In order to permit such usage, while at the same time keeping the usual
       case (that is, usage within a single process) efficient, a _p_r_o_c_e_s_s_-
       _s_h_a_r_e_d option has been defined.

       If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option,
       then the _p_r_o_c_e_s_s_-_s_h_a_r_e_d attribute can be used to indicate that mutexes
       or condition variables may be accessed by threads of multiple
       processes.

       The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for the
       _p_r_o_c_e_s_s_-_s_h_a_r_e_d attribute so that the most efficient forms of these
       synchronization objects are created by default.

       Synchronization variables that are initialized with the
       PTHREAD_PROCESS_PRIVATE _p_r_o_c_e_s_s_-_s_h_a_r_e_d attribute may only be operated
       on by threads in the process that initialized them. Synchronization
       variables that are initialized with the PTHREAD_PROCESS_SHARED _p_r_o_c_e_s_s_-
       _s_h_a_r_e_d 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.


           /* sem.h */
           struct semaphore {
               pthread_mutex_t lock;
               pthread_cond_t nonzero;
               unsigned count;
           };
           typedef struct semaphore semaphore_t;

           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);

           /* sem.c */
           #include <sys/types.h>
           #include <sys/stat.h>
           #include <sys/mman.h>
           #include <fcntl.h>
           #include <pthread.h>
           #include "sem.h"

           semaphore_t *
           semaphore_create(char *semaphore_name)
           {
           int fd;
               semaphore_t *semap;
               pthread_mutexattr_t psharedm;
               pthread_condattr_t psharedc;

               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);
           }

           semaphore_t *
           semaphore_open(char *semaphore_name)
           {
               int fd;
               semaphore_t *semap;

               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);
           }

           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);
           }

           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);
           }

           void
           semaphore_close(semaphore_t *semap)
           {
               munmap((void *) semap, sizeof(semaphore_t));
           }

       The following code is for three separate processes that create, post,
       and wait on a semaphore in the file //ttmmpp//sseemmaapphhoorree.  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.


           /* create.c */
           #include "pthread.h"
           #include "sem.h"

           int
           main()
           {
               semaphore_t *semap;

               semap = semaphore_create("/tmp/semaphore");
               if (semap == NULL)
                   exit(1);
               semaphore_close(semap);
               return (0);
           }

           /* post */
           #include "pthread.h"
           #include "sem.h"

           int
           main()
           {
               semaphore_t *semap;

               semap = semaphore_open("/tmp/semaphore");
               if (semap == NULL)
                   exit(1);
               semaphore_post(semap);
               semaphore_close(semap);
               return (0);
           }

           /* wait */
           #include "pthread.h"
           #include "sem.h"

           int
           main()
           {
               semaphore_t *semap;

               semap = semaphore_open("/tmp/semaphore");
               if (semap == NULL)
                   exit(1);
               semaphore_wait(semap);
               semaphore_close(semap);
               return (0);
           }

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _p_t_h_r_e_a_d___c_o_n_d___d_e_s_t_r_o_y(), _p_t_h_r_e_a_d___c_r_e_a_t_e(), _p_t_h_r_e_a_d___m_u_t_e_x___d_e_s_t_r_o_y()

       The Base Definitions volume of POSIX.1-2017, <<pptthhrreeaadd..hh>>

CCOOPPYYRRIIGGHHTT
       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 .

       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 .



IEEE/The Open Group                  2017         PTHREAD_MUTEXATTR_DESTROY(3)
