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