Merge commit 'origin/trunk@12184' into fedora

[iptables.git] / trunk / libipq / ipq_create_handle.3

diff --git a/trunk/libipq/ipq_create_handle.3 b/trunk/libipq/ipq_create_handle.3
new file mode 100644 (file)
index 0000000..c833e88
--- /dev/null
+++ b/trunk/libipq/ipq_create_handle.3
@@ -0,0 +1,84 @@
+.TH IPQ_CREATE_HANDLE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" 
+.\"
+\" $Id: ipq_create_handle.3,v 1.2 2001/10/16 14:41:02 jamesm Exp $
+.\"
+.\"     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_create_handle, ipq_destroy_handle - create and destroy libipq handles.
+.SH SYNOPSIS
+.B #include <linux/netfilter.h>
+.br
+.B #include <libipq.h>
+.sp
+.BI "struct ipq_handle *ipq_create_handle(u_int32_t " flags ", u_int32_t " protocol ");"
+.br
+.BI "int ipq_destroy_handle(struct ipq_handle *" h );
+.SH DESCRIPTION
+The
+.B ipq_create_handle
+function initialises libipq for an application, attempts to bind to the
+Netlink socket used by ip_queue, and returns an opaque context handle.  It
+should be the first libipq function to be called by an application.  The
+handle returned should be used in all subsequent library calls which 
+require a handle parameter.
+.PP
+The
+.I flags
+parameter is not currently used and should be set to zero by the application
+for forward compatibility.
+.PP
+The
+.I protocol
+parameter is used to specify the protocol of the packets to be queued.
+Valid values are PF_INET for IPv4 and PF_INET6 for IPv6.  Currently, 
+only one protocol may be queued at a time for a handle.
+.PP
+The
+.B ipq_destroy_handle
+function frees up resources allocated by
+.BR ipq_create_handle ,
+and should be used when the handle is no longer required by the application.
+.SH RETURN VALUES
+On success,
+.B ipq_create_handle
+returns a pointer to a context handle.
+.br
+On failure, NULL is returned.
+.PP
+On success,
+.B ipq_destroy_handle
+returns zero.
+.br
+On failure, -1 is returned.
+.SH ERRORS
+On failure, a descriptive error message will be available
+via the
+.B ipq_errstr
+function.
+.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 iptables (8),
+.BR libipq (3).