188 lines
9.4 KiB
HTML
188 lines
9.4 KiB
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 The Open Group, All Rights Reserved -->
|
|
<title>pthread_atfork</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="pthread_atfork"></a> <a name="tag_03_486"></a><!-- pthread_atfork -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_486_01"></a>NAME</h4>
|
|
|
|
<blockquote>pthread_atfork - register fork handlers</blockquote>
|
|
|
|
<h4><a name="tag_03_486_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_atfork(void (*</tt><i>prepare</i><tt>)(void), void (*</tt><i>parent</i><tt>)(void),<br>
|
|
void (*</tt><i>child</i><tt>)(void)); <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_486_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pthread_atfork</i>() function shall declare fork handlers to be called before and after <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>, in the context of the thread that called <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>. The <i>prepare</i> fork handler shall be called before <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> processing commences. The <i>parent</i> fork handle shall be called after <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> processing completes in the parent process. The <i>child</i> fork handler shall be
|
|
called after <a href="../functions/fork.html"><i>fork</i>()</a> processing completes in the child process. If no handling is
|
|
desired at one or more of these three points, the corresponding fork handler address(es) may be set to NULL.</p>
|
|
|
|
<p>The order of calls to <i>pthread_atfork</i>() is significant. The <i>parent</i> and <i>child</i> fork handlers shall be called
|
|
in the order in which they were established by calls to <i>pthread_atfork</i>(). The <i>prepare</i> fork handlers shall be called
|
|
in the opposite order.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>pthread_atfork</i>() shall return a value of zero; otherwise, an error number shall be returned
|
|
to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pthread_atfork</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[ENOMEM]</dt>
|
|
|
|
<dd>Insufficient table space exists to record the fork handler addresses.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>pthread_atfork</i>() function 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_486_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>There are at least two serious problems with the semantics of <a href="../functions/fork.html"><i>fork</i>()</a> in a
|
|
multi-threaded program. One problem has to do with state (for example, memory) covered by mutexes. Consider the case where one
|
|
thread has a mutex locked and the state covered by that mutex is inconsistent while another thread calls <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>. In the child, the mutex is in the locked state (locked by a nonexistent thread and thus
|
|
can never be unlocked). Having the child simply reinitialize the mutex is unsatisfactory since this approach does not resolve the
|
|
question about how to correct or otherwise deal with the inconsistent state in the child.</p>
|
|
|
|
<p>It is suggested that programs that use <a href="../functions/fork.html"><i>fork</i>()</a> call an <i><a href=
|
|
"../functions/exec.html">exec</a></i> function very soon afterwards in the child process, thus resetting all states. In the
|
|
meantime, only a short list of async-signal-safe library routines are promised to be available.</p>
|
|
|
|
<p>Unfortunately, this solution does not address the needs of multi-threaded libraries. Application programs may not be aware that
|
|
a multi-threaded library is in use, and they feel free to call any number of library routines between the <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> and <i><a href="../functions/exec.html">exec</a></i> calls, just as they always have.
|
|
Indeed, they may be extant single-threaded programs and cannot, therefore, be expected to obey new restrictions imposed by the
|
|
threads library.</p>
|
|
|
|
<p>On the other hand, the multi-threaded library needs a way to protect its internal state during <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> in case it is re-entered later in the child process. The problem arises especially in
|
|
multi-threaded I/O libraries, which are almost sure to be invoked between the <a href="../functions/fork.html"><i>fork</i>()</a>
|
|
and <i><a href="../functions/exec.html">exec</a></i> calls to effect I/O redirection. The solution may require locking mutex
|
|
variables during <a href="../functions/fork.html"><i>fork</i>()</a>, or it may entail simply resetting the state in the child after
|
|
the <a href="../functions/fork.html"><i>fork</i>()</a> processing completes.</p>
|
|
|
|
<p>The <i>pthread_atfork</i>() function provides multi-threaded libraries with a means to protect themselves from innocent
|
|
application programs that call <a href="../functions/fork.html"><i>fork</i>()</a>, and it provides multi-threaded application
|
|
programs with a standard mechanism for protecting themselves from <a href="../functions/fork.html"><i>fork</i>()</a> calls in a
|
|
library routine or the application itself.</p>
|
|
|
|
<p>The expected usage is that the <i>prepare</i> handler acquires all mutex locks and the other two fork handlers release them.</p>
|
|
|
|
<p>For example, an application can supply a <i>prepare</i> routine that acquires the necessary mutexes the library maintains and
|
|
supply <i>child</i> and <i>parent</i> routines that release those mutexes, thus ensuring that the child gets a consistent snapshot
|
|
of the state of the library (and that no mutexes are left stranded). Alternatively, some libraries might be able to supply just a
|
|
<i>child</i> routine that reinitializes the mutexes in the library and all associated states to some known value (for example, what
|
|
it was when the image was originally executed).</p>
|
|
|
|
<p>When <a href="../functions/fork.html"><i>fork</i>()</a> is called, only the calling thread is duplicated in the child process.
|
|
Synchronization variables remain in the same state in the child as they were in the parent at the time <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> was called. Thus, for example, mutex locks may be held by threads that no longer exist
|
|
in the child process, and any associated states may be inconsistent. The parent process may avoid this by explicit code that
|
|
acquires and releases locks critical to the child via <i>pthread_atfork</i>(). In addition, any critical threads need to be
|
|
recreated and reinitialized to the proper state in the child (also via <i>pthread_atfork</i>()).</p>
|
|
|
|
<p>A higher-level package may acquire locks on its own data structures before invoking lower-level packages. Under this scenario,
|
|
the order specified for fork handler calls allows a simple rule of initialization for avoiding package deadlock: a package
|
|
initializes all packages on which it depends before it calls the <i>pthread_atfork</i>() function for itself.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="atexit.html"><i>atexit</i>()</a> , <a href="fork.html"><i>fork</i>()</a> , the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 5. Derived from the POSIX Threads Extension.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.1c #4 is applied.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_486_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pthread_atfork</i>() function is marked as part of the Threads option.</p>
|
|
|
|
<p>The <a href="../basedefs/pthread.h.html"><i><pthread.h></i></a> header is added to the SYNOPSIS.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|