Files
mheily bf08b3f898 remove unimplemented solaris stuff
git-svn-id: svn://svn.code.sf.net/p/libkqueue/code/trunk@328 fb4e3144-bc1c-4b72-a658-5bcd248dd7f7
2010-09-14 03:05:35 +00:00

175 lines
5.9 KiB
Plaintext

m4_include(header.m4)
<h2>Usage</h2>
Here are some issues to be aware of when using this library under any platform:
<br/>
<ol>
<li>
The EVFILT_PROC filter is not implemented.
</li>
<li>
The EVFILT_AIO filter is not implemented.
</li>
<li>When a kqueue descriptor is closed, it's resources are not immediately reclaimed. Instead, they will be freed the next time that the <code>kqueue(2)</code> function is called.
</li>
<li>
A signal handler is implicitly installed when a EVFILT_SIGNAL kevent is created. For compatibility with kernel-based <code>kqueue(2)</code>, programs must ignore signals that will generate kevents. After an EVFILT_SIGNAL kevent is created, a program must not modify the disposition of the associated signal. The following example shows the proper way to handle SIGUSR1 with a kevent:
<pre>
int main() {
int kqfd;
struct kevent kev;
kqfd = kqueue();
signal(SIGUSR1, SIG_IGN);
EV_SET(&amp;kev, SIGUSR1, EVFILT_SIGNAL, EV_ADD, 0, 0, NULL);
kevent(kqfd, &amp;kev, 1, NULL, 0, NULL);
}
</pre>
</ol>
<h3>Linux</h3>
There are several compatibility issues to be aware of when using this library under Linux:<br/>
<ol>
<li>The NOTE_LOWAT flag is not supported. According to <i>socket(7)</i>,<br/>
<pre style="blockquote">
"The select(2) and poll(2) system calls currently do not respect the
SO_RCVLOWAT setting on Linux, and mark a socket readable when even a
single byte of data is available. A subsequent read from the socket
will block until SO_RCVLOWAT bytes are available."</pre>
</li>
<li>
The NOTE_REVOKE flag is not supported because Linux does not have
a <code>revoke(2)</code> system call.
</li>
<li>
When an EVFILT_SIGNAL event is generated, the <code>data</code> field
is set to 1 regardless of how many times the signal was received by the process.
</li>
<li>
When an EVFILT_READ event occurs on a listening socket, the <code>data</code> field is set to 1 regardless of how many pending connections are available.
<!--
<li>
The EVFILT_PROC filter only supports the NOTE_EXIT flag, and the <code>ident</code> field must contain the PID of a child of the current process. This filter is only suitable as an event-driven replacement for the <code>wait(2)</code> family of system calls.
</li>
-->
</ol>
<h3>Solaris</h3>
Here are the issues to be aware of when using this library under Solaris:<br/>
<ol>
<li>
Solaris 10 or newer is required. It should work with OpenSolaris and other Solaris-based distributions, but has not been tested.
</li>
<li>
When an EVFILT_READ event is generated, the <code>data</code> field
is set to 1 regardless of how many bytes are available to read.
</li>
<li>
When an EVFILT_TIMER event is generated, the <code>data</code> field
is set to 1 regardless of how many times the timer has been triggered.
</li>
<li>
The EVFILT_VNODE filter is not implemented. This will eventually be implemented
using the PORT_SOURCE_FILE mechanism described <a href="http://blogs.sun.com/praks/entry/file_events_notification">here</a>.
</li>
<li>The EVFILT_TIMER filter is implemented using high-resolution timers. In order to use high-resolution timers, the calling process must hold the PRIV_PROC_CLOCK_HIGHRES privilege. This privilege is not granted to ordinary users by default. It can be granted to individual users by running the following command as root:<br/>
<pre>
# usermod -K defaultpriv=basic,proc_clock_highres $user
</pre>
</ol>
<h3>BSD-based systems</h3>
There are some differences in the behavior of the <code>kevent(2)</code> system call across the various BSD-based operating systems. Here are some of the differences to be aware of:
<ol>
<li>FreeBSD 8 does not set the <i>EV_ADD</i> flag for kevents on the eventlist, but OpenBSD and Darwin do. This means you should never use the equality operator (==) to test the flags; use the logical AND operator instead.
</li>
<li>The <code>EVFILT_USER</code> filter behaves differently from other filters with respect to the <i>EV_ONESHOT</i> flag. All other filters will preserve the flag when the event is triggered and placed on the eventlist. The <code>EVFILT_USER</code> filter does not preserve this flag.
</li>
<li>
OpenBSD has the <i>NOTE_TRUNCATE</i> fflag, while FreeBSD and Darwin do not.
</li>
<li>
EVFILT_FS is undocumented and only available on FreeBSD and Darwin. Here is the <a href="http://adam.kungfoohampster.com/lists/cvs-all/msg71399.shtml">CVS commit log</a> which could be helpful to document this filter.
</li>
<!--
<li>
[TODO - Verify and check against 10.6] OS X 10.5 and earlier do not implement the <code>EVFILT_AIO</code> or <code>EVFILT_TIMER</code> filters.
</li>
-->
</ol>
<h2>Integration</h2>
<h3>Ordinary Makefile</h3>
Here are the steps to use libkqueue in your program if you use an ordinary Makefile:
<ol>
<li>Add <code>&lsquo;pkg-config libkqueue --cflags&lsquo;</code> to the CFLAGS variable.
<li>Add <code>&lsquo;pkg-config libkqueue --libs&lsquo;</code> to the LDADD variable.
<li>Add <code>#include &lt;sys/event.h&gt;</code> to the source code.
</ol>
<h3>Autoconf/Automake/Libtool</h3>
If your program uses the GNU Autoconf/Automake/Libtool build system, the following steps will allow you to use libkqueue:
<ol>
<li>Add the following to <code>configure.ac</code>:
<pre>
#
# Prefer native kqueue(2); otherwise use libkqueue if present.
#
AC_CHECK_HEADER(sys/event.h, [],
[PKG_CHECK_MODULES(KQUEUE, libkqueue)]
)
</pre>
</li>
<li>
Add the following to <code>Makefile.am</code> (assuming your program is named "foo"):
<pre>
foo_CFLAGS+=$(KQUEUE_CFLAGS)
foo_LDADD+=$(KQUEUE_LIBS)
</pre>
</li>
</ol>
Instead of using the <code>$(KQUEUE_LIBS)</code> variable, you could just add <code>libkqueue.la</code> to your programs LDADD variable.
<h3>Threads</h3>
libkqueue uses one or more helper threads, so all programs that link with libkqueue must also link against the pthreads library. Calls to <code>kqueue()</code> and <code>kevent()</code> are safe to be used from multiple threads.
m4_include(footer.m4)