]>
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 | .\" |
eae2dfce | 12 | .TH PACKET 7 2012-05-10 "Linux" "Linux Programmer's Manual" |
77117f4f | 13 | .SH NAME |
61310e03 | 14 | packet \- packet interface on device level. |
77117f4f MK |
15 | .SH SYNOPSIS |
16 | .nf | |
17 | .B #include <sys/socket.h> | |
18 | .br | |
19 | .B #include <netpacket/packet.h> | |
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 | |
35 | for raw packets including the link level header or | |
36 | .B SOCK_DGRAM | |
37 | for cooked packets with the link level header removed. | |
38 | The link level | |
39 | header information is available in a common format in a | |
40 | .IR sockaddr_ll . | |
41 | .I protocol | |
42 | is the IEEE 802.3 protocol number in network order. | |
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 | |
48 | .B htons(ETH_P_ALL) | |
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 | ||
53 | Only processes with effective UID 0 or the | |
54 | .B CAP_NET_RAW | |
55 | capability may open packet sockets. | |
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. | |
64 | When transmitting a packet, the user supplied buffer | |
65 | should contain the physical layer header. | |
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 | |
80 | packet socket get a suitable physical layer header based on the | |
81 | information in the | |
82 | .I sockaddr_ll | |
83 | destination address before they are queued. | |
84 | ||
85 | By default all packets of the specified protocol type | |
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. | |
92 | Only the | |
93 | .I sll_protocol | |
94 | and the | |
95 | .I sll_ifindex | |
96 | address fields are used for purposes of binding. | |
97 | ||
98 | The | |
99 | .BR connect (2) | |
100 | operation is not supported on packet sockets. | |
101 | ||
102 | When the | |
103 | .B MSG_TRUNC | |
104 | flag is passed to | |
105 | .BR recvmsg (2), | |
106 | .BR recv (2), | |
107 | .BR recvfrom (2) | |
108 | the real length of the packet on the wire is always returned, | |
109 | even when it is longer than the buffer. | |
c634028a | 110 | .SS Address types |
77117f4f MK |
111 | The sockaddr_ll is a device independent physical layer address. |
112 | ||
113 | .in +4n | |
114 | .nf | |
115 | struct sockaddr_ll { | |
116 | unsigned short sll_family; /* Always AF_PACKET */ | |
117 | unsigned short sll_protocol; /* Physical layer protocol */ | |
118 | int sll_ifindex; /* Interface number */ | |
ed924588 | 119 | unsigned short sll_hatype; /* ARP hardware type */ |
77117f4f MK |
120 | unsigned char sll_pkttype; /* Packet type */ |
121 | unsigned char sll_halen; /* Length of address */ | |
122 | unsigned char sll_addr[8]; /* Physical layer address */ | |
123 | }; | |
124 | .fi | |
125 | .in | |
126 | ||
127 | .I sll_protocol | |
128 | is the standard ethernet protocol type in network order as defined | |
129 | in the | |
130 | .I <linux/if_ether.h> | |
131 | include file. | |
132 | It defaults to the socket's protocol. | |
133 | .I sll_ifindex | |
134 | is the interface index of the interface | |
135 | (see | |
136 | .BR netdevice (7)); | |
137 | 0 matches any interface (only permitted for binding). | |
138 | .I sll_hatype | |
88ea664e | 139 | is an ARP type as defined in the |
77117f4f MK |
140 | .I <linux/if_arp.h> |
141 | include file. | |
142 | .I sll_pkttype | |
143 | contains the packet type. | |
144 | Valid types are | |
145 | .B PACKET_HOST | |
146 | for a packet addressed to the local host, | |
147 | .B PACKET_BROADCAST | |
148 | for a physical layer broadcast packet, | |
149 | .B PACKET_MULTICAST | |
150 | for a packet sent to a physical layer multicast address, | |
151 | .B PACKET_OTHERHOST | |
152 | for a packet to some other host that has been caught by a device driver | |
153 | in promiscuous mode, and | |
154 | .B PACKET_OUTGOING | |
155 | for a packet originated from the local host that is looped back to a packet | |
156 | socket. | |
33a0ccb2 | 157 | These types make sense only for receiving. |
77117f4f MK |
158 | .I sll_addr |
159 | and | |
160 | .I sll_halen | |
161 | contain the physical layer (e.g., IEEE 802.3) address and its length. | |
162 | The exact interpretation depends on the device. | |
163 | ||
164 | When you send packets it is enough to specify | |
165 | .IR sll_family , | |
166 | .IR sll_addr , | |
167 | .IR sll_halen , | |
168 | .IR sll_ifindex . | |
169 | The other fields should be 0. | |
170 | .I sll_hatype | |
171 | and | |
172 | .I sll_pkttype | |
173 | are set on received packets for your information. | |
174 | For bind only | |
175 | .I sll_protocol | |
176 | and | |
177 | .I sll_ifindex | |
178 | are used. | |
c634028a | 179 | .SS Socket options |
77117f4f MK |
180 | Packet sockets can be used to configure physical layer multicasting |
181 | and promiscuous mode. | |
182 | It works by calling | |
183 | .BR setsockopt (2) | |
184 | on a packet socket for | |
185 | .B SOL_PACKET | |
186 | and one of the options | |
187 | .B PACKET_ADD_MEMBERSHIP | |
188 | to add a binding or | |
189 | .B PACKET_DROP_MEMBERSHIP | |
190 | to drop it. | |
191 | They both expect a | |
192 | .B packet_mreq | |
193 | structure as argument: | |
194 | ||
195 | .in +4n | |
196 | .nf | |
197 | struct packet_mreq { | |
198 | int mr_ifindex; /* interface index */ | |
199 | unsigned short mr_type; /* action */ | |
200 | unsigned short mr_alen; /* address length */ | |
201 | unsigned char mr_address[8]; /* physical layer address */ | |
202 | }; | |
203 | .fi | |
204 | .in | |
205 | ||
206 | .B mr_ifindex | |
207 | contains the interface index for the interface whose status | |
208 | should be changed. | |
209 | The | |
210 | .B mr_type | |
211 | parameter specifies which action to perform. | |
212 | .B PACKET_MR_PROMISC | |
213 | enables receiving all packets on a shared medium (often known as | |
214 | "promiscuous mode"), | |
215 | .B PACKET_MR_MULTICAST | |
216 | binds the socket to the physical layer multicast group specified in | |
217 | .B mr_address | |
218 | and | |
219 | .BR mr_alen , | |
220 | and | |
221 | .B PACKET_MR_ALLMULTI | |
222 | sets the socket up to receive all multicast packets arriving at | |
223 | the interface. | |
224 | ||
225 | In addition the traditional ioctls | |
226 | .BR SIOCSIFFLAGS , | |
227 | .BR SIOCADDMULTI , | |
228 | .B SIOCDELMULTI | |
229 | can be used for the same purpose. | |
230 | .SS Ioctls | |
231 | .B SIOCGSTAMP | |
232 | can be used to receive the timestamp of the last received packet. | |
233 | Argument is a | |
234 | .I struct timeval. | |
00c84453 | 235 | .\" FIXME Document SIOCGSTAMPNS |
77117f4f MK |
236 | |
237 | In addition all standard ioctls defined in | |
238 | .BR netdevice (7) | |
239 | and | |
240 | .BR socket (7) | |
241 | are valid on packet sockets. | |
c634028a | 242 | .SS Error handling |
77117f4f MK |
243 | Packet sockets do no error handling other than errors occurred |
244 | while passing the packet to the device driver. | |
245 | They don't have the concept of a pending error. | |
246 | .SH ERRORS | |
247 | .TP | |
248 | .B EADDRNOTAVAIL | |
249 | Unknown multicast group address passed. | |
250 | .TP | |
251 | .B EFAULT | |
252 | User passed invalid memory address. | |
253 | .TP | |
254 | .B EINVAL | |
255 | Invalid argument. | |
256 | .TP | |
257 | .B EMSGSIZE | |
258 | Packet is bigger than interface MTU. | |
259 | .TP | |
260 | .B ENETDOWN | |
261 | Interface is not up. | |
262 | .TP | |
263 | .B ENOBUFS | |
264 | Not enough memory to allocate the packet. | |
265 | .TP | |
266 | .B ENODEV | |
267 | Unknown device name or interface index specified in interface address. | |
268 | .TP | |
269 | .B ENOENT | |
270 | No packet received. | |
271 | .TP | |
272 | .B ENOTCONN | |
273 | No interface address passed. | |
274 | .TP | |
275 | .B ENXIO | |
276 | Interface address contained an invalid interface index. | |
277 | .TP | |
278 | .B EPERM | |
279 | User has insufficient privileges to carry out this operation. | |
280 | ||
281 | In addition other errors may be generated by the low-level driver. | |
282 | .SH VERSIONS | |
d4c8c97c | 283 | .B AF_PACKET |
77117f4f MK |
284 | is a new feature in Linux 2.2. |
285 | Earlier Linux versions supported only | |
286 | .BR SOCK_PACKET . | |
287 | .PP | |
288 | The include file | |
289 | .I <netpacket/packet.h> | |
290 | is present since glibc 2.1. | |
291 | Older systems need: | |
292 | .sp | |
293 | .in +4n | |
294 | .nf | |
295 | #include <asm/types.h> | |
296 | #include <linux/if_packet.h> | |
297 | #include <linux/if_ether.h> /* The L2 protocols */ | |
298 | .fi | |
299 | .in | |
300 | .SH NOTES | |
301 | For portable programs it is suggested to use | |
d4c8c97c | 302 | .B AF_PACKET |
77117f4f MK |
303 | via |
304 | .BR pcap (3); | |
33a0ccb2 | 305 | although this covers only a subset of the |
d4c8c97c | 306 | .B AF_PACKET |
77117f4f MK |
307 | features. |
308 | ||
309 | The | |
310 | .B SOCK_DGRAM | |
311 | packet sockets make no attempt to create or parse the IEEE 802.2 LLC | |
312 | header for a IEEE 802.3 frame. | |
313 | When | |
314 | .B ETH_P_802_3 | |
315 | is specified as protocol for sending the kernel creates the | |
316 | 802.3 frame and fills out the length field; the user has to supply the LLC | |
317 | header to get a fully conforming packet. | |
318 | Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol | |
319 | fields; instead they are supplied to the user as protocol | |
320 | .B ETH_P_802_2 | |
321 | with the LLC header prepended. | |
322 | It is thus not possible to bind to | |
323 | .BR ETH_P_802_3 ; | |
324 | bind to | |
325 | .B ETH_P_802_2 | |
326 | instead and do the protocol multiplex yourself. | |
327 | The default for sending is the standard Ethernet DIX | |
328 | encapsulation with the protocol filled in. | |
329 | ||
330 | Packet sockets are not subject to the input or output firewall chains. | |
331 | .SS Compatibility | |
332 | In Linux 2.0, the only way to get a packet socket was by calling | |
d4c8c97c | 333 | .BI "socket(AF_INET, SOCK_PACKET, " protocol )\fR. |
77117f4f MK |
334 | This is still supported but strongly deprecated. |
335 | The main difference between the two methods is that | |
336 | .B SOCK_PACKET | |
337 | uses the old | |
338 | .I struct sockaddr_pkt | |
339 | to specify an interface, which doesn't provide physical layer | |
340 | independence. | |
341 | ||
342 | .in +4n | |
343 | .nf | |
344 | struct sockaddr_pkt { | |
345 | unsigned short spkt_family; | |
346 | unsigned char spkt_device[14]; | |
347 | unsigned short spkt_protocol; | |
348 | }; | |
349 | .fi | |
350 | .in | |
351 | ||
352 | .I spkt_family | |
353 | contains | |
354 | the device type, | |
355 | .I spkt_protocol | |
356 | is the IEEE 802.3 protocol type as defined in | |
357 | .I <sys/if_ether.h> | |
358 | and | |
359 | .I spkt_device | |
d0cb7cc6 | 360 | is the device name as a null-terminated string, for example, eth0. |
77117f4f MK |
361 | |
362 | This structure is obsolete and should not be used in new code. | |
363 | .SH BUGS | |
364 | glibc 2.1 does not have a define for | |
365 | .BR SOL_PACKET . | |
366 | The suggested workaround is to use: | |
367 | .in +4n | |
368 | .nf | |
369 | ||
370 | #ifndef SOL_PACKET | |
371 | #define SOL_PACKET 263 | |
372 | #endif | |
373 | ||
374 | .fi | |
375 | .in | |
376 | This is fixed in later glibc versions and also does not occur on | |
377 | libc5 systems. | |
378 | ||
379 | The IEEE 802.2/803.3 LLC handling could be considered as a bug. | |
380 | ||
381 | Socket filters are not documented. | |
382 | ||
383 | The | |
384 | .B MSG_TRUNC | |
385 | .BR recvmsg (2) | |
386 | extension is an ugly hack and should be replaced by a control message. | |
387 | There is currently no way to get the original destination address of | |
388 | packets via | |
389 | .BR SOCK_DGRAM . | |
390 | .\" .SH CREDITS | |
391 | .\" This man page was written by Andi Kleen with help from Matthew Wilcox. | |
d4c8c97c | 392 | .\" AF_PACKET in Linux 2.2 was implemented |
77117f4f | 393 | .\" by Alexey Kuznetsov, based on code by Alan Cox and others. |
47297adb | 394 | .SH SEE ALSO |
77117f4f MK |
395 | .BR socket (2), |
396 | .BR pcap (3), | |
397 | .BR capabilities (7), | |
398 | .BR ip (7), | |
399 | .BR raw (7), | |
400 | .BR socket (7) | |
401 | ||
402 | RFC\ 894 for the standard IP Ethernet encapsulation. | |
77117f4f MK |
403 | RFC\ 1700 for the IEEE 802.3 IP encapsulation. |
404 | ||
405 | The | |
406 | .I <linux/if_ether.h> | |
407 | include file for physical layer protocols. |