1PACKET(7)                  Linux Programmer's Manual                 PACKET(7)
2
3
4

NAME

6       packet - packet interface on device level.
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <netpacket/packet.h>
11       #include <net/ethernet.h> /* the L2 protocols */
12
13       packet_socket = socket(AF_PACKET, int socket_type, int protocol);
14

DESCRIPTION

16       Packet  sockets  are  used to receive or send raw packets at the device
17       driver (OSI Layer 2) level.  They allow the user to implement  protocol
18       modules in user space on top of the physical layer.
19
20       The  socket_type  is either SOCK_RAW for raw packets including the link
21       level header or SOCK_DGRAM for  cooked  packets  with  the  link  level
22       header  removed.   The  link level header information is available in a
23       common format in a sockaddr_ll.  protocol is the  IEEE  802.3  protocol
24       number in network order.  See the <linux/if_ether.h> include file for a
25       list of allowed protocols.  When protocol is  set  to  htons(ETH_P_ALL)
26       then all protocols are received.  All incoming packets of that protocol
27       type will be passed to the packet socket before they are passed to  the
28       protocols implemented in the kernel.
29
30       Only  processes  with effective UID 0 or the CAP_NET_RAW capability may
31       open packet sockets.
32
33       SOCK_RAW packets are passed to and from the device driver  without  any
34       changes  in  the  packet data.  When receiving a packet, the address is
35       still parsed and passed in a standard  sockaddr_ll  address  structure.
36       When transmitting a packet, the user supplied buffer should contain the
37       physical layer header.  That packet is then queued  unmodified  to  the
38       network  driver  of  the  interface defined by the destination address.
39       Some device drivers always add other headers.  SOCK_RAW is  similar  to
40       but not compatible with the obsolete AF_INET/SOCK_PACKET of Linux 2.0.
41
42       SOCK_DGRAM operates on a slightly higher level.  The physical header is
43       removed before the packet is passed to the user.  Packets sent  through
44       a  SOCK_DGRAM  packet socket get a suitable physical layer header based
45       on the information in the sockaddr_ll destination address  before  they
46       are queued.
47
48       By  default  all packets of the specified protocol type are passed to a
49       packet socket.  To get packets  only  from  a  specific  interface  use
50       bind(2)  specifying  an  address  in  a  struct sockaddr_ll to bind the
51       packet  socket  to  an  interface.   Only  the  sll_protocol  and   the
52       sll_ifindex address fields are used for purposes of binding.
53
54       The connect(2) operation is not supported on packet sockets.
55
56       When  the  MSG_TRUNC flag is passed to recvmsg(2), recv(2), recvfrom(2)
57       the real length of the packet on the wire is always returned, even when
58       it is longer than the buffer.
59
60   Address types
61       The sockaddr_ll is a device independent physical layer address.
62
63           struct sockaddr_ll {
64               unsigned short sll_family;   /* Always AF_PACKET */
65               unsigned short sll_protocol; /* Physical layer protocol */
66               int            sll_ifindex;  /* Interface number */
67               unsigned short sll_hatype;   /* ARP hardware type */
68               unsigned char  sll_pkttype;  /* Packet type */
69               unsigned char  sll_halen;    /* Length of address */
70               unsigned char  sll_addr[8];  /* Physical layer address */
71           };
72
73       sll_protocol is the standard ethernet protocol type in network order as
74       defined in the <linux/if_ether.h> include file.   It  defaults  to  the
75       socket's protocol.  sll_ifindex is the interface index of the interface
76       (see netdevice(7)); 0 matches any interface (only permitted  for  bind‐
77       ing).   sll_hatype  is  an  ARP type as defined in the <linux/if_arp.h>
78       include file.  sll_pkttype contains the packet type.  Valid  types  are
79       PACKET_HOST  for a packet addressed to the local host, PACKET_BROADCAST
80       for a physical layer broadcast packet, PACKET_MULTICAST  for  a  packet
81       sent  to  a  physical  layer  multicast address, PACKET_OTHERHOST for a
82       packet to some other host that has been caught by a  device  driver  in
83       promiscuous  mode, and PACKET_OUTGOING for a packet originated from the
84       local host that is looped back to a packet socket.   These  types  make
85       sense  only for receiving.  sll_addr and sll_halen contain the physical
86       layer (e.g., IEEE 802.3) address and its length.  The exact interpreta‐
87       tion depends on the device.
88
89       When  you  send  packets  it is enough to specify sll_family, sll_addr,
90       sll_halen, sll_ifindex.  The other fields should be 0.  sll_hatype  and
91       sll_pkttype are set on received packets for your information.  For bind
92       only sll_protocol and sll_ifindex are used.
93
94   Socket options
95       Packet sockets can be used to configure physical layer multicasting and
96       promiscuous mode.  It works by calling setsockopt(2) on a packet socket
97       for SOL_PACKET and one of the options PACKET_ADD_MEMBERSHIP  to  add  a
98       binding  or  PACKET_DROP_MEMBERSHIP  to  drop  it.   They both expect a
99       packet_mreq structure as argument:
100
101           struct packet_mreq {
102               int            mr_ifindex;    /* interface index */
103               unsigned short mr_type;       /* action */
104               unsigned short mr_alen;       /* address length */
105               unsigned char  mr_address[8]; /* physical layer address */
106           };
107
108       mr_ifindex contains the interface index for the interface whose  status
109       should  be  changed.   The  mr_type parameter specifies which action to
110       perform.  PACKET_MR_PROMISC enables receiving all packets on  a  shared
111       medium  (often  known as "promiscuous mode"), PACKET_MR_MULTICAST binds
112       the  socket  to  the  physical  layer  multicast  group  specified   in
113       mr_address  and  mr_alen,  and PACKET_MR_ALLMULTI sets the socket up to
114       receive all multicast packets arriving at the interface.
115
116       In addition the traditional ioctls SIOCSIFFLAGS, SIOCADDMULTI, SIOCDEL‐
117       MULTI can be used for the same purpose.
118
119   Ioctls
120       SIOCGSTAMP  can  be  used to receive the timestamp of the last received
121       packet.  Argument is a struct timeval.
122
123       In addition all standard ioctls defined in netdevice(7)  and  socket(7)
124       are valid on packet sockets.
125
126   Error handling
127       Packet  sockets  do  no error handling other than errors occurred while
128       passing the packet to the device driver.  They don't have  the  concept
129       of a pending error.
130

ERRORS

132       EADDRNOTAVAIL
133              Unknown multicast group address passed.
134
135       EFAULT User passed invalid memory address.
136
137       EINVAL Invalid argument.
138
139       EMSGSIZE
140              Packet is bigger than interface MTU.
141
142       ENETDOWN
143              Interface is not up.
144
145       ENOBUFS
146              Not enough memory to allocate the packet.
147
148       ENODEV Unknown  device  name  or interface index specified in interface
149              address.
150
151       ENOENT No packet received.
152
153       ENOTCONN
154              No interface address passed.
155
156       ENXIO  Interface address contained an invalid interface index.
157
158       EPERM  User has insufficient privileges to carry out this operation.
159
160              In addition other errors  may  be  generated  by  the  low-level
161              driver.
162

VERSIONS

164       AF_PACKET  is  a new feature in Linux 2.2.  Earlier Linux versions sup‐
165       ported only SOCK_PACKET.
166
167       The include file  <netpacket/packet.h>  is  present  since  glibc  2.1.
168       Older systems need:
169
170           #include <asm/types.h>
171           #include <linux/if_packet.h>
172           #include <linux/if_ether.h>  /* The L2 protocols */
173

NOTES

175       For  portable  programs  it  is suggested to use AF_PACKET via pcap(3);
176       although this covers only a subset of the AF_PACKET features.
177
178       The SOCK_DGRAM packet sockets make no attempt to create  or  parse  the
179       IEEE  802.2  LLC  header  for  a IEEE 802.3 frame.  When ETH_P_802_3 is
180       specified as protocol for sending the kernel creates  the  802.3  frame
181       and  fills  out the length field; the user has to supply the LLC header
182       to get a fully conforming packet.  Incoming 802.3 packets are not  mul‐
183       tiplexed on the DSAP/SSAP protocol fields; instead they are supplied to
184       the user as protocol ETH_P_802_2 with the LLC header prepended.  It  is
185       thus  not  possible to bind to ETH_P_802_3; bind to ETH_P_802_2 instead
186       and do the protocol multiplex yourself.  The default for sending is the
187       standard Ethernet DIX encapsulation with the protocol filled in.
188
189       Packet sockets are not subject to the input or output firewall chains.
190
191   Compatibility
192       In  Linux  2.0,  the  only  way  to  get a packet socket was by calling
193       socket(AF_INET, SOCK_PACKET, protocol).  This is  still  supported  but
194       strongly  deprecated.   The  main difference between the two methods is
195       that SOCK_PACKET uses the old struct sockaddr_pkt to specify an  inter‐
196       face, which doesn't provide physical layer independence.
197
198           struct sockaddr_pkt {
199               unsigned short spkt_family;
200               unsigned char  spkt_device[14];
201               unsigned short spkt_protocol;
202           };
203
204       spkt_family  contains  the device type, spkt_protocol is the IEEE 802.3
205       protocol type as defined in <sys/if_ether.h>  and  spkt_device  is  the
206       device name as a null-terminated string, for example, eth0.
207
208       This structure is obsolete and should not be used in new code.
209

BUGS

211       glibc  2.1  does not have a define for SOL_PACKET.  The suggested work‐
212       around is to use:
213
214           #ifndef SOL_PACKET
215           #define SOL_PACKET 263
216           #endif
217
218       This is fixed in later glibc versions and also does not occur on  libc5
219       systems.
220
221       The IEEE 802.2/803.3 LLC handling could be considered as a bug.
222
223       Socket filters are not documented.
224
225       The  MSG_TRUNC  recvmsg(2)  extension  is  an  ugly  hack and should be
226       replaced by a control message.  There is currently no way  to  get  the
227       original destination address of packets via SOCK_DGRAM.
228

SEE ALSO

230       socket(2), pcap(3), capabilities(7), ip(7), raw(7), socket(7)
231
232       RFC 894  for  the standard IP Ethernet encapsulation.  RFC 1700 for the
233       IEEE 802.3 IP encapsulation.
234
235       The <linux/if_ether.h> include file for physical layer protocols.
236

COLOPHON

238       This page is part of release 3.53 of the Linux  man-pages  project.   A
239       description  of  the project, and information about reporting bugs, can
240       be found at http://www.kernel.org/doc/man-pages/.
241
242
243
244Linux                             2012-05-10                         PACKET(7)
Impressum