From a2c342cef9b70c9dc8c5d5f7a1bd8fd59d264555 Mon Sep 17 00:00:00 2001
From: jamesm <jamesm>
Date: Tue, 16 Oct 2001 14:41:02 +0000
Subject: 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.

---
 libipq/ipq_read.3 | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

(limited to 'libipq/ipq_read.3')

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 @@ 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).
 
-- 
cgit v1.2.3