arm-2011.03/share/doc/arm-arm-none-linux-gnueabi/html/libc/Nonreentrancy.html - nest-cam/v366/arm-none-linux-gnueabi-i686-pc-linux-gnu - Git at Google

 <html lang="en">
 <head>
 <title>Nonreentrancy - The GNU C Library</title>
 <meta http-equiv="Content-Type" content="text/html">
 <meta name="description" content="The GNU C Library">
 <meta name="generator" content="makeinfo 4.13">
 <link title="Top" rel="start" href="index.html#Top">
 <link rel="up" href="Defining-Handlers.html#Defining-Handlers" title="Defining Handlers">
 <link rel="prev" href="Merged-Signals.html#Merged-Signals" title="Merged Signals">
 <link rel="next" href="Atomic-Data-Access.html#Atomic-Data-Access" title="Atomic Data Access">
 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
 <!--
 This file documents the GNU C library.

 This is Edition 0.12, last updated 2007-10-27,
 of `The GNU C Library Reference Manual', for version
 2.8 (Sourcery G++ Lite 2011.03-41).

 Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
 2003, 2007, 2008, 2010 Free Software Foundation, Inc.

 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being ``Free Software Needs Free Documentation''
 and ``GNU Lesser General Public License'', the Front-Cover texts being
 ``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
 copy of the license is included in the section entitled "GNU Free
 Documentation License".

 (a) The FSF's Back-Cover Text is: ``You have the freedom to
 copy and modify this GNU manual.  Buying copies from the FSF
 supports it in developing GNU and promoting software freedom.''-->
 <meta http-equiv="Content-Style-Type" content="text/css">
 <style type="text/css"><!--
   pre.display { font-family:inherit }
   pre.format  { font-family:inherit }
   pre.smalldisplay { font-family:inherit; font-size:smaller }
   pre.smallformat  { font-family:inherit; font-size:smaller }
   pre.smallexample { font-size:smaller }
   pre.smalllisp    { font-size:smaller }
   span.sc    { font-variant:small-caps }
   span.roman { font-family:serif; font-weight:normal; }
   span.sansserif { font-family:sans-serif; font-weight:normal; }
 --></style>
 <link rel="stylesheet" type="text/css" href="../cs.css">
 </head>
 <body>
 <div class="node">
 <a name="Nonreentrancy"></a>
 <p>
 Next:&nbsp;<a rel="next" accesskey="n" href="Atomic-Data-Access.html#Atomic-Data-Access">Atomic Data Access</a>,
 Previous:&nbsp;<a rel="previous" accesskey="p" href="Merged-Signals.html#Merged-Signals">Merged Signals</a>,
 Up:&nbsp;<a rel="up" accesskey="u" href="Defining-Handlers.html#Defining-Handlers">Defining Handlers</a>
 <hr>
 </div>

 <h4 class="subsection">24.4.6 Signal Handling and Nonreentrant Functions</h4>

 <p><a name="index-restrictions-on-signal-handler-functions-2936"></a>
 Handler functions usually don't do very much.  The best practice is to
 write a handler that does nothing but set an external variable that the
 program checks regularly, and leave all serious work to the program.
 This is best because the handler can be called asynchronously, at
 unpredictable times&mdash;perhaps in the middle of a primitive function, or
 even between the beginning and the end of a C operator that requires
 multiple instructions.  The data structures being manipulated might
 therefore be in an inconsistent state when the handler function is
 invoked.  Even copying one <code>int</code> variable into another can take two
 instructions on most machines.

    <p>This means you have to be very careful about what you do in a signal
 handler.

      <ul>
 <li><a name="index-g_t_0040code_007bvolatile_007d-declarations-2937"></a>If your handler needs to access any global variables from your program,
 declare those variables <code>volatile</code>.  This tells the compiler that
 the value of the variable might change asynchronously, and inhibits
 certain optimizations that would be invalidated by such modifications.

      <li><a name="index-reentrant-functions-2938"></a>If you call a function in the handler, make sure it is <dfn>reentrant</dfn>
 with respect to signals, or else make sure that the signal cannot
 interrupt a call to a related function.
 </ul>

    <p>A function can be non-reentrant if it uses memory that is not on the
 stack.

      <ul>
 <li>If a function uses a static variable or a global variable, or a
 dynamically-allocated object that it finds for itself, then it is
 non-reentrant and any two calls to the function can interfere.

      <p>For example, suppose that the signal handler uses <code>gethostbyname</code>.
 This function returns its value in a static object, reusing the same
 object each time.  If the signal happens to arrive during a call to
 <code>gethostbyname</code>, or even after one (while the program is still
 using the value), it will clobber the value that the program asked for.

      <p>However, if the program does not use <code>gethostbyname</code> or any other
 function that returns information in the same object, or if it always
 blocks signals around each use, then you are safe.

      <p>There are a large number of library functions that return values in a
 fixed object, always reusing the same object in this fashion, and all of
 them cause the same problem.  Function descriptions in this manual
 always mention this behavior.

      <li>If a function uses and modifies an object that you supply, then it is
 potentially non-reentrant; two calls can interfere if they use the same
 object.

      <p>This case arises when you do I/O using streams.  Suppose that the
 signal handler prints a message with <code>fprintf</code>.  Suppose that the
 program was in the middle of an <code>fprintf</code> call using the same
 stream when the signal was delivered.  Both the signal handler's message
 and the program's data could be corrupted, because both calls operate on
 the same data structure&mdash;the stream itself.

      <p>However, if you know that the stream that the handler uses cannot
 possibly be used by the program at a time when signals can arrive, then
 you are safe.  It is no problem if the program uses some other stream.

      <li>On most systems, <code>malloc</code> and <code>free</code> are not reentrant,
 because they use a static data structure which records what memory
 blocks are free.  As a result, no library functions that allocate or
 free memory are reentrant.  This includes functions that allocate space
 to store a result.

      <p>The best way to avoid the need to allocate memory in a handler is to
 allocate in advance space for signal handlers to use.

      <p>The best way to avoid freeing memory in a handler is to flag or record
 the objects to be freed, and have the program check from time to time
 whether anything is waiting to be freed.  But this must be done with
 care, because placing an object on a chain is not atomic, and if it is
 interrupted by another signal handler that does the same thing, you
 could &ldquo;lose&rdquo; one of the objects.

      <li>Any function that modifies <code>errno</code> is non-reentrant, but you can
 correct for this: in the handler, save the original value of
 <code>errno</code> and restore it before returning normally.  This prevents
 errors that occur within the signal handler from being confused with
 errors from system calls at the point the program is interrupted to run
 the handler.

      <p>This technique is generally applicable; if you want to call in a handler
 a function that modifies a particular object in memory, you can make
 this safe by saving and restoring that object.

      <li>Merely reading from a memory object is safe provided that you can deal
 with any of the values that might appear in the object at a time when
 the signal can be delivered.  Keep in mind that assignment to some data
 types requires more than one instruction, which means that the handler
 could run &ldquo;in the middle of&rdquo; an assignment to the variable if its type
 is not atomic.  See <a href="Atomic-Data-Access.html#Atomic-Data-Access">Atomic Data Access</a>.

      <li>Merely writing into a memory object is safe as long as a sudden change
 in the value, at any time when the handler might run, will not disturb
 anything.
 </ul>

    </body></html>
	<html lang="en">
	<head>
	<title>Nonreentrancy - The GNU C Library</title>
	<meta http-equiv="Content-Type" content="text/html">
	<meta name="description" content="The GNU C Library">
	<meta name="generator" content="makeinfo 4.13">
	<link title="Top" rel="start" href="index.html#Top">
	<link rel="up" href="Defining-Handlers.html#Defining-Handlers" title="Defining Handlers">
	<link rel="prev" href="Merged-Signals.html#Merged-Signals" title="Merged Signals">
	<link rel="next" href="Atomic-Data-Access.html#Atomic-Data-Access" title="Atomic Data Access">
	<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
	<!--
	This file documents the GNU C library.

	This is Edition 0.12, last updated 2007-10-27,
	of `The GNU C Library Reference Manual', for version
	2.8 (Sourcery G++ Lite 2011.03-41).

	Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
	2003, 2007, 2008, 2010 Free Software Foundation, Inc.

	Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU Free Documentation License, Version 1.3 or
	any later version published by the Free Software Foundation; with the
	Invariant Sections being ``Free Software Needs Free Documentation''
	and ``GNU Lesser General Public License'', the Front-Cover texts being
	``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A
	copy of the license is included in the section entitled "GNU Free
	Documentation License".

	(a) The FSF's Back-Cover Text is: ``You have the freedom to
	copy and modify this GNU manual. Buying copies from the FSF
	supports it in developing GNU and promoting software freedom.''-->
	<meta http-equiv="Content-Style-Type" content="text/css">
	<style type="text/css"><!--
	pre.display { font-family:inherit }
	pre.format { font-family:inherit }
	pre.smalldisplay { font-family:inherit; font-size:smaller }
	pre.smallformat { font-family:inherit; font-size:smaller }
	pre.smallexample { font-size:smaller }
	pre.smalllisp { font-size:smaller }
	span.sc { font-variant:small-caps }
	span.roman { font-family:serif; font-weight:normal; }
	span.sansserif { font-family:sans-serif; font-weight:normal; }
	--></style>
	<link rel="stylesheet" type="text/css" href="../cs.css">
	</head>
	<body>
	<div class="node">
	<a name="Nonreentrancy"></a>
	<p>
	Next: <a rel="next" accesskey="n" href="Atomic-Data-Access.html#Atomic-Data-Access">Atomic Data Access</a>,
	Previous: <a rel="previous" accesskey="p" href="Merged-Signals.html#Merged-Signals">Merged Signals</a>,
	Up: <a rel="up" accesskey="u" href="Defining-Handlers.html#Defining-Handlers">Defining Handlers</a>
	<hr>
	</div>

	<h4 class="subsection">24.4.6 Signal Handling and Nonreentrant Functions</h4>

	<p><a name="index-restrictions-on-signal-handler-functions-2936"></a>
	Handler functions usually don't do very much. The best practice is to
	write a handler that does nothing but set an external variable that the
	program checks regularly, and leave all serious work to the program.
	This is best because the handler can be called asynchronously, at
	unpredictable times—perhaps in the middle of a primitive function, or
	even between the beginning and the end of a C operator that requires
	multiple instructions. The data structures being manipulated might
	therefore be in an inconsistent state when the handler function is
	invoked. Even copying one <code>int</code> variable into another can take two
	instructions on most machines.

	<p>This means you have to be very careful about what you do in a signal
	handler.

	<ul>
	<li><a name="index-g_t_0040code_007bvolatile_007d-declarations-2937"></a>If your handler needs to access any global variables from your program,
	declare those variables <code>volatile</code>. This tells the compiler that
	the value of the variable might change asynchronously, and inhibits
	certain optimizations that would be invalidated by such modifications.

	<li><a name="index-reentrant-functions-2938"></a>If you call a function in the handler, make sure it is <dfn>reentrant</dfn>
	with respect to signals, or else make sure that the signal cannot
	interrupt a call to a related function.
	</ul>

	<p>A function can be non-reentrant if it uses memory that is not on the
	stack.

	<ul>
	<li>If a function uses a static variable or a global variable, or a
	dynamically-allocated object that it finds for itself, then it is
	non-reentrant and any two calls to the function can interfere.

	<p>For example, suppose that the signal handler uses <code>gethostbyname</code>.
	This function returns its value in a static object, reusing the same
	object each time. If the signal happens to arrive during a call to
	<code>gethostbyname</code>, or even after one (while the program is still
	using the value), it will clobber the value that the program asked for.

	<p>However, if the program does not use <code>gethostbyname</code> or any other
	function that returns information in the same object, or if it always
	blocks signals around each use, then you are safe.

	<p>There are a large number of library functions that return values in a
	fixed object, always reusing the same object in this fashion, and all of
	them cause the same problem. Function descriptions in this manual
	always mention this behavior.

	<li>If a function uses and modifies an object that you supply, then it is
	potentially non-reentrant; two calls can interfere if they use the same
	object.

	<p>This case arises when you do I/O using streams. Suppose that the
	signal handler prints a message with <code>fprintf</code>. Suppose that the
	program was in the middle of an <code>fprintf</code> call using the same
	stream when the signal was delivered. Both the signal handler's message
	and the program's data could be corrupted, because both calls operate on
	the same data structure—the stream itself.

	<p>However, if you know that the stream that the handler uses cannot
	possibly be used by the program at a time when signals can arrive, then
	you are safe. It is no problem if the program uses some other stream.

	<li>On most systems, <code>malloc</code> and <code>free</code> are not reentrant,
	because they use a static data structure which records what memory
	blocks are free. As a result, no library functions that allocate or
	free memory are reentrant. This includes functions that allocate space
	to store a result.

	<p>The best way to avoid the need to allocate memory in a handler is to
	allocate in advance space for signal handlers to use.

	<p>The best way to avoid freeing memory in a handler is to flag or record
	the objects to be freed, and have the program check from time to time
	whether anything is waiting to be freed. But this must be done with
	care, because placing an object on a chain is not atomic, and if it is
	interrupted by another signal handler that does the same thing, you
	could “lose” one of the objects.

	<li>Any function that modifies <code>errno</code> is non-reentrant, but you can
	correct for this: in the handler, save the original value of
	<code>errno</code> and restore it before returning normally. This prevents
	errors that occur within the signal handler from being confused with
	errors from system calls at the point the program is interrupted to run
	the handler.

	<p>This technique is generally applicable; if you want to call in a handler
	a function that modifies a particular object in memory, you can make
	this safe by saving and restoring that object.

	<li>Merely reading from a memory object is safe provided that you can deal
	with any of the values that might appear in the object at a time when
	the signal can be delivered. Keep in mind that assignment to some data
	types requires more than one instruction, which means that the handler
	could run “in the middle of” an assignment to the variable if its type
	is not atomic. See <a href="Atomic-Data-Access.html#Atomic-Data-Access">Atomic Data Access</a>.

	<li>Merely writing into a memory object is safe as long as a sudden change
	in the value, at any time when the handler might run, will not disturb
	anything.
	</ul>

	</body></html>