path: root/libipq/ipq_read.3
diff options
authorjamesm <jamesm>2001-10-16 14:41:02 +0000
committerjamesm <jamesm>2001-10-16 14:41:02 +0000
commita2c342cef9b70c9dc8c5d5f7a1bd8fd59d264555 (patch)
tree607d357ebf06590a8f62c9ec0fe825b501c5f8f1 /libipq/ipq_read.3
parent53f7368a04b654a2fdeef2da827de67fc81a262e (diff)
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.
Diffstat (limited to 'libipq/ipq_read.3')
1 files changed, 26 insertions, 15 deletions
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 @@
-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
.B #include <linux/netfilter.h>
@@ -30,17 +30,17 @@ ipq_read - wait for queue messages from ip_queue and read into supplied buffer
.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 .
.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 .
The caller is responsible for ensuring that the memory pointed to by
.I buf
@@ -50,7 +50,11 @@ bytes.
.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.
Data returned via
.I buf
@@ -62,7 +66,15 @@ functions to access the queue message in the buffer.
On failure, -1 is returned.
-On success, a non-zero positive value is returned.
+On success, a non-zero positive value is returned when no timeout
+value is specified.
+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
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.
-.I timeout
-as part of a non-blocking interface.
None known.
James Morris <>
-Copyright (c) 2000 Netfilter Core Team.
+Copyright (c) 2000-2001 Netfilter Core Team.
Distributed under the GNU General Public License.
+Joost Remij implemented the timeout feature, which appeared in the 1.2.4 release of iptables.
.BR iptables (8),
-.BR libipq (3).
+.BR libipq (3),
+.BR select (2).