📄 pthread_mutex_init.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta name="generator" content="HTML Tidy, see www.w3.org"><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 --><!-- Copyright (c) 2001-2003 The Open Group, All Rights Reserved --><title>pthread_mutex_destroy</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="pthread_mutex_destroy"></a> <a name="tag_03_537"></a><!-- pthread_mutex_destroy --> <!--header start--><center><font size="2">The Open Group Base Specifications Issue 6<br>IEEE Std 1003.1, 2003 Edition<br>Copyright © 2001-2003 The IEEE and The Open Group, All Rights reserved.</font></center><!--header end--><hr size="2" noshade><h4><a name="tag_03_537_01"></a>NAME</h4><blockquote>pthread_mutex_destroy, pthread_mutex_init - destroy and initialize a mutex</blockquote><h4><a name="tag_03_537_02"></a>SYNOPSIS</h4><blockquote class="synopsis"><div class="box"><code><tt><sup>[<a href="javascript:open_code('THR')">THR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> #include <<a href="../basedefs/pthread.h.html">pthread.h</a>><br><br> int pthread_mutex_destroy(pthread_mutex_t *</tt><i>mutex</i><tt>);<br> int pthread_mutex_init(pthread_mutex_t *restrict</tt> <i>mutex</i><tt>,<br> const pthread_mutexattr_t *restrict</tt> <i>attr</i><tt>);<br> pthread_mutex_t</tt> <i>mutex</i> <tt>= PTHREAD_MUTEX_INITIALIZER; <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div><tt><br></tt></blockquote><h4><a name="tag_03_537_03"></a>DESCRIPTION</h4><blockquote><p>The <i>pthread_mutex_destroy</i>() function shall destroy the mutex object referenced by <i>mutex</i>; the mutex object becomes,in effect, uninitialized. An implementation may cause <i>pthread_mutex_destroy</i>() to set the object referenced by <i>mutex</i>to an invalid value. A destroyed mutex object can be reinitialized using <i>pthread_mutex_init</i>(); the results of otherwisereferencing the object after it has been destroyed are undefined.</p><p>It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked mutex results in undefinedbehavior.</p><p>The <i>pthread_mutex_init</i>() function shall initialize the mutex referenced by <i>mutex</i> with attributes specified by<i>attr</i>. If <i>attr</i> is NULL, the default mutex attributes are used; the effect shall be the same as passing the address ofa default mutex attributes object. Upon successful initialization, the state of the mutex becomes initialized and unlocked.</p><p>Only <i>mutex</i> itself may be used for performing synchronization. The result of referring to copies of <i>mutex</i> in callsto <a href="../functions/pthread_mutex_lock.html"><i>pthread_mutex_lock</i>()</a>, <a href="../functions/pthread_mutex_trylock.html"><i>pthread_mutex_trylock</i>()</a>, <a href="../functions/pthread_mutex_unlock.html"><i>pthread_mutex_unlock</i>()</a>, and <i>pthread_mutex_destroy</i>() is undefined.</p><p>Attempting to initialize an already initialized mutex results in undefined behavior.</p><p>In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexesthat are statically allocated. The effect shall be equivalent to dynamic initialization by a call to <i>pthread_mutex_init</i>()with parameter <i>attr</i> specified as NULL, except that no error checks are performed.</p></blockquote><h4><a name="tag_03_537_04"></a>RETURN VALUE</h4><blockquote><p>If successful, the <i>pthread_mutex_destroy</i>() and <i>pthread_mutex_init</i>() functions shall return zero; otherwise, anerror number shall be returned to indicate the error.</p><p>The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed immediately at the beginning of processingfor the function and shall cause an error return prior to modifying the state of the mutex specified by <i>mutex</i>.</p></blockquote><h4><a name="tag_03_537_05"></a>ERRORS</h4><blockquote><p>The <i>pthread_mutex_destroy</i>() function may fail if:</p><dl compact><dt>[EBUSY]</dt><dd>The implementation has detected an attempt to destroy the object referenced by <i>mutex</i> while it is locked or referenced(for example, while being used in a <a href="../functions/pthread_cond_timedwait.html"><i>pthread_cond_timedwait</i>()</a> or <ahref="../functions/pthread_cond_wait.html"><i>pthread_cond_wait</i>()</a>) by another thread.</dd><dt>[EINVAL]</dt><dd>The value specified by <i>mutex</i> is invalid.</dd></dl><p>The <i>pthread_mutex_init</i>() function shall fail if:</p><dl compact><dt>[EAGAIN]</dt><dd>The system lacked the necessary resources (other than memory) to initialize another mutex.</dd><dt>[ENOMEM]</dt><dd>Insufficient memory exists to initialize the mutex.</dd><dt>[EPERM]</dt><dd>The caller does not have the privilege to perform the operation.</dd></dl><p>The <i>pthread_mutex_init</i>() function may fail if:</p><dl compact><dt>[EBUSY]</dt><dd>The implementation has detected an attempt to reinitialize the object referenced by <i>mutex</i>, a previously initialized, butnot yet destroyed, mutex.</dd><dt>[EINVAL]</dt><dd>The value specified by <i>attr</i> is invalid.</dd></dl><p>These functions shall not return an error code of [EINTR].</p></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_537_06"></a>EXAMPLES</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_537_07"></a>APPLICATION USAGE</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_537_08"></a>RATIONALE</h4><blockquote><h5><a name="tag_03_537_08_01"></a>Alternate Implementations Possible</h5><p>This volume of IEEE Std 1003.1-2001 supports several alternative implementations of mutexes. An implementation maystore the lock directly in the object of type <b>pthread_mutex_t</b>. Alternatively, an implementation may store the lock in theheap and merely store a pointer, handle, or unique ID in the mutex object. Either implementation has advantages or may be requiredon certain hardware configurations. So that portable code can be written that is invariant to this choice, this volume ofIEEE Std 1003.1-2001 does not define assignment or equality for this type, and it uses the term "initialize" toreinforce the (more restrictive) notion that the lock may actually reside in the mutex object itself.</p><p>Note that this precludes an over-specification of the type of the mutex or condition variable and motivates the opaqueness ofthe type.</p><p>An implementation is permitted, but not required, to have <i>pthread_mutex_destroy</i>() store an illegal value into the mutex.This may help detect erroneous programs that try to lock (or otherwise reference) a mutex that has already been destroyed.</p><h5><a name="tag_03_537_08_02"></a>Tradeoff Between Error Checks and Performance Supported</h5><p>Many of the error checks were made optional in order to let implementations trade off performance <i>versus</i> degree of errorchecking according to the needs of their specific applications and execution environment. As a general rule, errors or conditionscaused by the system (such as insufficient memory) always need to be reported, but errors due to an erroneously coded application(such as failing to provide adequate synchronization to prevent a mutex from being deleted while in use) are made optional.</p><p>A wide range of implementations is thus made possible. For example, an implementation intended for application debugging mayimplement all of the error checks, but an implementation running a single, provably correct application under very tightperformance constraints in an embedded computer might implement minimal checks. An implementation might even be provided in twoversions, similar to the options that compilers provide: a full-checking, but slower version; and a limited-checking, but fasterversion. To forbid this optionality would be a disservice to users.</p><p>By carefully limiting the use of "undefined behavior" only to things that an erroneous (badly coded) application might do, andby defining that resource-not-available errors are mandatory, this volume of IEEE Std 1003.1-2001 ensures that afully-conforming application is portable across the full range of implementations, while not forcing all implementations to addoverhead to check for numerous things that a correct program never does.</p><h5><a name="tag_03_537_08_03"></a>Why No Limits are Defined</h5>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -