original/man3/ipq_set_mode.3

   1 .TH IPQ_SET_MODE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 .\"     Copyright (c) 2000-2001 Netfilter Core Team
   4 .\"
   5 .\"     This program is free software; you can redistribute it and/or modify
   6 .\"     it under the terms of the GNU General Public License as published by
   7 .\"     the Free Software Foundation; either version 2 of the License, or
   8 .\"     (at your option) any later version.
   9 .\"
  10 .\"     This program is distributed in the hope that it will be useful,
  11 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"     GNU General Public License for more details.
  14 .\"
  15 .\"     You should have received a copy of the GNU General Public License
  16 .\"     along with this program; if not, write to the Free Software
  17 .\"     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18 .\"
  19 .\"
  20 .SH NAME
  21 ipq_set_mode \(em set the ip_queue queuing mode
  22 .SH SYNOPSIS
  23 .B #include <linux/netfilter.h>
  24 .br
  25 .B #include <libipq.h>
  26 .sp
  27 .BI "int ipq_set_mode(const struct ipq_handle *" h ", u_int8_t " mode ", size_t " range );
  28 .SH DESCRIPTION
  29 The
  30 .B ipq_set_mode
  31 function sends a message to the kernel ip_queue module, specifying whether
  32 packet metadata only, or packet payloads as well as metadata should be copied to
  33 userspace.
  34 .PP
  35 The
  36 .I h
  37 parameter is a context handle which must previously have been returned
  38 successfully from a call to
  39 .BR ipq_create_handle .
  40 .PP
  41 The
  42 .I mode
  43 parameter must be one of:
  44 .TP
  45 .B IPQ_COPY_META
  46 Copy only packet metadata to userspace.
  47 .TP
  48 .B IPQ_COPY_PACKET
  49 Copy packet metadata and packet payloads to userspace.
  50 .PP
  51 The
  52 .I range
  53 parameter is used to specify how many bytes of the payload to copy
  54 to userspace.  It is only valid for
  55 .B IPQ_COPY_PACKET
  56 mode and is otherwise ignored.  The maximum useful value for
  57 .I range
  58 is 65535 (greater values will be clamped to this by ip_queue).
  59 .PP
  60 .B ipq_set_mode
  61 is usually used immediately following
  62 .B ipq_create_handle
  63 to enable the flow of packets to userspace.
  64 .PP
  65 Note that as the underlying Netlink messaging transport is connectionless,
  66 the ip_queue module does not know that a userspace application is ready to
  67 communicate until it receives a message such as this.
  68 .SH RETURN VALUE
  69 On failure, \-1 is returned.
  70 .br
  71 On success, a non-zero positive value is returned.
  72 .SH ERRORS
  73 On failure, a descriptive error message will be available
  74 via the
  75 .B ipq_errstr
  76 function.
  77 .SH DIAGNOSTICS
  78 A relatively common failure may occur if the ip_queue module is not loaded.
  79 In this case, the following code excerpt:
  80 .PP
  81 .RS
  82 .nf
  83 status = ipq_set_mode(h, IPQ_COPY_META, 0);
  84 if (status < 0) {
  85         ipq_perror("myapp");
  86         ipq_destroy_handle(h);
  87         exit(1);
  88 }
  89 .RE
  90 .fi
  91 .PP
  92 would generate the following output:
  93 .PP
  94 .I myapp: Failed to send netlink message: Connection refused
  95 .SH BUGS
  96 None known.
  97 .SH AUTHOR
  98 James Morris <jmorris@intercode.com.au>
  99 .SH COPYRIGHT
 100 Copyright (c) 2000-2001 Netfilter Core Team.
 101 .PP
 102 Distributed under the GNU General Public License.
 103 .SH SEE ALSO
 104 .BR libipq (3),
 105 .BR iptables (8).