{ "mode": "man", "parameter": "packet", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/packet/7/json", "generated": "2026-09-07T08:54:38Z", "synopsis": "", "sections": { "NAME": { "content": "packet - packet interface on device level\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "#include ", "content": "" }, { "name": "#include ", "content": "#include /* the L2 protocols */\n\npacketsocket = socket(AFPACKET, int sockettype, int protocol);\n" } ] }, "DESCRIPTION": { "content": "Packet sockets are used to receive or send raw packets at the device driver (OSI Layer 2)\nlevel. They allow the user to implement protocol modules in user space on top of the physi‐\ncal layer.\n\nThe sockettype is either SOCKRAW for raw packets including the link-level header or\nSOCKDGRAM for cooked packets with the link-level header removed. The link-level header in‐\nformation is available in a common format in a sockaddrll structure. protocol is the IEEE\n802.3 protocol number in network byte order. See the include file for a\nlist of allowed protocols. When protocol is set to htons(ETHPALL), then all protocols are\nreceived. All incoming packets of that protocol type will be passed to the packet socket be‐\nfore they are passed to the protocols implemented in the kernel. If protocol is set to zero,\nno packets are received. bind(2) can optionally be called with a nonzero sllprotocol to\nstart receiving packets for the protocols specified.\n\nIn order to create a packet socket, a process must have the CAPNETRAW capability in the\nuser namespace that governs its network namespace.\n\nSOCKRAW packets are passed to and from the device driver without any changes in the packet\ndata. When receiving a packet, the address is still parsed and passed in a standard sock‐\naddrll address structure. When transmitting a packet, the user-supplied buffer should con‐\ntain the physical-layer header. That packet is then queued unmodified to the network driver\nof the interface defined by the destination address. Some device drivers always add other\nheaders. SOCKRAW is similar to but not compatible with the obsolete AFINET/SOCKPACKET of\nLinux 2.0.\n\nSOCKDGRAM operates on a slightly higher level. The physical header is removed before the\npacket is passed to the user. Packets sent through a SOCKDGRAM packet socket get a suitable\nphysical-layer header based on the information in the sockaddrll destination address before\nthey are queued.\n\nBy default, all packets of the specified protocol type are passed to a packet socket. To get\npackets only from a specific interface use bind(2) specifying an address in a struct sock‐\naddrll to bind the packet socket to an interface. Fields used for binding are sllfamily\n(should be AFPACKET), sllprotocol, and sllifindex.\n\nThe connect(2) operation is not supported on packet sockets.\n\nWhen the MSGTRUNC flag is passed to recvmsg(2), recv(2), or recvfrom(2), the real length of\nthe packet on the wire is always returned, even when it is longer than the buffer.\n", "subsections": [ { "name": "Address types", "content": "The sockaddrll structure is a device-independent physical-layer address.\n\nstruct sockaddrll {\nunsigned short sllfamily; /* Always AFPACKET */\nunsigned short sllprotocol; /* Physical-layer protocol */\nint sllifindex; /* Interface number */\nunsigned short sllhatype; /* ARP hardware type */\nunsigned char sllpkttype; /* Packet type */\nunsigned char sllhalen; /* Length of address */\nunsigned char slladdr[8]; /* Physical-layer address */\n};\n\nThe fields of this structure are as follows:\n\nsllprotocol\nis the standard ethernet protocol type in network byte order as defined in the\n include file. It defaults to the socket's protocol.\n\nsllifindex\nis the interface index of the interface (see netdevice(7)); 0 matches any interface\n(only permitted for binding). sllhatype is an ARP type as defined in the\n include file.\n\nsllpkttype\ncontains the packet type. Valid types are PACKETHOST for a packet addressed to the\nlocal host, PACKETBROADCAST for a physical-layer broadcast packet, PACKETMULTICAST\nfor a packet sent to a physical-layer multicast address, PACKETOTHERHOST for a packet\nto some other host that has been caught by a device driver in promiscuous mode, and\nPACKETOUTGOING for a packet originating from the local host that is looped back to a\npacket socket. These types make sense only for receiving.\n\nslladdr\nsllhalen\ncontain the physical-layer (e.g., IEEE 802.3) address and its length. The exact in‐\nterpretation depends on the device.\n\nWhen you send packets, it is enough to specify sllfamily, slladdr, sllhalen, sllifindex,\nand sllprotocol. The other fields should be 0. sllhatype and sllpkttype are set on re‐\nceived packets for your information.\n" }, { "name": "Socket options", "content": "Packet socket options are configured by calling setsockopt(2) with level SOLPACKET.\n\nPACKETADDMEMBERSHIP\nPACKETDROPMEMBERSHIP\nPacket sockets can be used to configure physical-layer multicasting and promiscuous\nmode. PACKETADDMEMBERSHIP adds a binding and PACKETDROPMEMBERSHIP drops it. They\nboth expect a packetmreq structure as argument:\n\nstruct packetmreq {\nint mrifindex; /* interface index */\nunsigned short mrtype; /* action */\nunsigned short mralen; /* address length */\nunsigned char mraddress[8]; /* physical-layer address */\n};\n\nmrifindex contains the interface index for the interface whose status should be\nchanged. The mrtype field specifies which action to perform. PACKETMRPROMISC en‐\nables receiving all packets on a shared medium (often known as \"promiscuous mode\"),\nPACKETMRMULTICAST binds the socket to the physical-layer multicast group specified\nin mraddress and mralen, and PACKETMRALLMULTI sets the socket up to receive all\nmulticast packets arriving at the interface.\n\nIn addition, the traditional ioctls SIOCSIFFLAGS, SIOCADDMULTI, SIOCDELMULTI can be\nused for the same purpose.\n\nPACKETAUXDATA (since Linux 2.6.21)\nIf this binary option is enabled, the packet socket passes a metadata structure along\nwith each packet in the recvmsg(2) control field. The structure can be read with\ncmsg(3). It is defined as\n\nstruct tpacketauxdata {\nu32 tpstatus;\nu32 tplen; /* packet length */\nu32 tpsnaplen; /* captured length */\nu16 tpmac;\nu16 tpnet;\nu16 tpvlantci;\nu16 tpvlantpid; /* Since Linux 3.14; earlier, these\nwere unused padding bytes */\n};\n\nPACKETFANOUT (since Linux 3.1)\nTo scale processing across threads, packet sockets can form a fanout group. In this\nmode, each matching packet is enqueued onto only one socket in the group. A socket\njoins a fanout group by calling setsockopt(2) with level SOLPACKET and option\nPACKETFANOUT. Each network namespace can have up to 65536 independent groups. A\nsocket selects a group by encoding the ID in the first 16 bits of the integer option\nvalue. The first packet socket to join a group implicitly creates it. To success‐\nfully join an existing group, subsequent packet sockets must have the same protocol,\ndevice settings, fanout mode, and flags (see below). Packet sockets can leave a\nfanout group only by closing the socket. The group is deleted when the last socket is\nclosed.\n\nFanout supports multiple algorithms to spread traffic between sockets, as follows:\n\n• The default mode, PACKETFANOUTHASH, sends packets from the same flow to the same\nsocket to maintain per-flow ordering. For each packet, it chooses a socket by tak‐\ning the packet flow hash modulo the number of sockets in the group, where a flow\nhash is a hash over network-layer address and optional transport-layer port fields.\n\n• The load-balance mode PACKETFANOUTLB implements a round-robin algorithm.\n\n• PACKETFANOUTCPU selects the socket based on the CPU that the packet arrived on.\n\n• PACKETFANOUTROLLOVER processes all data on a single socket, moving to the next\nwhen one becomes backlogged.\n\n• PACKETFANOUTRND selects the socket using a pseudo-random number generator.\n\n• PACKETFANOUTQM (available since Linux 3.14) selects the socket using the recorded\nqueuemapping of the received skb.\n\nFanout modes can take additional options. IP fragmentation causes packets from the\nsame flow to have different flow hashes. The flag PACKETFANOUTFLAGDEFRAG, if set,\ncauses packets to be defragmented before fanout is applied, to preserve order even in\nthis case. Fanout mode and options are communicated in the second 16 bits of the in‐\nteger option value. The flag PACKETFANOUTFLAGROLLOVER enables the roll over mecha‐\nnism as a backup strategy: if the original fanout algorithm selects a backlogged\nsocket, the packet rolls over to the next available one.\n\nPACKETLOSS (with PACKETTXRING)\nWhen a malformed packet is encountered on a transmit ring, the default is to reset its\ntpstatus to TPSTATUSWRONGFORMAT and abort the transmission immediately. The mal‐\nformed packet blocks itself and subsequently enqueued packets from being sent. The\nformat error must be fixed, the associated tpstatus reset to TPSTATUSSENDREQUEST,\nand the transmission process restarted via send(2). However, if PACKETLOSS is set,\nany malformed packet will be skipped, its tpstatus reset to TPSTATUSAVAILABLE, and\nthe transmission process continued.\n\nPACKETRESERVE (with PACKETRXRING)\nBy default, a packet receive ring writes packets immediately following the metadata\nstructure and alignment padding. This integer option reserves additional headroom.\n\nPACKETRXRING\nCreate a memory-mapped ring buffer for asynchronous packet reception. The packet\nsocket reserves a contiguous region of application address space, lays it out into an\narray of packet slots and copies packets (up to tpsnaplen) into subsequent slots.\nEach packet is preceded by a metadata structure similar to tpacketauxdata. The pro‐\ntocol fields encode the offset to the data from the start of the metadata header.\ntpnet stores the offset to the network layer. If the packet socket is of type\nSOCKDGRAM, then tpmac is the same. If it is of type SOCKRAW, then that field\nstores the offset to the link-layer frame. Packet socket and application communicate\nthe head and tail of the ring through the tpstatus field. The packet socket owns all\nslots with tpstatus equal to TPSTATUSKERNEL. After filling a slot, it changes the\nstatus of the slot to transfer ownership to the application. During normal operation,\nthe new tpstatus value has at least the TPSTATUSUSER bit set to signal that a re‐\nceived packet has been stored. When the application has finished processing a packet,\nit transfers ownership of the slot back to the socket by setting tpstatus equal to\nTPSTATUSKERNEL.\n\nPacket sockets implement multiple variants of the packet ring. The implementation de‐\ntails are described in Documentation/networking/packetmmap.rst in the Linux kernel\nsource tree.\n\nPACKETSTATISTICS\nRetrieve packet socket statistics in the form of a structure\n\nstruct tpacketstats {\nunsigned int tppackets; /* Total packet count */\nunsigned int tpdrops; /* Dropped packet count */\n};\n\nReceiving statistics resets the internal counters. The statistics structure differs\nwhen using a ring of variant TPACKETV3.\n\nPACKETTIMESTAMP (with PACKETRXRING; since Linux 2.6.36)\nThe packet receive ring always stores a timestamp in the metadata header. By default,\nthis is a software generated timestamp generated when the packet is copied into the\nring. This integer option selects the type of timestamp. Besides the default, it\nsupport the two hardware formats described in Documentation/networking/timestamp‐\ning.rst in the Linux kernel source tree.\n\nPACKETTXRING (since Linux 2.6.31)\nCreate a memory-mapped ring buffer for packet transmission. This option is similar to\nPACKETRXRING and takes the same arguments. The application writes packets into\nslots with tpstatus equal to TPSTATUSAVAILABLE and schedules them for transmission\nby changing tpstatus to TPSTATUSSENDREQUEST. When packets are ready to be trans‐\nmitted, the application calls send(2) or a variant thereof. The buf and len fields of\nthis call are ignored. If an address is passed using sendto(2) or sendmsg(2), then\nthat overrides the socket default. On successful transmission, the socket resets\ntpstatus to TPSTATUSAVAILABLE. It immediately aborts the transmission on error un‐\nless PACKETLOSS is set.\n\nPACKETVERSION (with PACKETRXRING; since Linux 2.6.27)\nBy default, PACKETRXRING creates a packet receive ring of variant TPACKETV1. To\ncreate another variant, configure the desired variant by setting this integer option\nbefore creating the ring.\n\nPACKETQDISCBYPASS (since Linux 3.14)\nBy default, packets sent through packet sockets pass through the kernel's qdisc (traf‐\nfic control) layer, which is fine for the vast majority of use cases. For traffic\ngenerator appliances using packet sockets that intend to brute-force flood the net‐\nwork—for example, to test devices under load in a similar fashion to pktgen—this layer\ncan be bypassed by setting this integer option to 1. A side effect is that packet\nbuffering in the qdisc layer is avoided, which will lead to increased drops when net‐\nwork device transmit queues are busy; therefore, use at your own risk.\n" }, { "name": "Ioctls", "content": "SIOCGSTAMP can be used to receive the timestamp of the last received packet. Argument is a\nstruct timeval variable.\n\nIn addition, all standard ioctls defined in netdevice(7) and socket(7) are valid on packet\nsockets.\n" }, { "name": "Error handling", "content": "Packet sockets do no error handling other than errors occurred while passing the packet to\nthe device driver. They don't have the concept of a pending error.\n" } ] }, "ERRORS": { "content": "EADDRNOTAVAIL\nUnknown multicast group address passed.\n\nEFAULT User passed invalid memory address.\n\nEINVAL Invalid argument.\n\nEMSGSIZE\nPacket is bigger than interface MTU.\n\nENETDOWN\nInterface is not up.\n\nENOBUFS\nNot enough memory to allocate the packet.\n\nENODEV Unknown device name or interface index specified in interface address.\n\nENOENT No packet received.\n\nENOTCONN\nNo interface address passed.\n\nENXIO Interface address contained an invalid interface index.\n\nEPERM User has insufficient privileges to carry out this operation.\n\nIn addition, other errors may be generated by the low-level driver.\n", "subsections": [] }, "VERSIONS": { "content": "AFPACKET is a new feature in Linux 2.2. Earlier Linux versions supported only SOCKPACKET.\n", "subsections": [] }, "NOTES": { "content": "For portable programs it is suggested to use AFPACKET via pcap(3); although this covers only\na subset of the AFPACKET features.\n\nThe SOCKDGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC header\nfor a IEEE 802.3 frame. When ETHP8023 is specified as protocol for sending the kernel\ncreates the 802.3 frame and fills out the length field; the user has to supply the LLC header\nto get a fully conforming packet. Incoming 802.3 packets are not multiplexed on the\nDSAP/SSAP protocol fields; instead they are supplied to the user as protocol ETHP8022 with\nthe LLC header prefixed. It is thus not possible to bind to ETHP8023; bind to ETHP8022\ninstead and do the protocol multiplex yourself. The default for sending is the standard Eth‐\nernet DIX encapsulation with the protocol filled in.\n\nPacket sockets are not subject to the input or output firewall chains.\n", "subsections": [ { "name": "Compatibility", "content": "In Linux 2.0, the only way to get a packet socket was with the call:\n\nsocket(AFINET, SOCKPACKET, protocol)\n\nThis is still supported, but deprecated and strongly discouraged. The main difference be‐\ntween the two methods is that SOCKPACKET uses the old struct sockaddrpkt to specify an in‐\nterface, which doesn't provide physical-layer independence.\n\nstruct sockaddrpkt {\nunsigned short spktfamily;\nunsigned char spktdevice[14];\nunsigned short spktprotocol;\n};\n\nspktfamily contains the device type, spktprotocol is the IEEE 802.3 protocol type as de‐\nfined in and spktdevice is the device name as a null-terminated string, for\nexample, eth0.\n\nThis structure is obsolete and should not be used in new code.\n" } ] }, "BUGS": { "content": "", "subsections": [ { "name": "LLC header handling", "content": "The IEEE 802.2/803.3 LLC handling could be considered as a bug.\n" }, { "name": "MSG_TRUNC issues", "content": "The MSGTRUNC recvmsg(2) extension is an ugly hack and should be replaced by a control mes‐\nsage. There is currently no way to get the original destination address of packets via\nSOCKDGRAM.\n" }, { "name": "spkt_device device name truncation", "content": "The spktdevice field of sockaddrpkt has a size of 14 bytes, which is less than the constant\nIFNAMSIZ defined in which is 16 bytes and describes the system limit for a network\ninterface name. This means the names of network devices longer than 14 bytes will be trun‐\ncated to fit into spktdevice. All these lengths include the terminating null byte ('\\0')).\n\nIssues from this with old code typically show up with very long interface names used by the\nPredictable Network Interface Names feature enabled by default in many modern Linux distribu‐\ntions.\n\nThe preferred solution is to rewrite code to avoid SOCKPACKET. Possible user solutions are\nto disable Predictable Network Interface Names or to rename the interface to a name of at\nmost 13 bytes, for example using the ip(8) tool.\n" }, { "name": "Documentation issues", "content": "Socket filters are not documented.\n" } ] }, "SEE ALSO": { "content": "socket(2), pcap(3), capabilities(7), ip(7), raw(7), socket(7), ip(8),\n\nRFC 894 for the standard IP Ethernet encapsulation. RFC 1700 for the IEEE 802.3 IP encapsu‐\nlation.\n\nThe include file for physical-layer protocols.\n\nThe Linux kernel source tree. Documentation/networking/filter.rst describes how to apply\nBerkeley Packet Filters to packet sockets. tools/testing/selftests/net/psocktpacket.c con‐\ntains example source code for all available versions of PACKETRXRING and PACKETTXRING.\n\nLinux man-pages 6.7 2023-10-31 packet(7)", "subsections": [] } }, "summary": "packet - packet interface on device level", "flags": [], "examples": [], "see_also": [ { "name": "socket", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/socket/2/json" }, { "name": "pcap", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/pcap/3/json" }, { "name": "capabilities", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/capabilities/7/json" }, { "name": "ip", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ip/7/json" }, { "name": "raw", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/raw/7/json" }, { "name": "socket", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/socket/7/json" }, { "name": "ip", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/ip/8/json" } ] }