libipq/ipq_create_handle.3

   1 .TH IPQ_CREATE_HANDLE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 \" $Id: ipq_create_handle.3,v 1.2 2001/10/16 14:41:02 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_create_handle, ipq_destroy_handle - create and destroy libipq handles.
  24 .SH SYNOPSIS
  25 .B #include <linux/netfilter.h>
  26 .br
  27 .B #include <libipq.h>
  28 .sp
  29 .BI "struct ipq_handle *ipq_create_handle(u_int32_t " flags ", u_int32_t " protocol ");"
  30 .br
  31 .BI "int ipq_destroy_handle(struct ipq_handle *" h );
  32 .SH DESCRIPTION
  33 The
  34 .B ipq_create_handle
  35 function initialises libipq for an application, attempts to bind to the
  36 Netlink socket used by ip_queue, and returns an opaque context handle.  It
  37 should be the first libipq function to be called by an application.  The
  38 handle returned should be used in all subsequent library calls which
  39 require a handle parameter.
  40 .PP
  41 The
  42 .I flags
  43 parameter is not currently used and should be set to zero by the application
  44 for forward compatibility.
  45 .PP
  46 The
  47 .I protocol
  48 parameter is used to specify the protocol of the packets to be queued.
  49 Valid values are PF_INET for IPv4 and PF_INET6 for IPv6.  Currently,
  50 only one protocol may be queued at a time for a handle.
  51 .PP
  52 The
  53 .B ipq_destroy_handle
  54 function frees up resources allocated by
  55 .BR ipq_create_handle ,
  56 and should be used when the handle is no longer required by the application.
  57 .SH RETURN VALUES
  58 On success,
  59 .B ipq_create_handle
  60 returns a pointer to a context handle.
  61 .br
  62 On failure, NULL is returned.
  63 .PP
  64 On success,
  65 .B ipq_destroy_handle
  66 returns zero.
  67 .br
  68 On failure, -1 is returned.
  69 .SH ERRORS
  70 On failure, a descriptive error message will be available
  71 via the
  72 .B ipq_errstr
  73 function.
  74 .SH BUGS
  75 None known.
  76 .SH AUTHOR
  77 James Morris <jmorris@intercode.com.au>
  78 .SH COPYRIGHT
  79 Copyright (c) 2000-2001 Netfilter Core Team.
  80 .PP
  81 Distributed under the GNU General Public License.
  82 .SH SEE ALSO
  83 .BR iptables (8),
  84 .BR libipq (3).