--- libev/ev.pod	2009/12/26 09:21:54	1.275
+++ libev/ev.pod	2010/03/09 08:46:17	1.281
@@ -372,13 +372,18 @@
 testing, this flag can be useful to conserve inotify file descriptors, as
 otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
 
-=item C<EVFLAG_NOSIGFD>
+=item C<EVFLAG_SIGNALFD>
 
-When this flag is specified, then libev will not attempt to use the
-I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is
-probably only useful to work around any bugs in libev. Consequently, this
-flag might go away once the signalfd functionality is considered stable,
-so it's useful mostly in environment variables and not in program code.
+When this flag is specified, then libev will attempt to use the
+I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
+delivers signals synchronously, which makes it both faster and might make
+it possible to get the queued signal data. It can also simplify signal
+handling with threads, as long as you properly block signals in your
+threads that are not interested in handling them.
+
+Signalfd will not be used by default as this changes your signal mask, and
+there are a lot of shoddy libraries and programs (glib's threadpool for
+example) that can't properly initialise their signal masks.
 
 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
 
@@ -794,9 +799,10 @@
 loop: Every watcher keeps one reference, and as long as the reference
 count is nonzero, C<ev_loop> will not return on its own.
 
-If you have a watcher you never unregister that should not keep C<ev_loop>
-from returning, call ev_unref() after starting, and ev_ref() before
-stopping it.
+This is useful when you have a watcher that you never intend to
+unregister, but that nevertheless should not keep C<ev_loop> from
+returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
+before stopping it.
 
 As an example, libev itself uses this for its internal signal pipe: It
 is not visible to the libev user and should not keep C<ev_loop> from
@@ -1863,7 +1869,7 @@
 the timeout value currently configured.
 
 That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
-C<5>. When the timer is started and one second passes, C<ev_timer_remain>
+C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
 will return C<4>. When the timer expires and is restarted, it will return
 roughly C<7> (likely slightly less as callback invocation takes some time,
 too), and so on.
@@ -2133,7 +2139,7 @@
 interrupted by signals you can block all signals in an C<ev_check> watcher
 and unblock them in an C<ev_prepare> watcher.
 
-=head3 The special problem of inheritance over execve
+=head3 The special problem of inheritance over fork/execve/pthread_create
 
 Both the signal mask (C<sigprocmask>) and the signal disposition
 (C<sigaction>) are unspecified after starting a signal watcher (and after
@@ -2153,10 +2159,14 @@
 to install a fork handler with C<pthread_atfork> that resets it. That will
 catch fork calls done by libraries (such as the libc) as well.
 
-In current versions of libev, you can also ensure that the signal mask is
-not blocking any signals (except temporarily, so thread users watch out)
-by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This
-is not guaranteed for future versions, however.
+In current versions of libev, the signal will not be blocked indefinitely
+unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
+the window of opportunity for problems, it will not go away, as libev
+I<has> to modify the signal mask, at least temporarily.
+
+So I can't stress this enough: I<If you do not reset your signal mask when
+you expect it to be empty, you have a race condition in your code>. This
+is not a libev-specific thing, this is true for most event libraries.
 
 =head3 Watcher-Specific Functions and Data Members
 
@@ -3443,8 +3453,8 @@
 
 =item Lua
 
-Brian Maher has written a partial interface to libev
-for lua (only C<ev_io> and C<ev_timer>), to be found at
+Brian Maher has written a partial interface to libev for lua (at the
+time of this writing, only C<ev_io> and C<ev_timer>), to be found at
 L<http://github.com/brimworks/lua-ev>.
 
 =back
@@ -3609,12 +3619,19 @@
 =head2 PREPROCESSOR SYMBOLS/MACROS
 
 Libev can be configured via a variety of preprocessor symbols you have to
-define before including any of its files. The default in the absence of
-autoconf is documented for every option.
+define before including (or compiling) any of its files. The default in
+the absence of autoconf is documented for every option.
+
+Symbols marked with "(h)" do not change the ABI, and can have different
+values when compiling libev vs. including F<ev.h>, so it is permissible
+to redefine them before including F<ev.h> without breakign compatibility
+to a compiled library. All other symbols change the ABI, which means all
+users of libev and the libev code itself must be compiled with compatible
+settings.
 
 =over 4
 
-=item EV_STANDALONE
+=item EV_STANDALONE (h)
 
 Must always be C<1> if you do not use autoconf configuration, which
 keeps libev from including F<config.h>, and it also defines dummy
@@ -3774,24 +3791,24 @@
 In the absence of this define, libev will use C<sig_atomic_t volatile>
 (from F<signal.h>), which is usually good enough on most platforms.
 
-=item EV_H
+=item EV_H (h)
 
 The name of the F<ev.h> header file used to include it. The default if
 undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
 used to virtually rename the F<ev.h> header file in case of conflicts.
 
-=item EV_CONFIG_H
+=item EV_CONFIG_H (h)
 
 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
 C<EV_H>, above.
 
-=item EV_EVENT_H
+=item EV_EVENT_H (h)
 
 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
 of how the F<event.h> header can be found, the default is C<"event.h">.
 
-=item EV_PROTOTYPES
+=item EV_PROTOTYPES (h)
 
 If defined to be C<0>, then F<ev.h> will not define any function
 prototypes, but still define all the structs and other symbols. This is
@@ -3873,6 +3890,17 @@
 of the API are still available, and do not complain if this subset changes
 over time.
 
+=item EV_AVOID_STDIO
+
+If this is set to C<1> at compiletime, then libev will avoid using stdio
+functions (printf, scanf, perror etc.). This will increase the codesize
+somewhat, but if your program doesn't otherwise depend on stdio and your
+libc allows it, this avoids linking in the stdio library which is quite
+big.
+
+Note that error messages might become less precise when this option is
+enabled.
+
 =item EV_NSIG
 
 The highest supported signal number, +1 (or, the number of