Updated libipq documentation with information on new timeout feature,
as well as minor miscellaneous updates. Added a bit more info to the
install-devel description in the INSTALL file.
diff --git a/libipq/ipq_read.3 b/libipq/ipq_read.3
index 62763ca..14867dd 100644
--- a/libipq/ipq_read.3
+++ b/libipq/ipq_read.3
@@ -1,8 +1,8 @@
-.TH IPQ_READ 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual"
+.TH IPQ_READ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
.\"
-.\" $Id: $
+.\" $Id: ipq_read.3,v 1.1 2000/11/20 14:13:32 jamesm Exp $
.\"
-.\" Copyright (c) 2000 Netfilter Core Team
+.\" Copyright (c) 2000-2001 Netfilter Core Team
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
@@ -20,7 +20,7 @@
.\"
.\"
.SH NAME
-ipq_read - wait for queue messages from ip_queue and read into supplied buffer
+ipq_read - read queue messages from ip_queue and read into supplied buffer
.SH SYNOPSIS
.B #include <linux/netfilter.h>
.br
@@ -30,17 +30,17 @@
.SH DESCRIPTION
The
.B ipq_read
-function waits for a queue message to arrive from the kernel and copies it to
+function reads a queue message from the kernel and copies it to
the memory pointed to by
.I buf
to a maximum length of
-. I len .
+. IR len .
.PP
The
.I h
parameter is a context handle which must previously have been returned
successfully from a call to
-.B ipq_create_handle .
+.BR ipq_create_handle .
.PP
The caller is responsible for ensuring that the memory pointed to by
.I buf
@@ -50,7 +50,11 @@
.PP
The
.I timeout
-parameter is not currently implemented.
+parameter may be used to set a timeout for the operation, specified in microseconds.
+This is implemented internally by the library via the
+.BR select
+system call. A value of zero provides normal, backwards-compatible blocking behaviour
+with no timeout. A negative value causes the function to return immediately.
.PP
Data returned via
.I buf
@@ -62,7 +66,15 @@
.SH RETURN VALUE
On failure, -1 is returned.
.br
-On success, a non-zero positive value is returned.
+On success, a non-zero positive value is returned when no timeout
+value is specified.
+.br
+On success with a timeout value specified, zero is returned if no data
+was available to read, or if a non-blocked signal was caught. In the
+latter case, the global
+.B errno
+value will be set to
+.BR EINTR .
.SH ERRORS
On error, a descriptive error message will be available
via the
@@ -77,19 +89,18 @@
to determine if it is an error message, and
.B ipq_get_msgerr
to access the value of the message.
-.SH TODO
-Implement
-.I timeout
-as part of a non-blocking interface.
.SH BUGS
None known.
.SH AUTHOR
James Morris <jmorris@intercode.com.au>
.SH COPYRIGHT
-Copyright (c) 2000 Netfilter Core Team.
+Copyright (c) 2000-2001 Netfilter Core Team.
.PP
Distributed under the GNU General Public License.
+.SH CREDITS
+Joost Remij implemented the timeout feature, which appeared in the 1.2.4 release of iptables.
.SH SEE ALSO
.BR iptables (8),
-.BR libipq (3).
+.BR libipq (3),
+.BR select (2).