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/INSTALL b/INSTALL
index 4539232e59a84380f496eabf01616eb62d176da6..62b4f175e9b0b6471911e56f6772f18c3c6794b1 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -13,7 +13,8 @@ FOLLOW THESE STEPS:
 2) Finally, you need to to install the shared libraries, and the binary:
        # make install KERNEL_DIR=<<where-your-kernel-is>>
 
-If you are a developer, you can install the header files, like:
+If you are a developer, you can install the headers, development libraries
+and associated development man pages, with:
        # make install-devel
 
 That's it!

diff --git a/libipq/ipq_create_handle.3 b/libipq/ipq_create_handle.3
index 5c981371167d7b6ad30c343333f575ab76880103..da99e54940da22cba38379295ec7d67af886a622 100644 (file)
--- a/libipq/ipq_create_handle.3
+++ b/libipq/ipq_create_handle.3
@@ -1,8 +1,8 @@
-.TH IPQ_CREATE_HANDLE 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" 
+.TH IPQ_CREATE_HANDLE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
 .\"
-\" $Id: $
+\" $Id: ipq_create_handle.3,v 1.1 2000/11/20 14:13:31 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
@@ -70,7 +70,7 @@ 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 SEE ALSO

diff --git a/libipq/ipq_errstr.3 b/libipq/ipq_errstr.3
index ec43ff6bb859511ce3997807577f847aa9b9685a..96614694810d90fd0aa7bc76592e1722acc47734 100644 (file)
--- a/libipq/ipq_errstr.3
+++ b/libipq/ipq_errstr.3
@@ -1,6 +1,6 @@
-.TH IPQ_ERRSTR 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" 
+.TH IPQ_ERRSTR 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
 .\"
-.\" $Id: $
+.\" $Id: ipq_errstr.3,v 1.1 2000/11/20 14:13:32 jamesm Exp $
 .\"
 .\"     Copyright (c) 2000 Netfilter Core Team
 .\"
@@ -58,7 +58,7 @@ 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 SEE ALSO

diff --git a/libipq/ipq_message_type.3 b/libipq/ipq_message_type.3
index 4a2de1dcd9778c4967021be52566c8485097f59d..0594518f2d60e8f534c0eff64b4ea1b8fcf6bf38 100644 (file)
--- a/libipq/ipq_message_type.3
+++ b/libipq/ipq_message_type.3
@@ -1,8 +1,8 @@
-.TH IPQ_MESSAGE_TYPE 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" 
+.TH IPQ_MESSAGE_TYPE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
 .\"
-.\" $Id: $
+.\" $Id: ipq_message_type.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
@@ -128,7 +128,7 @@ 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 SEE ALSO

diff --git a/libipq/ipq_read.3 b/libipq/ipq_read.3
index 62763ca44e23692eee5089b8d7dba46f2fed7c7f..14867dda2644226f4db50616b446227b57a5c032 100644 (file)
--- 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 @@ ipq_read - wait for queue messages from ip_queue and read into supplied buffer
 .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 @@ bytes.
 .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 @@ functions to access the queue message in the buffer.
 .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 @@ may itself be an error message from a higher level kernel component.  Use
 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).
 

diff --git a/libipq/ipq_set_mode.3 b/libipq/ipq_set_mode.3
index ad1d0e95020c0b1d9bd9b8d4f80a28f97970cf68..241581eb81b91f3ac7d883da4301180bcb747b6a 100644 (file)
--- a/libipq/ipq_set_mode.3
+++ b/libipq/ipq_set_mode.3
@@ -1,8 +1,8 @@
-.TH IPQ_SET_MODE 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" 
+.TH IPQ_SET_MODE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
 .\"
-.\" $Id: $
+.\" $Id: ipq_set_mode.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
@@ -99,7 +99,7 @@ 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 SEE ALSO

diff --git a/libipq/ipq_set_verdict.3 b/libipq/ipq_set_verdict.3
index de4ccdbf63bd95fed61590805132fafb689076b2..84a94119c63a74d29cacacca6724c66685b15276 100644 (file)
--- a/libipq/ipq_set_verdict.3
+++ b/libipq/ipq_set_verdict.3
@@ -1,8 +1,8 @@
-.TH IPQ_SET_VERDICT 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" 
+.TH IPQ_SET_VERDICT 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
 .\"
-.\" $Id: $
+.\" $Id: ipq_set_verdict.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
@@ -86,7 +86,7 @@ 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 SEE ALSO

diff --git a/libipq/libipq.3 b/libipq/libipq.3
index 1d2e498c8389964d6d1ef248c81a2c0418c80033..54898bf6dd1f8bb8a3fd24752eab15d25f7ffd80 100644 (file)
--- a/libipq/libipq.3
+++ b/libipq/libipq.3
@@ -1,8 +1,8 @@
-.TH LIBIPQ 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual" 
+.TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
 .\"
-.\" $Id: libipq.3,v 1.1 2000/11/20 14:13:32 jamesm Exp $
+.\" $Id: libipq.3,v 1.2 2001/05/26 20:32:01 laforge 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
@@ -242,8 +242,6 @@ Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue
 module.  Such processes can potentially access and modify any IP packets
 received, generated or forwarded by the kernel.
 .SH TODO
-Implement a non-blocking interface.
-.br
 Per-handle
 .B ipq_errno
 values.
@@ -252,9 +250,13 @@ Probably.
 .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
+.B ipq_read
+timeout feature, which appeared in the 1.2.4 release of iptables.
 .SH SEE ALSO
 .BR iptables (8),
 .BR ipq_create_handle (3),
@@ -268,7 +270,7 @@ Distributed under the GNU General Public License.
 .BR ipq_set_mode (3),
 .BR ipq_set_verdict (3).
 .PP
-The Netfilter home page at http://netfilter.gnumonks.org/
+The Netfilter home page at http://netfilter.samba.org/
 which has links to The Networking Concepts HOWTO, The Linux 2.4 Packet
 Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO,
 The Netfilter FAQ and many other useful resources.