libipq/ipq_message_type.3

   1 .TH IPQ_MESSAGE_TYPE 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 .\" $Id: ipq_message_type.3,v 1.1 2000/11/20 14:13:32 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_message_type, ipq_get_packet, ipq_getmsgerr - query queue messages
  24 .SH SYNOPSIS
  25 .B #include <linux/netfilter.h>
  26 .br
  27 .B #include <libipq.h>
  28 .sp
  29 .BI "int ipq_message_type(const unsigned char *" buf ");"
  30 .br
  31 .BI "ipq_packet_msg_t *ipq_get_packet(const unsigned char *" buf ");"
  32 .br
  33 .BI "int ipq_get_msgerr(const unsigned char *" buf ");"
  34 .SH DESCRIPTION
  35 The
  36 .B ipq_message_type
  37 function returns the type of queue message returned to userspace
  38 via
  39 .BR ipq_read .
  40 .PP
  41 .B ipq_message_type
  42 should always be called following a successful call to
  43 .B ipq_read
  44 to determine whether the message is a packet message or an
  45 error message. The
  46 .I buf
  47 parameter should be the same data obtained from
  48 the previous call to
  49 .BR ipq_read .
  50 .PP
  51 .B ipq_message_type
  52 will return one of the following values:
  53 .TP
  54 .B NLMSG_ERROR
  55 An error message generated by the Netlink transport.
  56 .PP
  57 .TP
  58 .B IPQM_PACKET
  59 A packet message containing packet metadata and optional packet payload data.
  60 .PP
  61 The
  62 .B ipq_get_packet
  63 function should be called if
  64 .B ipq_message_type
  65 returns
  66 .BR IPQM_PACKET .
  67 The
  68 .I buf
  69 parameter should point to the same data used for the call to
  70 .BR ipq_message_type .
  71 The pointer returned by
  72 .B ipq_get_packet
  73 points to a packet message, which is declared as follows:
  74 .PP
  75 .RS
  76 .nf
  77 typedef struct ipq_packet_msg {
  78         unsigned long packet_id;        /* ID of queued packet */
  79         unsigned long mark;             /* Netfilter mark value */
  80         long timestamp_sec;             /* Packet arrival time (seconds) */
  81         long timestamp_usec;            /* Packet arrvial time (+useconds) */
  82         unsigned int hook;              /* Netfilter hook we rode in on */
  83         char indev_name[IFNAMSIZ];      /* Name of incoming interface */
  84         char outdev_name[IFNAMSIZ];     /* Name of outgoing interface */
  85         unsigned short hw_protocol;     /* Hardware protocol (network order) */
  86         unsigned short hw_type;         /* Hardware type */
  87         unsigned char hw_addrlen;       /* Hardware address length */
  88         unsigned char hw_addr[8];       /* Hardware address */
  89         size_t data_len;                /* Length of packet data */
  90         unsigned char payload[0];       /* Optional packet data */
  91 } ipq_packet_msg_t;
  92 .fi
  93 .RE
  94 .PP
  95 Each of these fields may be read by the application.  If the queue mode
  96 is
  97 .B IPQ_COPY_PACKET
  98 and the
  99 .I data_len
 100 value is greater than zero, the packet payload contents may be accessed
 101 in the memory following the
 102 .B ipq_packet_msg_t
 103 structure to a range of
 104 .I data_len.
 105 .PP
 106 The
 107 .I packet_id
 108 field contains a packet identifier to be used when calling
 109 .BR ipq_set_verdict .
 110 .PP
 111 The
 112 .B ipq_get_msgerr
 113 function should be called if
 114 .B ipq_message_type
 115 returns
 116 .BR NLMSG_ERROR.
 117 The
 118 .I buf
 119 parameter should point to the same data used for the call to
 120 .BR ipq_message_type .
 121 The value returned by
 122 .B ipq_get_msgerr
 123 is set by higher level kernel code and corresponds to standard
 124 .B errno
 125 values.
 126 .SH BUGS
 127 None known.
 128 .SH AUTHOR
 129 James Morris <jmorris@intercode.com.au>
 130 .SH COPYRIGHT
 131 Copyright (c) 2000-2001 Netfilter Core Team.
 132 .PP
 133 Distributed under the GNU General Public License.
 134 .SH SEE ALSO
 135 .BR iptables (8),
 136 .BR libipq (3).