PACKET(4)           Linux Programmer's Manual           PACKET(4)

NAME
       packet, PF_PACKET - packet interface on device level.

SYNOPSIS
       #include <sys/socket.h>
       #include <sys/if_packet.h>

       packet_socket = socket(PF_PACKET, socket_type, protocol);

DESCRIPTION
       Packet  sockets are used to receive or send raw packets on
       the device driver (OSI Layer 2) level. They allow the user
       to  implement protocol modules in user space on top of the
       physical layer.

       socket_type is either SOCK_RAW for raw  packets  including
       the  link  level  header  or SOCK_DGRAM for cooked packets
       with the link level header removed. The link level  header
       informations  are  available in a common format in a sock-
       addr_ll.  protocol is the IEEE 802.3  protocol  number  in
       network order. See the <sys/if_ether.h> include file for a
       list of allowed protocols.  All incoming packets with that
       protocol  will be first passed to the packet socket, after
       that to the other protocols implemented in the kernel.

       Only processes with effective uid  0  or  the  CAP_NET_RAW
       attribute set may open packet sockets.

       There  are  two  types  of  packet  sockets:  SOCK_RAW and
       SOCK_DGRAM.  SOCK_RAW is directly passed to and  from  the
       device  driver without any changes in the packet data. The
       user program has to know about the physical header  struc-
       ture  of  the  device  to  properly  set  up and parse the
       packet. The address is still parsed and passed in a  stan-
       dard  sockaddr_ll  address  structure. SOCK_RAW is similar
       but not compatible to the obsolete  SOCK_PACKET  of  Linux
       2.0.

       SOCK_DGRAM operates on a slightly higher level. The physi-
       cal header is removed before passing  the  packet  to  the
       user (and prepended before sending it).

       Per  default  all  packets  with  the  specified  protocol
       received from any interface are passed to a packet socket.
       To  only get packets from a specific interface use bind(2)
       with a sockaddr_ll address to bind the packet to an inter-
       face.

       For  sending  to SOCK_RAW sockets the user supplied buffer
       has to contain the complete packet including the  physical
       layer header. That packet is then queued unmodified to the
       network driver of the interface defined by the destination
       address.   Packets sent through a SOCK_DGRAM packet socket
       get a suitable physical layer header based on the informa-
       tion  in  the  sockaddr_ll destination address before they
       are queued.

ADDRESS TYPES
       The sockaddr_ll is a  device  independent  physical  layer
       address.

              struct sockaddr_ll
              {
                  unsigned short  sll_family; /* Always AF_PACKET */
                  unsigned short  sll_protocol;/* Physical layer protocol in network order */
                  int                         sll_ifindex;/* Interface number */
                  unsigned short  sll_hatype; /* Header type */
                  unsigned char   sll_pkttype;/* Packet type */
                  unsigned char   sll_halen;  /* Length of address */
                  unsigned char   sll_addr[8];/* Physical layer address */
              };

       sll_protocol is standard ethernet protocol type in network
       order as  defined  in  the  sys/if_ether.h  include  file.
       sll_hatype  is  a  ARP type as defined in the sys/if_arp.h
       include file.  sll_pkttype contains the packet type. Valid
       types  are PACKET_HOST for a packet addressed to the local
       host, PACKET_BROADCAST for a  physical  layer  broadcasted
       packet,  PACKET_MULTICAST  for a packet sent to a physical
       layer multicast address, PACKET_OTHERHOST for a packet  to
       some other host that has been caught by a device driver in
       promiscuous mode, and PACKET_OUTGOING for a packet  origi-
       nated  from the local host that is looped back to a packet
       socket.  sll_halen and sll_addr contain the physical layer
       (e.g. IEEE 802.3) address and its length.

MULTICAST AND PROMISCUOUS MODE SUPPORT
       Linux  2.2  supports a new way to configure physical layer
       multicasting and promiscuous mode over packet sockets.  It
       works  by  calling  setsockopt(2)  on  a packet socket for
       SOL_PACKET and one of the options PACKET_ADD_MEMBERSHIP or
       PACKET_DROP_MEMBERSHIP.   They  both  expect a packet_mreq
       structure as argument:

              struct packet_mreq
              {
              intmr_ifindex;   /* interface index */
              unsigned shortmr_type;   /* mreq type as defined below */
              unsigned shortmr_alen;   /* address length */
              unsigned charmr_address[8];   /* physical layer address */
              };

       mr_interface contains the interface index for  the  inter-
       face  whose  status  should be changed.  Valid options for
       mr_type are PACKET_MR_MULTICAST to bind the socket to  the
       physical layer multicast group specified in mr_address and
       mr_alen, PACKET_MR_PROMISC to enable promiscuous  mode  on
       the  interface  to receive all packets on a shared medium,
       PACKET_MR_ALLMULTI sets the socket up to receive all  mul-
       ticast     packets     arriving    at    the    interface.
       PACKET_DROP_MEMBERSHIP removes the binding or setting.

IOCTLS
       These ioctls can be accessed using ioctl(2).  The  correct
       syntax    is   error   =   ioctl(tcp_socket,   ioctl_type,
       value_ptr);

       SIOCGSTAMP Return a struct timeval with the receive times-
       tamp of the last packet passed to the user. This is useful
       for accurate round trip time measurements  and  the  like.
       See setitimer(2) for a description of struct timeval.

       FIOCSETOWN  and SIOCSPGRP set the process or process group
       (negative value) to send SIGIO to when an asynchronous  IO
       operation has finished. Argument is a pid_t.

       FIOCGETOWN  and  SIOCGPGRP get the current process or pro-
       cess group that receive SIGIOs, or 0  when  none  is  set.
       Argument is a pid_t.

       In addition you may pass all network device ioctls.

ERROR HANDLING
       Packet  sockets  do  no  error  handling other than errors
       occurred while passing the packet to  the  device  driver.
       They don't have the concept of a pending error.

COMPATIBILITY
       Linux   2.0   only   supported   SOCK_RAW   as   (PF_INET,
       SOCK_PACKET). This is still supported but deprecated.  The
       main  difference  between SOCK_RAW and SOCK_PACKET is that
       that SOCK_PACKET uses the old  sockaddr_pkt  structure  to
       specify an interface.

              struct sockaddr_pkt
              {
              unsigned short spkt_family;
              unsigned char spkt_device[14];
              unsigned short spkt_protocol;
              };

       spkt_family contains the device type, spkt_protocol is the
       IEEE 802.3 protocol type as defined in the  sys/if_ether.h
       include.   spkt_device is the device name as a null termi-
       nated string, e.g. eth0.

       This structure is obsolete and should not be used  in  new
       code.

ERRORS
       ENETDOWN
              Interface is not up.

       ENOTCONN
              No interface address passed.

       ENODEV Unknown device name or interface index specified in
              interface address.

       EMSGSIZE
              Packet is bigger than interface MTU.

       ENOBUFS
              Not enough memory to allocate the packet.

       EFAULT User passed invalid memory address.

       EINVAL Invalid argument.

       ENXIO  Interface  address  contained   illegal   interface
              index.

       EPERM  User  doesn't  have  an  effective  uid of 0 or the
              CAP_NET_RAW attribute.

       EADDRNOTAVAIL
              Unknown multicast group address passed.

       ENOENT No packet received.

SEE ALSO
       ip(4), socket(4), socket(2), raw(4)

Linux Man Page              3 Oct 1998                          1