| .TH IPQ_SET_MODE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" |
| .\" |
| .\" 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 |
| .\" 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 \(em 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-2001 Netfilter Core Team. |
| .PP |
| Distributed under the GNU General Public License. |
| .SH SEE ALSO |
| .BR libipq (3), |
| .BR iptables (8). |