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



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);


DESCRIPTION

       Netlink is used to  transfer  information  between  kernel
       modules  and user space processes.  It consists of a stan-
       dard sockets based interface for  user  processes  and  an
       internal  kernel API for kernel modules. The internal ker-
       nel interface is not documented in  this  man  page.  Also
       there is an obsolete netlink interface via netlink charac-
       ter devices, this interface is not documented here and  is
       only provided for backwards compatibility.

       Netlink is a datagram oriented service.  Both SOCK_RAW and
       SOCK_DGRAM are valid values for socket_type;  however  the
       netlink protocol does not distinguish between datagram and
       raw sockets.

       netlink_family selects the kernel module or netlink  group
       to communicate with.  The currently assigned netlink fami-
       lies are:

       NETLINK_ROUTE
              Receives routing updates and may be used to  modify
              the IPv4 routing table (see rtnetlink(7)).

       NETLINK_FIREWALL
              Receives packets sent by the IPv4 firewall code.

       NETLINK_ARPD
              For managing the arp table in user space.

       NETLINK_ROUTE6
              Receives and sends IPv6 routing table updates.

       NETLINK_IP6_FW
              to  receive  packets  that failed the IPv6 firewall
              checks (currently not implemented).

       NETLINK_TAPBASE...NETLINK_TAPBASE+15
              are the instances of the ethertap device.  Ethertap
              is  a  pseudo  network tunnel device that allows an
              ethernet driver to be simulated from user space.

       NETLINK_SKIP
              Reserved for ENskip.



Linux Man Page             27 Apr 1999                          1





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


       NETLINK_USERSOCK
              is reserved 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  only  be
       accessed with the standard NLMSG_* macros, see netlink(3).

       Netlink is not a reliable protocol.  It tries its best  to
       deliver a message to its destination(s), but may drop mes-
       sages 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 an NLMSG_ERROR packet with the
       error field set to 0.  The application must generate  acks
       for received messages itself.  The kernel tries to send an
       NLMSG_ERROR message for every failed packet.  A user  pro-
       cess should follow this convention too.

       Each  netlink  family  has  a  set of 32 multicast groups.
       When bind(2) is called on the socket, the nl_groups  field
       in  the  sockaddr_nl  should  be  set  to a bitmask of the
       groups which it wishes to listen to.   The  default  value
       for this field is zero which means that no multicasts will
       be received.  A socket may multicast messages  to  any  of
       the  multicast groups by setting nl_groups to a bitmask of
       the groups it wishes to send to when it  calls  sendmsg(2)
       or does a connect(2).  Only users with an effective uid of
       0 or the CAP_NET_ADMIN capability may send or listen to  a
       netlink   multicast  group.   Any  replies  to  a  message
       received for a multicast group should be sent back to  the
       sending pid and the multicast group.

              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;  /* PID of the process that opened the socket */
              };


              struct nlmsgerr
              {
                  int      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



Linux Man Page             27 Apr 1999                          2





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


       and the payload contains a nlmsgerr structure,  NLMSG_DONE
       message terminates a multipart message,

       A netlink family usually specifies more message types, see
       the appropriate man pages for that, e.g.  rtnetlink(7) for
       NETLINK_ROUTE.

       tab(:);  l  s  l  l.   Standard  Flag  bits in nlmsg_flags
       NLM_F_REQUEST:set on all request  messages  NLM_F_MULTI:T{
       the  message  is part of a multipart message terminated by
       NLMSG_DONE T} NLM_F_ACK:reply with  an  acknowledgment  on
       success NLM_F_ECHO:echo this request

       tab(:);  l  s  l l.  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.
       NLM_F_DUMP:not documented yet.

       tab(:);  l  s  l l.  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.

       Note  that  NLM_F_ATOMIC  requires  CAP_NET_ADMIN or super
       user rights.



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 process owning the destination
       socket,  or  0  if  the  destination  is  in  the  kernel.
       nl_groups  is  a  bitmask  with  every  bit representing a
       netlink group number.




BUGS

       This man page is not complete.





Linux Man Page             27 Apr 1999                          3





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



NOTES

       It is often better to use netlink via libnetlink than  via
       the low level kernel interface.



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 obsolete interface is not described here.



SEE ALSO

       cmsg(3), rtnetlink(7), netlink(3).

       ftp://ftp.inr.ac.ru/ip-routing/iproute2* for libnetlink







































Linux Man Page             27 Apr 1999                          4