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.
231 In addition all standard ioctls defined in
235 are valid on packet sockets.
237 Packet sockets do no error handling other than errors occurred
238 while passing the packet to the device driver.
239 They don't have the concept of a pending error.
243 Unknown multicast group address passed.
246 User passed invalid memory address.
252 Packet is bigger than interface MTU.
258 Not enough memory to allocate the packet.
261 Unknown device name or interface index specified in interface address.
267 No interface address passed.
270 Interface address contained an invalid interface index.
273 User has insufficient privileges to carry out this operation.
275 In addition other errors may be generated by the low-level driver.
278 is a new feature in Linux 2.2.
279 Earlier Linux versions supported only
283 .I <netpacket/packet.h>
284 is present since glibc 2.1.
289 #include <asm/types.h>
290 #include <linux/if_packet.h>
291 #include <linux/if_ether.h> /* The L2 protocols */
295 For portable programs it is suggested to use
299 although this only covers a subset of the
305 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
306 header for a IEEE 802.3 frame.
309 is specified as protocol for sending the kernel creates the
310 802.3 frame and fills out the length field; the user has to supply the LLC
311 header to get a fully conforming packet.
312 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
313 fields; instead they are supplied to the user as protocol
315 with the LLC header prepended.
316 It is thus not possible to bind to
320 instead and do the protocol multiplex yourself.
321 The default for sending is the standard Ethernet DIX
322 encapsulation with the protocol filled in.
324 Packet sockets are not subject to the input or output firewall chains.
326 In Linux 2.0, the only way to get a packet socket was by calling
327 .BI "socket(AF_INET, SOCK_PACKET, " protocol )\fR.
328 This is still supported but strongly deprecated.
329 The main difference between the two methods is that
332 .I struct sockaddr_pkt
333 to specify an interface, which doesn't provide physical layer
338 struct sockaddr_pkt {
339 unsigned short spkt_family;
340 unsigned char spkt_device[14];
341 unsigned short spkt_protocol;
350 is the IEEE 802.3 protocol type as defined in
354 is the device name as a null-terminated string, for example, eth0.
356 This structure is obsolete and should not be used in new code.
358 glibc 2.1 does not have a define for
360 The suggested workaround is to use:
365 #define SOL_PACKET 263
370 This is fixed in later glibc versions and also does not occur on
373 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
375 Socket filters are not documented.
380 extension is an ugly hack and should be replaced by a control message.
381 There is currently no way to get the original destination address of
385 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
386 .\" AF_PACKET in Linux 2.2 was implemented
387 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
391 .BR capabilities (7),
396 RFC\ 894 for the standard IP Ethernet encapsulation.
398 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
401 .I <linux/if_ether.h>
402 include file for physical layer protocols.