summaryrefslogtreecommitdiffstats
path: root/libipq/ipq_set_mode.3
diff options
context:
space:
mode:
authorJames Morris <jmorris@intercode.com.au>2000-11-20 14:13:31 +0000
committerJames Morris <jmorris@namei.org>2000-11-20 14:13:31 +0000
commit949810c35a0871d9173764e2ac3b4d814f982b9e (patch)
tree7a8c24a669a922a1d204302ad8497c91b09db544 /libipq/ipq_set_mode.3
parentb1e0b99aff57351419c24c618ccb00ae0fb142f9 (diff)
Initial commit of libipq man pages.
Diffstat (limited to 'libipq/ipq_set_mode.3')
-rw-r--r--libipq/ipq_set_mode.3107
1 files changed, 107 insertions, 0 deletions
diff --git a/libipq/ipq_set_mode.3 b/libipq/ipq_set_mode.3
new file mode 100644
index 00000000..ad1d0e95
--- /dev/null
+++ b/libipq/ipq_set_mode.3
@@ -0,0 +1,107 @@
+.TH IPQ_SET_MODE 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual"
+.\"
+.\" $Id: $
+.\"
+.\" Copyright (c) 2000 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
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program; if not, write to the Free Software
+.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+.\"
+.\"
+.SH NAME
+ipq_set_mode - set the ip_queue queuing mode
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "int ipq_set_mode(const struct ipq_handle *" h ", u_int8_t " mode ", size_t " range );
+.SH DESCRIPTION
+The
+.B ipq_set_mode
+function sends a message to the kernel ip_queue module, specifying whether
+packet metadata only, or packet payloads as well as metadata should be copied to
+userspace.
+.PP
+The
+.I h
+parameter is a context handle which must previously have been returned
+successfully from a call to
+.BR ipq_create_handle .
+.PP
+The
+.I mode
+parameter must be one of:
+.TP
+.B IPQ_COPY_META
+Copy only packet metadata to userspace.
+.TP
+.B IPQ_COPY_PACKET
+Copy packet metadata and packet payloads to userspace.
+.PP
+The
+.I range
+parameter is used to specify how many bytes of the payload to copy
+to userspace. It is only valid for
+.B IPQ_COPY_PACKET
+mode and is otherwise ignored. The maximum useful value for
+.I range
+is 65535 (greater values will be clamped to this by ip_queue).
+.PP
+.B ipq_set_mode
+is usually used immediately following
+.B ipq_create_handle
+to enable the flow of packets to userspace.
+.PP
+Note that as the underlying Netlink messaging transport is connectionless,
+the ip_queue module does not know that a userspace application is ready to
+communicate until it receives a message such as this.
+.SH RETURN VALUE
+On failure, -1 is returned.
+.br
+On success, a non-zero positive value is returned.
+.SH ERRORS
+On failure, a descriptive error message will be available
+via the
+.B ipq_errstr
+function.
+.SH DIAGNOSTICS
+A relatively common failure may occur if the ip_queue module is not loaded.
+In this case, the following code excerpt:
+.PP
+.RS
+.nf
+status = ipq_set_mode(h, IPQ_COPY_META, 0);
+if (status < 0) {
+ ipq_perror("myapp");
+ ipq_destroy_handle(h);
+ exit(1);
+}
+.RE
+.fi
+.PP
+would generate the following output:
+.PP
+.I myapp: Failed to send netlink message: Connection refused
+.SH BUGS
+None known.
+.SH AUTHOR
+James Morris <jmorris@intercode.com.au>
+.SH COPYRIGHT
+Copyright (c) 2000 Netfilter Core Team.
+.PP
+Distributed under the GNU General Public License.
+.SH SEE ALSO
+.BR libipq (3),
+.BR iptables (8).