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

NAME
       netlink,  PF_NETLINK  -  Communication  between kernel and
       user.

SYNOPSIS
       #include <asm/types.h>
       #include <sys/socket.h>
       #include <linux/netlink.h>
       netlink_socket    =    socket(PF_NETLINK,     socket_type,
       netlink_family);

       int NLMSG_ALIGN(size_t len);
       int NLMSG_LENGTH(size_t len);
       int NLMSG_SPACE(size_t len);
       void *NLMSG_DATA(struct nlmsghdr *);
       struct   nlmsghdr   *NLMSG_NEXT(struct   nlmsghdr  *,  int
       length);
       int NLMSG_OK(struct nlmsghdr *, int length);
       int NLMSG_PAYLOAD(struct nlmsghdr *, int length);

DESCRIPTION
       Netlink is used to transfer information between kernel and
       user  space  modules.   It  consists of a standard sockets
       based interface for user processes and an internal  kernel
       API  for  kernel modules. The internal kernel interface is
       not documented in this man page.

       Netlink is a datagram oriented service. Valid socket types
       are SOCK_RAW and SOCK_DGRAM.

       netlink_family  selects the kernel module or netlink group
       to communicate with.  Currently assigned netlink  families
       are:  NETLINK_ROUTE to receive routing updates and to mod-
       ify the IP routing  table.   NETLINK_FIREWALL  to  receive
       packets  sent  by the IPv4 firewall code.  NETLINK_ARPD to
       manage the arp table in  user  space.   NETLINK_ROUTE6  to
       receive    and    send   IPv6   routing   table   updates.
       NETLINK_IP6_FW to receive packets  that  failed  the  IPv6
       firewall checks (currently not implemented).  NETLINK_TAP-
       BASE ...  NETLINK_TAPBASE+15  are  the  instances  of  the
       ethertap  device.  Ethertap  is  a  pseudo  network tunnel
       device that allows to simulate  an  ethernet  driver  from
       user  space.   Reserved  are  NETLINK_SKIP  for ENskip and
       NETLINK_USERSOCK for future user space protocols.

       Netlink messages consist of a byte stream with one or mul-
       tiple  nlmsghdr headers and associated payload. For multi-
       part messages the first and all following headers have the
       NLM_F_MULTI flag set, except for the last header which has
       the type  NLMSG_DONE.  The  byte  stream  should  be  only
       accessed with the standard NLMSG_* macros.

       Netlink  is  pseudo reliable. This means it tries its best
       to deliver a message to its destination(s), but  may  drop
       messages  when  an  out of memory condition or other error
       occurs. For reliable transfer the sender  can  request  an
       acknowledgement from the receiver by setting the NLM_F_ACK
       flag.  An acknowledgment is a NLMSG_ERROR packet with  the
       error  field  set  to 0. The user has to handle generating
       acks for received messages himself. The  kernel  tries  to
       send an NLMSG_ERROR message for every failed packet.

              struct nlmsghdr
              {
                   __u32          nlmsg_len;     /* Length of message including header */
                   __u16          nlmsg_type;    /* Message content */
                   __u16          nlmsg_flags;   /* Additional flags */
                   __u32          nlmsg_seq;     /* Sequence number */
                   __u32          nlmsg_pid;     /* Sending process PID */
              };

              struct nlmsgerr
              {
                   int  error;         /* error: negative errno or 0 for acks. */
                   struct nlmsghdr msg;     /* message header that caused the error */
              };

       After  each  nlmsghdr the payload follows.  nlmsg_type can
       be one of the standard message types:  NLMSG_NOOP  message
       is to be ignored, NLMSG_ERROR the message signals an error
       and the payload contains a nlmsgerr structure,  NLMSG_DONE
       message terminates a multipart message,

       A netlink family usually has more specified message types,
       see the appropiate man pages for that, e.g.   rtnetlink(4)
       for NETLINK_ROUTE.

       Standard Flag bits in nlmsg_flags
       NLM_F_REQUEST   set on all request messages
       NLM_F_MULTI     the message is part of a multipart mes-
                       sage terminated by NLMSG_DONE
       NLM_F_ACK       reply with an acknowledgment on success
       NLM_F_ECHO      echo this request

       Additional flag bits for GET requests
       NLM_F_ROOT     Return the complete table instead of a single entry.
       NLM_F_MATCH    Not implemented yet.
       NLM_F_ATOMIC   Return an atomic snapshot of the table. Requires CAP_NET_ADMIN or super user rights.
       NLM_F_DUMP     not documented yet.

       Additional flag bits for NEW requests
       NLM_F_REPLACE   Override existing object.
       NLM_F_EXCL      Don't replace if the object already exists.
       NLM_F_CREATE    Create object if it doesn't already exist.
       NLM_F_APPEND    Add to the end of the object list.

ADDRESS FORMATS
       The sockaddr_nl structure describes a  netlink  client  in
       user  space or in the kernel.  A sockaddr_nl can be either
       unicast (only send to one peer) or send to netlink  groups
       (nl_groups not equal 0).

              struct sockaddr_nl
              {
                  sa_family_t nl_family;    /* AF_NETLINK */
                  unsigned short nl_pad;    /* zero */
                  pid_t       nl_pid;       /* process pid */
                  __u32       nl_groups;    /* multicast groups mask */
              };

       nl_pid  is  the pid of the user space netlink, or 0 if the
       destination is in the kernel.  nl_groups is a bitmask with
       every bit representing a netlink group number.

NETLINK MACROS
       Netlink  defines several standard macros to access or cre-
       ate a netlink datagram.  They are similar in spirit to the
       macros  defined in cmsg(3) for auxilliary data. The buffer
       passed to  and  from  a  netlink  socket  should  be  only
       accessed using these macros.

       NLMSG_ALIGN
               Round  the length of a netlink message up to align
               it properly.

       NLMSG_LENGTH
               Gets the payload length as  argument  and  returns
               the aligned length to store in the nlmsg_len field
               of the nlmsghdr.

       NLMSG_SPACE
               Return the number of bytes a netlink message  with
               payload of the passed length would occupy.

       NLMSG_DATA
               Return  a  pointer  to the payload associated with
               the passed nlmsghdr

       NLMSG_NEXT
               Get the next nlmsghdr in a multipart message.  The
               caller  must  check if the current nlmsghdr didn't
               have the NLMSG_DONE set -  this  function  doesn't
               return  NULL  on  end.  The length parameter is an
               lvalue containing the remaining length of the mes-
               sage  buffer.  This  macro  decrements  it  by the
               length of the message header.

       NLMSG_OK
               Return true if the netlink message  is  not  trun-
               cated and ok to parse.

       NLMSG_PAYLOAD
               Return  the  length of the payload associated with
               the nlmsghdr

BUGS
       This man page is not complete.

SEE ALSO
       cmsg(3), rtnetlink(4)

VERSIONS
       The socket interface to netlink is a new feature of  Linux
       2.2

       Linux  2.0 supported a more primitive device based netlink
       interface (which is still  available  as  a  compatibility
       option). This old interface is not described here.

Linux Man Page             23 Oct 1998                          1