]>
Commit | Line | Data |
---|---|---|
77117f4f | 1 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
2297bf0e | 2 | .\" |
00acdba1 | 3 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
77117f4f MK |
4 | .\" Permission is granted to distribute possibly modified copies |
5 | .\" of this page provided the header is included verbatim, | |
6 | .\" and in case of nontrivial modification author and date | |
7 | .\" of the modification is added to the header. | |
8ff7380d | 8 | .\" %%%LICENSE_END |
6a717e5e | 9 | .\" |
77117f4f | 10 | .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ |
6a717e5e | 11 | .\" |
b8efb414 | 12 | .TH PACKET 7 2016-10-08 "Linux" "Linux Programmer's Manual" |
77117f4f | 13 | .SH NAME |
239bd6e9 | 14 | packet \- packet interface on device level |
77117f4f MK |
15 | .SH SYNOPSIS |
16 | .nf | |
17 | .B #include <sys/socket.h> | |
18 | .br | |
eb67122e | 19 | .B #include <linux/if_packet.h> |
77117f4f MK |
20 | .br |
21 | .B #include <net/ethernet.h> /* the L2 protocols */ | |
22 | .sp | |
d4c8c97c | 23 | .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); |
77117f4f MK |
24 | .fi |
25 | .SH DESCRIPTION | |
26 | Packet sockets are used to receive or send raw packets at the device driver | |
27 | (OSI Layer 2) level. | |
28 | They allow the user to implement protocol modules in user space | |
29 | on top of the physical layer. | |
30 | ||
31 | The | |
32 | .I socket_type | |
33 | is either | |
34 | .B SOCK_RAW | |
c412686c | 35 | for raw packets including the link-level header or |
77117f4f | 36 | .B SOCK_DGRAM |
c412686c MK |
37 | for cooked packets with the link-level header removed. |
38 | The link-level header information is available in a common format in a | |
f2b20532 MK |
39 | .IR sockaddr_ll |
40 | structure. | |
77117f4f | 41 | .I protocol |
084cf3d1 | 42 | is the IEEE 802.3 protocol number in network byte order. |
77117f4f MK |
43 | See the |
44 | .I <linux/if_ether.h> | |
45 | include file for a list of allowed protocols. | |
46 | When protocol | |
47 | is set to | |
f2b20532 | 48 | .BR htons(ETH_P_ALL) , |
77117f4f MK |
49 | then all protocols are received. |
50 | All incoming packets of that protocol type will be passed to the packet | |
51 | socket before they are passed to the protocols implemented in the kernel. | |
52 | ||
f71d1557 | 53 | In order to create a packet socket, a process must have the |
77117f4f | 54 | .B CAP_NET_RAW |
f71d1557 | 55 | capability in the user namespace that governs its network namespace. |
77117f4f MK |
56 | |
57 | .B SOCK_RAW | |
58 | packets are passed to and from the device driver without any changes in | |
59 | the packet data. | |
60 | When receiving a packet, the address is still parsed and | |
61 | passed in a standard | |
62 | .I sockaddr_ll | |
63 | address structure. | |
f2b20532 MK |
64 | When transmitting a packet, the user-supplied buffer |
65 | should contain the physical-layer header. | |
77117f4f MK |
66 | That packet is then |
67 | queued unmodified to the network driver of the interface defined by the | |
68 | destination address. | |
69 | Some device drivers always add other headers. | |
70 | .B SOCK_RAW | |
71 | is similar to but not compatible with the obsolete | |
d4c8c97c | 72 | .B AF_INET/SOCK_PACKET |
77117f4f MK |
73 | of Linux 2.0. |
74 | ||
75 | .B SOCK_DGRAM | |
76 | operates on a slightly higher level. | |
77 | The physical header is removed before the packet is passed to the user. | |
78 | Packets sent through a | |
79 | .B SOCK_DGRAM | |
f2b20532 | 80 | packet socket get a suitable physical-layer header based on the |
77117f4f MK |
81 | information in the |
82 | .I sockaddr_ll | |
83 | destination address before they are queued. | |
84 | ||
0a3d13a5 | 85 | By default, all packets of the specified protocol type |
77117f4f | 86 | are passed to a packet socket. |
33a0ccb2 | 87 | To get packets only from a specific interface use |
77117f4f MK |
88 | .BR bind (2) |
89 | specifying an address in a | |
90 | .I struct sockaddr_ll | |
91 | to bind the packet socket to an interface. | |
4d45036a | 92 | Fields used for binding are |
c139511a MK |
93 | .IR sll_family |
94 | (should be | |
4d45036a | 95 | .BR AF_PACKET ), |
96 | .IR sll_protocol , | |
97 | and | |
98 | .IR sll_ifindex . | |
77117f4f MK |
99 | |
100 | The | |
101 | .BR connect (2) | |
102 | operation is not supported on packet sockets. | |
103 | ||
104 | When the | |
105 | .B MSG_TRUNC | |
106 | flag is passed to | |
107 | .BR recvmsg (2), | |
108 | .BR recv (2), | |
f2b20532 MK |
109 | or |
110 | .BR recvfrom (2), | |
77117f4f MK |
111 | the real length of the packet on the wire is always returned, |
112 | even when it is longer than the buffer. | |
c634028a | 113 | .SS Address types |
dd85e7df DP |
114 | The |
115 | .I sockaddr_ll | |
f2b20532 | 116 | structure is a device-independent physical-layer address. |
77117f4f MK |
117 | |
118 | .in +4n | |
119 | .nf | |
120 | struct sockaddr_ll { | |
121 | unsigned short sll_family; /* Always AF_PACKET */ | |
f2b20532 | 122 | unsigned short sll_protocol; /* Physical-layer protocol */ |
77117f4f | 123 | int sll_ifindex; /* Interface number */ |
ed924588 | 124 | unsigned short sll_hatype; /* ARP hardware type */ |
77117f4f MK |
125 | unsigned char sll_pkttype; /* Packet type */ |
126 | unsigned char sll_halen; /* Length of address */ | |
f2b20532 | 127 | unsigned char sll_addr[8]; /* Physical-layer address */ |
77117f4f MK |
128 | }; |
129 | .fi | |
130 | .in | |
131 | ||
ab8ff64c MK |
132 | The fields of this structure are as follows: |
133 | .IP * 3 | |
77117f4f | 134 | .I sll_protocol |
084cf3d1 | 135 | is the standard ethernet protocol type in network byte order as defined |
77117f4f MK |
136 | in the |
137 | .I <linux/if_ether.h> | |
138 | include file. | |
139 | It defaults to the socket's protocol. | |
ab8ff64c | 140 | .IP * |
77117f4f MK |
141 | .I sll_ifindex |
142 | is the interface index of the interface | |
143 | (see | |
144 | .BR netdevice (7)); | |
145 | 0 matches any interface (only permitted for binding). | |
146 | .I sll_hatype | |
88ea664e | 147 | is an ARP type as defined in the |
77117f4f MK |
148 | .I <linux/if_arp.h> |
149 | include file. | |
ab8ff64c | 150 | .IP * |
77117f4f MK |
151 | .I sll_pkttype |
152 | contains the packet type. | |
153 | Valid types are | |
154 | .B PACKET_HOST | |
155 | for a packet addressed to the local host, | |
156 | .B PACKET_BROADCAST | |
f2b20532 | 157 | for a physical-layer broadcast packet, |
77117f4f | 158 | .B PACKET_MULTICAST |
f2b20532 | 159 | for a packet sent to a physical-layer multicast address, |
77117f4f MK |
160 | .B PACKET_OTHERHOST |
161 | for a packet to some other host that has been caught by a device driver | |
162 | in promiscuous mode, and | |
163 | .B PACKET_OUTGOING | |
f2b20532 | 164 | for a packet originating from the local host that is looped back to a packet |
77117f4f | 165 | socket. |
33a0ccb2 | 166 | These types make sense only for receiving. |
ab8ff64c | 167 | .IP * |
77117f4f MK |
168 | .I sll_addr |
169 | and | |
170 | .I sll_halen | |
f2b20532 | 171 | contain the physical-layer (e.g., IEEE 802.3) address and its length. |
77117f4f | 172 | The exact interpretation depends on the device. |
ab8ff64c | 173 | .PP |
f2b20532 | 174 | When you send packets, it is enough to specify |
77117f4f MK |
175 | .IR sll_family , |
176 | .IR sll_addr , | |
177 | .IR sll_halen , | |
5f343bf2 GS |
178 | .IR sll_ifindex , |
179 | and | |
180 | .IR sll_protocol . | |
77117f4f MK |
181 | The other fields should be 0. |
182 | .I sll_hatype | |
183 | and | |
184 | .I sll_pkttype | |
185 | are set on received packets for your information. | |
c634028a | 186 | .SS Socket options |
dbb4f751 WB |
187 | Packet socket options are configured by calling |
188 | .BR setsockopt (2) | |
189 | with level | |
190 | .BR SOL_PACKET . | |
191 | .TP | |
192 | .BR PACKET_ADD_MEMBERSHIP | |
193 | .PD 0 | |
194 | .TP | |
195 | .BR PACKET_DROP_MEMBERSHIP | |
196 | .PD | |
f2b20532 | 197 | Packet sockets can be used to configure physical-layer multicasting |
77117f4f | 198 | and promiscuous mode. |
77117f4f | 199 | .B PACKET_ADD_MEMBERSHIP |
dbb4f751 | 200 | adds a binding and |
77117f4f | 201 | .B PACKET_DROP_MEMBERSHIP |
dbb4f751 | 202 | drops it. |
77117f4f | 203 | They both expect a |
c412686c | 204 | .I packet_mreq |
77117f4f MK |
205 | structure as argument: |
206 | ||
207 | .in +4n | |
208 | .nf | |
209 | struct packet_mreq { | |
210 | int mr_ifindex; /* interface index */ | |
211 | unsigned short mr_type; /* action */ | |
212 | unsigned short mr_alen; /* address length */ | |
f2b20532 | 213 | unsigned char mr_address[8]; /* physical-layer address */ |
77117f4f MK |
214 | }; |
215 | .fi | |
216 | .in | |
217 | ||
f2b20532 | 218 | .I mr_ifindex |
77117f4f MK |
219 | contains the interface index for the interface whose status |
220 | should be changed. | |
221 | The | |
f2b20532 MK |
222 | .I mr_type |
223 | field specifies which action to perform. | |
77117f4f MK |
224 | .B PACKET_MR_PROMISC |
225 | enables receiving all packets on a shared medium (often known as | |
226 | "promiscuous mode"), | |
227 | .B PACKET_MR_MULTICAST | |
f2b20532 MK |
228 | binds the socket to the physical-layer multicast group specified in |
229 | .I mr_address | |
77117f4f | 230 | and |
f2b20532 | 231 | .IR mr_alen , |
77117f4f MK |
232 | and |
233 | .B PACKET_MR_ALLMULTI | |
234 | sets the socket up to receive all multicast packets arriving at | |
235 | the interface. | |
236 | ||
f577d7ef | 237 | In addition, the traditional ioctls |
77117f4f MK |
238 | .BR SIOCSIFFLAGS , |
239 | .BR SIOCADDMULTI , | |
240 | .B SIOCDELMULTI | |
241 | can be used for the same purpose. | |
dbb4f751 WB |
242 | .TP |
243 | .BR PACKET_AUXDATA " (since Linux 2.6.21)" | |
244 | .\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc | |
245 | If this binary option is enabled, the packet socket passes a metadata | |
246 | structure along with each packet in the | |
247 | .BR recvmsg (2) | |
248 | control field. | |
249 | The structure can be read with | |
250 | .BR cmsg (3). | |
251 | It is defined as | |
252 | ||
253 | .in +4n | |
254 | .nf | |
255 | struct tpacket_auxdata { | |
256 | __u32 tp_status; | |
257 | __u32 tp_len; /* packet length */ | |
258 | __u32 tp_snaplen; /* captured length */ | |
259 | __u16 tp_mac; | |
260 | __u16 tp_net; | |
261 | __u16 tp_vlan_tci; | |
262 | __u16 tp_padding; | |
263 | }; | |
264 | .fi | |
265 | .in | |
266 | .TP | |
267 | .BR PACKET_FANOUT " (since Linux 3.1)" | |
268 | .\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc | |
269 | To scale processing across threads, packet sockets can form a fanout | |
270 | group. | |
271 | In this mode, each matching packet is enqueued onto only one | |
272 | socket in the group. | |
273 | A socket joins a fanout group by calling | |
274 | .BR setsockopt (2) | |
275 | with level | |
276 | .B SOL_PACKET | |
277 | and option | |
278 | .BR PACKET_FANOUT . | |
279 | Each network namespace can have up to 65536 independent groups. | |
280 | A socket selects a group by encoding the ID in the first 16 bits of | |
281 | the integer option value. | |
282 | The first packet socket to join a group implicitly creates it. | |
283 | To successfully join an existing group, subsequent packet sockets | |
c412686c | 284 | must have the same protocol, device settings, fanout mode and |
dbb4f751 WB |
285 | flags (see below). |
286 | Packet sockets can leave a fanout group only by closing the socket. | |
287 | The group is deleted when the last socket is closed. | |
288 | ||
2205c292 MK |
289 | Fanout supports multiple algorithms to spread traffic between sockets, |
290 | as follows: | |
291 | .RS | |
292 | .IP * 3 | |
dbb4f751 WB |
293 | The default mode, |
294 | .BR PACKET_FANOUT_HASH , | |
295 | sends packets from the same flow to the same socket to maintain | |
296 | per-flow ordering. | |
297 | For each packet, it chooses a socket by taking the packet flow hash | |
298 | modulo the number of sockets in the group, where a flow hash is a hash | |
c412686c | 299 | over network-layer address and optional transport-layer port fields. |
2205c292 | 300 | .IP * |
c412686c | 301 | The load-balance mode |
dbb4f751 WB |
302 | .BR PACKET_FANOUT_LB |
303 | implements a round-robin algorithm. | |
2205c292 | 304 | .IP * |
dbb4f751 WB |
305 | .BR PACKET_FANOUT_CPU |
306 | selects the socket based on the CPU that the packet arrived on. | |
2205c292 | 307 | .IP * |
dbb4f751 | 308 | .BR PACKET_FANOUT_ROLLOVER |
f2b20532 | 309 | processes all data on a single socket, moving to the next when one |
dbb4f751 | 310 | becomes backlogged. |
2205c292 | 311 | .IP * |
dbb4f751 | 312 | .BR PACKET_FANOUT_RND |
c412686c | 313 | selects the socket using a pseudo-random number generator. |
2205c292 | 314 | .IP * |
6a06d7e4 | 315 | .BR PACKET_FANOUT_QM |
bab78b9c MK |
316 | .\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd |
317 | (available since Linux 3.14) | |
6a06d7e4 | 318 | selects the socket using the recorded queue_mapping of the received skb. |
2205c292 MK |
319 | .RE |
320 | .IP | |
dbb4f751 WB |
321 | Fanout modes can take additional options. |
322 | IP fragmentation causes packets from the same flow to have different | |
323 | flow hashes. | |
324 | The flag | |
325 | .BR PACKET_FANOUT_FLAG_DEFRAG , | |
f2b20532 | 326 | if set, causes packets to be defragmented before fanout is applied, to |
dbb4f751 WB |
327 | preserve order even in this case. |
328 | Fanout mode and options are communicated in the second 16 bits of the | |
329 | integer option value. | |
330 | The flag | |
331 | .BR PACKET_FANOUT_FLAG_ROLLOVER | |
332 | enables the roll over mechanism as a backup strategy: if the | |
333 | original fanout algorithm selects a backlogged socket, the packet | |
334 | rolls over to the next available one. | |
335 | .TP | |
c412686c | 336 | .BR PACKET_LOSS " (with " PACKET_TX_RING ) |
17e5494f MK |
337 | When a malformed packet is encountered on a transmit ring, |
338 | the default is to reset its | |
43f5be18 CA |
339 | .I tp_status |
340 | to | |
8c26e99b | 341 | .BR TP_STATUS_WRONG_FORMAT |
43f5be18 | 342 | and abort the transmission immediately. |
17e5494f | 343 | The malformed packet blocks itself and subsequently enqueued packets from |
43f5be18 CA |
344 | being sent. |
345 | The format error must be fixed, the associated | |
346 | .I tp_status | |
347 | reset to | |
17e5494f | 348 | .BR TP_STATUS_SEND_REQUEST , |
43f5be18 | 349 | and the transmission process restarted via |
17e5494f | 350 | .BR send (2). |
896333c5 | 351 | However, if |
8c26e99b | 352 | .BR PACKET_LOSS |
43f5be18 CA |
353 | is set, any malformed packet will be skipped, its |
354 | .I tp_status | |
355 | reset to | |
896333c5 | 356 | .BR TP_STATUS_AVAILABLE , |
8c26e99b | 357 | and the transmission process continued. |
dbb4f751 | 358 | .TP |
c412686c | 359 | .BR PACKET_RESERVE " (with " PACKET_RX_RING ) |
dbb4f751 WB |
360 | By default, a packet receive ring writes packets immediately following the |
361 | metadata structure and alignment padding. | |
362 | This integer option reserves additional headroom. | |
363 | .TP | |
364 | .BR PACKET_RX_RING | |
9a141bfb | 365 | Create a memory-mapped ring buffer for asynchronous packet reception. |
dbb4f751 WB |
366 | The packet socket reserves a contiguous region of application address |
367 | space, lays it out into an array of packet slots and copies packets | |
368 | (up to | |
ffd04565 DP |
369 | .IR tp_snaplen ) |
370 | into subsequent slots. | |
dbb4f751 WB |
371 | Each packet is preceded by a metadata structure similar to |
372 | .IR tpacket_auxdata . | |
373 | The protocol fields encode the offset to the data | |
374 | from the start of the metadata header. | |
375 | .I tp_net | |
376 | stores the offset to the network layer. | |
377 | If the packet socket is of type | |
378 | .BR SOCK_DGRAM , | |
379 | then | |
380 | .I tp_mac | |
381 | is the same. | |
382 | If it is of type | |
383 | .BR SOCK_RAW , | |
c412686c | 384 | then that field stores the offset to the link-layer frame. |
dbb4f751 WB |
385 | Packet socket and application communicate the head and tail of the ring |
386 | through the | |
387 | .I tp_status | |
388 | field. | |
43f5be18 CA |
389 | The packet socket owns all slots with |
390 | .I tp_status | |
391 | equal to | |
dbb4f751 WB |
392 | .BR TP_STATUS_KERNEL . |
393 | After filling a slot, it changes the status of the slot to transfer | |
394 | ownership to the application. | |
43f5be18 CA |
395 | During normal operation, the new |
396 | .I tp_status | |
397 | value has at least the | |
a29edaee SP |
398 | .BR TP_STATUS_USER |
399 | bit set to signal that a received packet has been stored. | |
dbb4f751 | 400 | When the application has finished processing a packet, it transfers |
43f5be18 CA |
401 | ownership of the slot back to the socket by setting |
402 | .I tp_status | |
403 | equal to | |
dbb4f751 | 404 | .BR TP_STATUS_KERNEL . |
f2b20532 | 405 | |
dbb4f751 WB |
406 | Packet sockets implement multiple variants of the packet ring. |
407 | The implementation details are described in | |
408 | .IR Documentation/networking/packet_mmap.txt | |
409 | in the Linux kernel source tree. | |
410 | .TP | |
411 | .BR PACKET_STATISTICS | |
412 | Retrieve packet socket statistics in the form of a structure | |
413 | ||
414 | .in +4n | |
415 | .nf | |
416 | struct tpacket_stats { | |
c412686c MK |
417 | unsigned int tp_packets; /* Total packet count */ |
418 | unsigned int tp_drops; /* Dropped packet count */ | |
dbb4f751 WB |
419 | }; |
420 | .fi | |
421 | .in | |
422 | ||
423 | Receiving statistics resets the internal counters. | |
424 | The statistics structure differs when using a ring of variant | |
425 | .BR TPACKET_V3 . | |
426 | .TP | |
342639d9 | 427 | .BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)" |
dbb4f751 WB |
428 | .\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649 |
429 | The packet receive ring always stores a timestamp in the metadata header. | |
430 | By default, this is a software generated timestamp generated when the | |
431 | packet is copied into the ring. | |
432 | This integer option selects the type of timestamp. | |
433 | Besides the default, it support the two hardware formats described in | |
434 | .IR Documentation/networking/timestamping.txt | |
435 | in the Linux kernel source tree. | |
436 | .TP | |
437 | .BR PACKET_TX_RING " (since Linux 2.6.31)" | |
438 | .\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1 | |
9a141bfb | 439 | Create a memory-mapped ring buffer for packet transmission. |
dbb4f751 WB |
440 | This option is similar to |
441 | .BR PACKET_RX_RING | |
442 | and takes the same arguments. | |
43f5be18 CA |
443 | The application writes packets into slots with |
444 | .I tp_status | |
445 | equal to | |
dbb4f751 | 446 | .BR TP_STATUS_AVAILABLE |
43f5be18 CA |
447 | and schedules them for transmission by changing |
448 | .I tp_status | |
449 | to | |
dbb4f751 WB |
450 | .BR TP_STATUS_SEND_REQUEST . |
451 | When packets are ready to be transmitted, the application calls | |
452 | .BR send (2) | |
453 | or a variant thereof. | |
454 | The | |
455 | .I buf | |
456 | and | |
457 | .I len | |
458 | fields of this call are ignored. | |
459 | If an address is passed using | |
460 | .BR sendto (2) | |
461 | or | |
ffd04565 | 462 | .BR sendmsg (2), |
dbb4f751 | 463 | then that overrides the socket default. |
43f5be18 CA |
464 | On successful transmission, the socket resets |
465 | .I tp_status | |
466 | to | |
dbb4f751 | 467 | .BR TP_STATUS_AVAILABLE . |
8c26e99b | 468 | It immediately aborts the transmission on error unless |
dbb4f751 WB |
469 | .BR PACKET_LOSS |
470 | is set. | |
471 | .TP | |
342639d9 | 472 | .BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)" |
dbb4f751 WB |
473 | .\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279 |
474 | By default, | |
475 | .BR PACKET_RX_RING | |
476 | creates a packet receive ring of variant | |
477 | .BR TPACKET_V1 . | |
478 | To create another variant, configure the desired variant by setting this | |
479 | integer option before creating the ring. | |
602ce088 DB |
480 | .TP |
481 | .BR PACKET_QDISC_BYPASS " (since Linux 3.14)" | |
992787fe | 482 | .\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1 |
602ce088 | 483 | By default, packets sent through packet sockets pass through the kernel's |
2203837f DB |
484 | qdisc (traffic control) layer, which is fine for the vast majority of use |
485 | cases. | |
a4edbc60 MK |
486 | For traffic generator appliances using packet sockets |
487 | that intend to brute-force flood the network\(emfor example, | |
488 | to test devices under load in a similar | |
489 | fashion to pktgen\(emthis layer can be bypassed by setting | |
490 | this integer option to 1. | |
31718129 | 491 | A side effect is that packet buffering in the qdisc layer is avoided, |
a4edbc60 MK |
492 | which will lead to increased drops when network |
493 | device transmit queues are busy; | |
2203837f | 494 | therefore, use at your own risk. |
77117f4f MK |
495 | .SS Ioctls |
496 | .B SIOCGSTAMP | |
497 | can be used to receive the timestamp of the last received packet. | |
498 | Argument is a | |
dbb4f751 WB |
499 | .I struct timeval |
500 | variable. | |
00c84453 | 501 | .\" FIXME Document SIOCGSTAMPNS |
77117f4f | 502 | |
f577d7ef | 503 | In addition, all standard ioctls defined in |
77117f4f MK |
504 | .BR netdevice (7) |
505 | and | |
506 | .BR socket (7) | |
507 | are valid on packet sockets. | |
c634028a | 508 | .SS Error handling |
77117f4f MK |
509 | Packet sockets do no error handling other than errors occurred |
510 | while passing the packet to the device driver. | |
511 | They don't have the concept of a pending error. | |
512 | .SH ERRORS | |
513 | .TP | |
514 | .B EADDRNOTAVAIL | |
515 | Unknown multicast group address passed. | |
516 | .TP | |
517 | .B EFAULT | |
518 | User passed invalid memory address. | |
519 | .TP | |
520 | .B EINVAL | |
521 | Invalid argument. | |
522 | .TP | |
523 | .B EMSGSIZE | |
524 | Packet is bigger than interface MTU. | |
525 | .TP | |
526 | .B ENETDOWN | |
527 | Interface is not up. | |
528 | .TP | |
529 | .B ENOBUFS | |
530 | Not enough memory to allocate the packet. | |
531 | .TP | |
532 | .B ENODEV | |
533 | Unknown device name or interface index specified in interface address. | |
534 | .TP | |
535 | .B ENOENT | |
536 | No packet received. | |
537 | .TP | |
538 | .B ENOTCONN | |
539 | No interface address passed. | |
540 | .TP | |
541 | .B ENXIO | |
542 | Interface address contained an invalid interface index. | |
543 | .TP | |
544 | .B EPERM | |
545 | User has insufficient privileges to carry out this operation. | |
f2b20532 | 546 | .PP |
f577d7ef | 547 | In addition, other errors may be generated by the low-level driver. |
77117f4f | 548 | .SH VERSIONS |
d4c8c97c | 549 | .B AF_PACKET |
77117f4f MK |
550 | is a new feature in Linux 2.2. |
551 | Earlier Linux versions supported only | |
552 | .BR SOCK_PACKET . | |
553 | .PP | |
77117f4f MK |
554 | .SH NOTES |
555 | For portable programs it is suggested to use | |
d4c8c97c | 556 | .B AF_PACKET |
77117f4f MK |
557 | via |
558 | .BR pcap (3); | |
33a0ccb2 | 559 | although this covers only a subset of the |
d4c8c97c | 560 | .B AF_PACKET |
77117f4f MK |
561 | features. |
562 | ||
563 | The | |
564 | .B SOCK_DGRAM | |
565 | packet sockets make no attempt to create or parse the IEEE 802.2 LLC | |
566 | header for a IEEE 802.3 frame. | |
567 | When | |
568 | .B ETH_P_802_3 | |
569 | is specified as protocol for sending the kernel creates the | |
570 | 802.3 frame and fills out the length field; the user has to supply the LLC | |
571 | header to get a fully conforming packet. | |
572 | Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol | |
573 | fields; instead they are supplied to the user as protocol | |
574 | .B ETH_P_802_2 | |
dbb4f751 | 575 | with the LLC header prefixed. |
77117f4f MK |
576 | It is thus not possible to bind to |
577 | .BR ETH_P_802_3 ; | |
578 | bind to | |
579 | .B ETH_P_802_2 | |
580 | instead and do the protocol multiplex yourself. | |
581 | The default for sending is the standard Ethernet DIX | |
582 | encapsulation with the protocol filled in. | |
583 | ||
584 | Packet sockets are not subject to the input or output firewall chains. | |
585 | .SS Compatibility | |
f2b20532 MK |
586 | In Linux 2.0, the only way to get a packet socket was with the call: |
587 | ||
588 | socket(AF_INET, SOCK_PACKET, protocol) | |
589 | ||
590 | This is still supported, but deprecated and strongly discouraged. | |
77117f4f MK |
591 | The main difference between the two methods is that |
592 | .B SOCK_PACKET | |
593 | uses the old | |
594 | .I struct sockaddr_pkt | |
f2b20532 | 595 | to specify an interface, which doesn't provide physical-layer |
77117f4f MK |
596 | independence. |
597 | ||
598 | .in +4n | |
599 | .nf | |
600 | struct sockaddr_pkt { | |
601 | unsigned short spkt_family; | |
602 | unsigned char spkt_device[14]; | |
603 | unsigned short spkt_protocol; | |
604 | }; | |
605 | .fi | |
606 | .in | |
607 | ||
608 | .I spkt_family | |
609 | contains | |
610 | the device type, | |
611 | .I spkt_protocol | |
612 | is the IEEE 802.3 protocol type as defined in | |
613 | .I <sys/if_ether.h> | |
614 | and | |
615 | .I spkt_device | |
d0cb7cc6 | 616 | is the device name as a null-terminated string, for example, eth0. |
77117f4f MK |
617 | |
618 | This structure is obsolete and should not be used in new code. | |
619 | .SH BUGS | |
77117f4f MK |
620 | The IEEE 802.2/803.3 LLC handling could be considered as a bug. |
621 | ||
622 | Socket filters are not documented. | |
623 | ||
624 | The | |
625 | .B MSG_TRUNC | |
626 | .BR recvmsg (2) | |
627 | extension is an ugly hack and should be replaced by a control message. | |
628 | There is currently no way to get the original destination address of | |
629 | packets via | |
630 | .BR SOCK_DGRAM . | |
631 | .\" .SH CREDITS | |
632 | .\" This man page was written by Andi Kleen with help from Matthew Wilcox. | |
d4c8c97c | 633 | .\" AF_PACKET in Linux 2.2 was implemented |
77117f4f | 634 | .\" by Alexey Kuznetsov, based on code by Alan Cox and others. |
47297adb | 635 | .SH SEE ALSO |
77117f4f MK |
636 | .BR socket (2), |
637 | .BR pcap (3), | |
638 | .BR capabilities (7), | |
639 | .BR ip (7), | |
640 | .BR raw (7), | |
641 | .BR socket (7) | |
642 | ||
643 | RFC\ 894 for the standard IP Ethernet encapsulation. | |
77117f4f MK |
644 | RFC\ 1700 for the IEEE 802.3 IP encapsulation. |
645 | ||
646 | The | |
647 | .I <linux/if_ether.h> | |
f2b20532 | 648 | include file for physical-layer protocols. |
ab80da6e | 649 | |
43f5be18 CA |
650 | The Linux kernel source tree. |
651 | .IR /Documentation/networking/filter.txt | |
652 | describes how to apply Berkeley Packet Filters to packet sockets. | |
ab80da6e | 653 | .IR /tools/testing/selftests/net/psock_tpacket.c |
43f5be18 CA |
654 | contains example source code for all available versions of |
655 | .BR PACKET_RX_RING | |
656 | and | |
657 | .BR PACKET_TX_RING . |