libipq/ipq_set_mode.3

   1 .TH IPQ_SET_MODE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 .\" $Id: ipq_set_mode.3,v 1.1 2000/11/20 14:13:32 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_set_mode - set the ip_queue queuing mode
  24 .SH SYNOPSIS
  25 .B #include <linux/netfilter.h>
  26 .br
  27 .B #include <libipq.h>
  28 .sp
  29 .BI "int ipq_set_mode(const struct ipq_handle *" h ", u_int8_t " mode ", size_t " range );
  30 .SH DESCRIPTION
  31 The
  32 .B ipq_set_mode
  33 function sends a message to the kernel ip_queue module, specifying whether
  34 packet metadata only, or packet payloads as well as metadata should be copied to
  35 userspace.
  36 .PP
  37 The
  38 .I h
  39 parameter is a context handle which must previously have been returned
  40 successfully from a call to
  41 .BR ipq_create_handle .
  42 .PP
  43 The
  44 .I mode
  45 parameter must be one of:
  46 .TP
  47 .B IPQ_COPY_META
  48 Copy only packet metadata to userspace.
  49 .TP
  50 .B IPQ_COPY_PACKET
  51 Copy packet metadata and packet payloads to userspace.
  52 .PP
  53 The
  54 .I range
  55 parameter is used to specify how many bytes of the payload to copy
  56 to userspace.  It is only valid for
  57 .B IPQ_COPY_PACKET
  58 mode and is otherwise ignored.  The maximum useful value for
  59 .I range
  60 is 65535 (greater values will be clamped to this by ip_queue).
  61 .PP
  62 .B ipq_set_mode
  63 is usually used immediately following
  64 .B ipq_create_handle
  65 to enable the flow of packets to userspace.
  66 .PP
  67 Note that as the underlying Netlink messaging transport is connectionless,
  68 the ip_queue module does not know that a userspace application is ready to
  69 communicate until it receives a message such as this.
  70 .SH RETURN VALUE
  71 On failure, -1 is returned.
  72 .br
  73 On success, a non-zero positive value is returned.
  74 .SH ERRORS
  75 On failure, a descriptive error message will be available
  76 via the
  77 .B ipq_errstr
  78 function.
  79 .SH DIAGNOSTICS
  80 A relatively common failure may occur if the ip_queue module is not loaded.
  81 In this case, the following code excerpt:
  82 .PP
  83 .RS
  84 .nf
  85 status = ipq_set_mode(h, IPQ_COPY_META, 0);
  86 if (status < 0) {
  87         ipq_perror("myapp");
  88         ipq_destroy_handle(h);
  89         exit(1);
  90 }
  91 .RE
  92 .fi
  93 .PP
  94 would generate the following output:
  95 .PP
  96 .I myapp: Failed to send netlink message: Connection refused
  97 .SH BUGS
  98 None known.
  99 .SH AUTHOR
 100 James Morris <jmorris@intercode.com.au>
 101 .SH COPYRIGHT
 102 Copyright (c) 2000-2001 Netfilter Core Team.
 103 .PP
 104 Distributed under the GNU General Public License.
 105 .SH SEE ALSO
 106 .BR libipq (3),
 107 .BR iptables (8).