1PACKET(7)                  Linux Programmer's Manual                 PACKET(7)
2
3
4

NAME

6       packet, PF_PACKET - packet interface on device level.
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <netpacket/packet.h>
11       #include <net/ethernet.h> /* the L2 protocols */
12
13       packet_socket = socket(PF_PACKET, int socket_type, int protocol);
14

DESCRIPTION

16       Packet  sockets  are  used to receive or send raw packets at the device
17       driver (OSI Layer 2) level. They allow the user to  implement  protocol
18       modules in user space on top of the physical layer.
19
20       The  socket_type  is either SOCK_RAW for raw packets including the link
21       level header or SOCK_DGRAM for  cooked  packets  with  the  link  level
22       header  removed.  The  link  level header information is available in a
23       common format in a sockaddr_ll.  protocol is the  IEEE  802.3  protocol
24       number  in network order. See the <linux/if_ether.h> include file for a
25       list of allowed protocols. When protocol  is  set  to  htons(ETH_P_ALL)
26       then all protocols are received.  All incoming packets of that protocol
27       type will be passed to the packet socket before they are passed to  the
28       protocols implemented in the kernel.
29
30       Only  processes  with effective UID 0 or the CAP_NET_RAW capability may
31       open packet sockets.
32
33       SOCK_RAW packets are passed to and from the device driver  without  any
34       changes  in  the  packet data.  When receiving a packet, the address is
35       still parsed and passed in a standard  sockaddr_ll  address  structure.
36       When transmitting a packet, the user supplied buffer should contain the
37       physical layer header.  That packet is then queued  unmodified  to  the
38       network  driver  of  the  interface defined by the destination address.
39       Some device drivers always add other headers.  SOCK_RAW is  similar  to
40       but not compatible with the obsolete PF_INET/SOCK_PACKET of Linux 2.0.
41
42       SOCK_DGRAM operates on a slightly higher level.  The physical header is
43       removed before the packet is passed to the user.  Packets sent  through
44       a  SOCK_DGRAM  packet socket get a suitable physical layer header based
45       on the information in the sockaddr_ll destination address  before  they
46       are queued.
47
48       By  default  all packets of the specified protocol type are passed to a
49       packet socket.  To only get  packets  from  a  specific  interface  use
50       bind(2)  specifying  an  address  in  a  struct sockaddr_ll to bind the
51       packet  socket  to  an  interface.  Only  the  sll_protocol   and   the
52       sll_ifindex address fields are used for purposes of binding.
53
54       The connect(2) operation is not supported on packet sockets.
55
56       When  the  MSG_TRUNC flag is passed to recvmsg(2), recv(2), recvfrom(2)
57       the real length of the packet on the wire is always returned, even when
58       it is longer than the buffer.
59
60

ADDRESS TYPES

62       The sockaddr_ll is a device independent physical layer address.
63
64         struct sockaddr_ll {
65             unsigned short sll_family;   /* Always AF_PACKET */
66             unsigned short sll_protocol; /* Physical layer protocol */
67             int            sll_ifindex;  /* Interface number */
68             unsigned short sll_hatype;   /* Header type */
69             unsigned char  sll_pkttype;  /* Packet type */
70             unsigned char  sll_halen;    /* Length of address */
71             unsigned char  sll_addr[8];  /* Physical layer address */
72         };
73
74       sll_protocol is the standard ethernet protocol type in network order as
75       defined in the <linux/if_ether.h> include file.   It  defaults  to  the
76       socket's protocol.  sll_ifindex is the interface index of the interface
77       (see netdevice(7)); 0 matches any interface (only legal  for  binding).
78       sll_hatype  is  a  ARP  type as defined in the <linux/if_arp.h> include
79       file.   sll_pkttype  contains  the  packet  type.   Valid   types   are
80       PACKET_HOST  for a packet addressed to the local host, PACKET_BROADCAST
81       for a physical layer broadcast packet, PACKET_MULTICAST  for  a  packet
82       sent  to  a  physical  layer  multicast address, PACKET_OTHERHOST for a
83       packet to some other host that has been caught by a  device  driver  in
84       promiscuous  mode, and PACKET_OUTGOING for a packet originated from the
85       local host that is looped back to a packet  socket.  These  types  make
86       only  sense for receiving.  sll_addr and sll_halen contain the physical
87       layer (e.g. IEEE 802.3) address and its length. The  exact  interpreta‐
88       tion depends on the device.
89
90       When  you  send  packets  it is enough to specify sll_family, sll_addr,
91       sll_halen, sll_ifindex.  The other fields should be 0.  sll_hatype  and
92       sll_pkttype are set on received packets for your information.  For bind
93       only sll_protocol and sll_ifindex are used.
94
95

SOCKET OPTIONS

97       Packet sockets can be used to configure physical layer multicasting and
98       promiscuous  mode. It works by calling setsockopt(2) on a packet socket
99       for SOL_PACKET and one of the options PACKET_ADD_MEMBERSHIP  to  add  a
100       binding  or  PACKET_DROP_MEMBERSHIP  to  drop  it.   They both expect a
101       packet_mreq structure as argument:
102
103         struct packet_mreq {
104             int            mr_ifindex;    /* interface index */
105             unsigned short mr_type;       /* action */
106             unsigned short mr_alen;       /* address length */
107             unsigned char  mr_address[8]; /* physical layer address */
108         };
109
110       mr_ifindex contains the interface index for the interface whose  status
111       should  be  changed.   The  mr_type parameter specifies which action to
112       perform.  PACKET_MR_PROMISC enables receiving all packets on  a  shared
113       medium (often known as ``promiscuous mode''), PACKET_MR_MULTICAST binds
114       the  socket  to  the  physical  layer  multicast  group  specified   in
115       mr_address  and  mr_alen,  and PACKET_MR_ALLMULTI sets the socket up to
116       receive all multicast packets arriving at the interface.
117
118       In addition the traditional ioctls SIOCSIFFLAGS, SIOCADDMULTI, SIOCDEL‐
119       MULTI can be used for the same purpose.
120
121
122

IOCTLS

124       SIOCGSTAMP  can  be used to receive the time stamp of the last received
125       packet.  Argument is a struct timeval.
126
127       In addition all standard ioctls defined in netdevice(7)  and  socket(7)
128       are valid on packet sockets.
129
130

ERROR HANDLING

132       Packet  sockets  do  no error handling other than errors occurred while
133       passing the packet to the device driver.  They don't have  the  concept
134       of a pending error.
135
136

COMPATIBILITY

138       In  Linux  2.0,  the  only  way  to  get a packet socket was by calling
139       socket(PF_INET, SOCK_PACKET, protocol).  This is  still  supported  but
140       strongly  deprecated.   The  main difference between the two methods is
141       that SOCK_PACKET uses the old struct sockaddr_pkt to specify an  inter‐
142       face, which doesn't provide physical layer independence.
143
144         struct sockaddr_pkt {
145             unsigned short spkt_family;
146             unsigned char  spkt_device[14];
147             unsigned short spkt_protocol;
148         };
149
150       spkt_family  contains  the device type, spkt_protocol is the IEEE 802.3
151       protocol type as defined in <sys/if_ether.h>  and  spkt_device  is  the
152       device name as a null terminated string, e.g. eth0.
153
154       This structure is obsolete and should not be used in new code.
155
156

NOTES

158       For  portable  programs  it  is suggested to use PF_PACKET via pcap(3);
159       although this only covers a subset of the PF_PACKET features.
160
161       The SOCK_DGRAM packet sockets make no attempt to create  or  parse  the
162       IEEE  802.2  LLC  header  for  a IEEE 802.3 frame.  When ETH_P_802_3 is
163       specified as protocol for sending the kernel creates  the  802.3  frame
164       and  fills  out the length field; the user has to supply the LLC header
165       to get a fully conforming packet.  Incoming 802.3 packets are not  mul‐
166       tiplexed on the DSAP/SSAP protocol fields; instead they are supplied to
167       the user as protocol ETH_P_802_2 with the LLC header prepended.  It  is
168       thus  not  possible to bind to ETH_P_802_3; bind to ETH_P_802_2 instead
169       and do the protocol multiplex yourself.  The default for sending is the
170       standard Ethernet DIX encapsulation with the protocol filled in.
171
172       Packet sockets are not subject to the input or output firewall chains.
173
174

ERRORS

176       ENETDOWN
177              Interface is not up.
178
179
180       ENOTCONN
181              No interface address passed.
182
183
184       ENODEV Unknown  device  name  or interface index specified in interface
185              address.
186
187
188       EMSGSIZE
189              Packet is bigger than interface MTU.
190
191
192       ENOBUFS
193              Not enough memory to allocate the packet.
194
195
196       EFAULT User passed invalid memory address.
197
198
199       EINVAL Invalid argument.
200
201
202       ENXIO  Interface address contained illegal interface index.
203
204
205       EPERM  User has insufficient privileges to carry out this operation.
206
207
208       EADDRNOTAVAIL
209              Unknown multicast group address passed.
210
211
212       ENOENT No packet received.
213
214              In addition other errors  may  be  generated  by  the  low-level
215              driver.
216

VERSIONS

218       PF_PACKET  is  a  new feature in Linux 2.2. Earlier Linux versions sup‐
219       ported only SOCK_PACKET.
220
221

BUGS

223       glibc 2.1 does not have a define for SOL_PACKET.  The  suggested  work‐
224       around is to use
225         #ifndef SOL_PACKET
226         #define SOL_PACKET 263
227         #endif
228       This  is fixed in later glibc versions and also does not occur on libc5
229       systems.
230
231       The IEEE 802.2/803.3 LLC handling could be considered as a bug.
232
233       Socket filters are not documented.
234
235       The MSG_TRUNC recvmsg()  extension  is  an  ugly  hack  and  should  be
236       replaced  by  a  control message.  There is currently no way to get the
237       original destination address of packets via SOCK_DGRAM.
238
239

HISTORICAL NOTE

241       The include file <netpacket/packet.h> is present since glibc2.1.  Older
242       systems need
243
244       #include <asm/types.h>
245       #include <linux/if_packet.h>
246       #include <linux/if_ether.h> /* The L2 protocols */
247

SEE ALSO

249       socket(2), pcap(3), capabilities(7), ip(7), raw(7), socket(7)
250
251       RFC 894 for the standard IP Ethernet encapsulation.
252
253       RFC 1700 for the IEEE 802.3 IP encapsulation.
254
255       The <linux/if_ether.h> include file for physical layer protocols.
256
257
258
259Linux Man Page                    1999-04-29                         PACKET(7)
Impressum