1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
2 .\" Permission is granted to distribute possibly modified copies
3 .\" of this page provided the header is included verbatim,
4 .\" and in case of nontrivial modification author and date
5 .\" of the modification is added to the header.
6 .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $
7 .TH PACKET 7 2008-08-08 "Linux" "Linux Programmer's Manual"
9 packet, AF_PACKET \- packet interface on device level.
12 .B #include <sys/socket.h>
14 .B #include <netpacket/packet.h>
16 .B #include <net/ethernet.h> /* the L2 protocols */
18 .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol );
21 Packet sockets are used to receive or send raw packets at the device driver
23 They allow the user to implement protocol modules in user space
24 on top of the physical layer.
30 for raw packets including the link level header or
32 for cooked packets with the link level header removed.
34 header information is available in a common format in a
37 is the IEEE 802.3 protocol number in network order.
40 include file for a list of allowed protocols.
44 then all protocols are received.
45 All incoming packets of that protocol type will be passed to the packet
46 socket before they are passed to the protocols implemented in the kernel.
48 Only processes with effective UID 0 or the
50 capability may open packet sockets.
53 packets are passed to and from the device driver without any changes in
55 When receiving a packet, the address is still parsed and
59 When transmitting a packet, the user supplied buffer
60 should contain the physical layer header.
62 queued unmodified to the network driver of the interface defined by the
64 Some device drivers always add other headers.
66 is similar to but not compatible with the obsolete
67 .B AF_INET/SOCK_PACKET
71 operates on a slightly higher level.
72 The physical header is removed before the packet is passed to the user.
73 Packets sent through a
75 packet socket get a suitable physical layer header based on the
78 destination address before they are queued.
80 By default all packets of the specified protocol type
81 are passed to a packet socket.
82 To only get packets from a specific interface use
84 specifying an address in a
86 to bind the packet socket to an interface.
91 address fields are used for purposes of binding.
95 operation is not supported on packet sockets.
103 the real length of the packet on the wire is always returned,
104 even when it is longer than the buffer.
106 The sockaddr_ll is a device independent physical layer address.
111 unsigned short sll_family; /* Always AF_PACKET */
112 unsigned short sll_protocol; /* Physical layer protocol */
113 int sll_ifindex; /* Interface number */
114 unsigned short sll_hatype; /* Header type */
115 unsigned char sll_pkttype; /* Packet type */
116 unsigned char sll_halen; /* Length of address */
117 unsigned char sll_addr[8]; /* Physical layer address */
123 is the standard ethernet protocol type in network order as defined
125 .I <linux/if_ether.h>
127 It defaults to the socket's protocol.
129 is the interface index of the interface
132 0 matches any interface (only permitted for binding).
134 is a ARP type as defined in the
138 contains the packet type.
141 for a packet addressed to the local host,
143 for a physical layer broadcast packet,
145 for a packet sent to a physical layer multicast address,
147 for a packet to some other host that has been caught by a device driver
148 in promiscuous mode, and
150 for a packet originated from the local host that is looped back to a packet
152 These types make only sense for receiving.
156 contain the physical layer (e.g., IEEE 802.3) address and its length.
157 The exact interpretation depends on the device.
159 When you send packets it is enough to specify
164 The other fields should be 0.
168 are set on received packets for your information.
175 Packet sockets can be used to configure physical layer multicasting
176 and promiscuous mode.
179 on a packet socket for
181 and one of the options
182 .B PACKET_ADD_MEMBERSHIP
184 .B PACKET_DROP_MEMBERSHIP
188 structure as argument:
193 int mr_ifindex; /* interface index */
194 unsigned short mr_type; /* action */
195 unsigned short mr_alen; /* address length */
196 unsigned char mr_address[8]; /* physical layer address */
202 contains the interface index for the interface whose status
206 parameter specifies which action to perform.
208 enables receiving all packets on a shared medium (often known as
210 .B PACKET_MR_MULTICAST
211 binds the socket to the physical layer multicast group specified in
216 .B PACKET_MR_ALLMULTI
217 sets the socket up to receive all multicast packets arriving at
220 In addition the traditional ioctls
224 can be used for the same purpose.
227 can be used to receive the timestamp of the last received packet.
230 .\" FIXME Document SIOCGSTAMPNS
232 In addition all standard ioctls defined in
236 are valid on packet sockets.
238 Packet sockets do no error handling other than errors occurred
239 while passing the packet to the device driver.
240 They don't have the concept of a pending error.
244 Unknown multicast group address passed.
247 User passed invalid memory address.
253 Packet is bigger than interface MTU.
259 Not enough memory to allocate the packet.
262 Unknown device name or interface index specified in interface address.
268 No interface address passed.
271 Interface address contained an invalid interface index.
274 User has insufficient privileges to carry out this operation.
276 In addition other errors may be generated by the low-level driver.
279 is a new feature in Linux 2.2.
280 Earlier Linux versions supported only
284 .I <netpacket/packet.h>
285 is present since glibc 2.1.
290 #include <asm/types.h>
291 #include <linux/if_packet.h>
292 #include <linux/if_ether.h> /* The L2 protocols */
296 For portable programs it is suggested to use
300 although this only covers a subset of the
306 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
307 header for a IEEE 802.3 frame.
310 is specified as protocol for sending the kernel creates the
311 802.3 frame and fills out the length field; the user has to supply the LLC
312 header to get a fully conforming packet.
313 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
314 fields; instead they are supplied to the user as protocol
316 with the LLC header prepended.
317 It is thus not possible to bind to
321 instead and do the protocol multiplex yourself.
322 The default for sending is the standard Ethernet DIX
323 encapsulation with the protocol filled in.
325 Packet sockets are not subject to the input or output firewall chains.
327 In Linux 2.0, the only way to get a packet socket was by calling
328 .BI "socket(AF_INET, SOCK_PACKET, " protocol )\fR.
329 This is still supported but strongly deprecated.
330 The main difference between the two methods is that
333 .I struct sockaddr_pkt
334 to specify an interface, which doesn't provide physical layer
339 struct sockaddr_pkt {
340 unsigned short spkt_family;
341 unsigned char spkt_device[14];
342 unsigned short spkt_protocol;
351 is the IEEE 802.3 protocol type as defined in
355 is the device name as a null-terminated string, for example, eth0.
357 This structure is obsolete and should not be used in new code.
359 glibc 2.1 does not have a define for
361 The suggested workaround is to use:
366 #define SOL_PACKET 263
371 This is fixed in later glibc versions and also does not occur on
374 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
376 Socket filters are not documented.
381 extension is an ugly hack and should be replaced by a control message.
382 There is currently no way to get the original destination address of
386 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
387 .\" AF_PACKET in Linux 2.2 was implemented
388 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
392 .BR capabilities (7),
397 RFC\ 894 for the standard IP Ethernet encapsulation.
399 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
402 .I <linux/if_ether.h>
403 include file for physical layer protocols.