libipq/ipq_read.3

   1 .TH IPQ_READ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 .\" $Id: ipq_read.3,v 1.2 2001/10/16 14:41:02 jamesm Exp $
   4 .\"
   5 .\"     Copyright (c) 2000-2001 Netfilter Core Team
   6 .\"
   7 .\"     This program is free software; you can redistribute it and/or modify
   8 .\"     it under the terms of the GNU General Public License as published by
   9 .\"     the Free Software Foundation; either version 2 of the License, or
  10 .\"     (at your option) any later version.
  11 .\"
  12 .\"     This program is distributed in the hope that it will be useful,
  13 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 .\"     GNU General Public License for more details.
  16 .\"
  17 .\"     You should have received a copy of the GNU General Public License
  18 .\"     along with this program; if not, write to the Free Software
  19 .\"     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20 .\"
  21 .\"
  22 .SH NAME
  23 ipq_read - read queue messages from ip_queue and read into supplied buffer
  24 .SH SYNOPSIS
  25 .B #include <linux/netfilter.h>
  26 .br
  27 .B #include <libipq.h>
  28 .sp
  29 .BI "ssize_t ipq_read(const struct ipq_handle *" h ", unsigned char *" buf ", size_t " len ", int " timeout ");"
  30 .SH DESCRIPTION
  31 The
  32 .B ipq_read
  33 function reads a queue message from the kernel and copies it to
  34 the memory pointed to by
  35 .I buf
  36 to a maximum length of
  37 . IR len .
  38 .PP
  39 The
  40 .I h
  41 parameter is a context handle which must previously have been returned
  42 successfully from a call to
  43 .BR ipq_create_handle .
  44 .PP
  45 The caller is responsible for ensuring that the memory pointed to by
  46 .I buf
  47 is large enough to contain
  48 .I len
  49 bytes.
  50 .PP
  51 The
  52 .I timeout
  53 parameter may be used to set a timeout for the operation, specified in microseconds.
  54 This is implemented internally by the library via the
  55 .BR select
  56 system call.  A value of zero provides normal, backwards-compatible blocking behaviour
  57 with no timeout.  A negative value causes the function to return immediately.
  58 .PP
  59 Data returned via
  60 .I buf
  61 should not be accessed directly.  Use the
  62 .BR ipq_message_type ,
  63 .BR ipq_get_packet ", and"
  64 .BR ipq_get_msgerr
  65 functions to access the queue message in the buffer.
  66 .SH RETURN VALUE
  67 On failure, -1 is returned.
  68 .br
  69 On success, a non-zero positive value is returned when no timeout
  70 value is specified.
  71 .br
  72 On success with a timeout value specified, zero is returned if no data
  73 was available to read, or if a non-blocked signal was caught.  In the
  74 latter case, the global
  75 .B errno
  76 value will be set to
  77 .BR EINTR .
  78 .SH ERRORS
  79 On error, a descriptive error message will be available
  80 via the
  81 .B ipq_errstr
  82 function.
  83 .SH DIAGNOSTICS
  84 While the
  85 .B ipq_read
  86 function may return successfully, the queue message copied to the buffer
  87 may itself be an error message from a higher level kernel component.  Use
  88 .B ipq_message_type
  89 to determine if it is an error message, and
  90 .B ipq_get_msgerr
  91 to access the value of the message.
  92 .SH BUGS
  93 None known.
  94 .SH AUTHOR
  95 James Morris <jmorris@intercode.com.au>
  96 .SH COPYRIGHT
  97 Copyright (c) 2000-2001 Netfilter Core Team.
  98 .PP
  99 Distributed under the GNU General Public License.
 100 .SH CREDITS
 101 Joost Remijn implemented the timeout feature, which appeared in the 1.2.4 release of iptables.
 102 .SH SEE ALSO
 103 .BR iptables (8),
 104 .BR libipq (3),
 105 .BR select (2).
 106