userspace-api/netlink/intro.rst

1 .. SPDX-License-Identifier: BSD-3-Clause
8 It aims to replace fixed-format C structures as supplied
12 To achieve this Netlink uses a minimal fixed-format metadata header
27 .. code-block:: c
39 .. code-block:: c
52 .. code-block:: c
69 The first two arguments of the socket() call require little explanation -
76 --------------------------
82 file, they include among others - general networking (NETLINK_ROUTE),
100 In addition to the Netlink fixed metadata header each Netlink protocol
101 defines its own fixed metadata header. (Similarly to how network
102 headers stack - Ethernet > IP > TCP we have Netlink > Generic N. > Family.)
105 by a protocol-specific header. In case of Generic Netlink the protocol
106 header is struct genlmsghdr.
110 .. code-block:: c
115 	__u16	nlmsg_flags;	/* Flags - request or dump */
133 Note that the first 16 values (0 - 15) of this field are reserved for
139  - performing a single action (``do``);
140  - dumping information (``dump``);
141  - getting asynchronous notifications (``multicast``).
152  - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK``
153  - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | NLM_F_DUMP``
174 ---------------------
183  - ``NLMSG_NOOP`` - ignore the message, not used in practice;
184  - ``NLMSG_ERROR`` - carries the return code of an operation;
185  - ``NLMSG_DONE`` - marks the end of a dump;
186  - ``NLMSG_OVERRUN`` - socket buffer has overflown, not used to date.
191 with ``NLMSG_ERROR`` if there is no error. To avoid having to special-case
196   ----------------------------------------------
197   | struct nlmsghdr - response header          |
198   ----------------------------------------------
200   ----------------------------------------------
201   | struct nlmsghdr - original request header |
202   ----------------------------------------------
204   ----------------------------------------------
206   ----------------------------------------------
211 to match requests to responses or re-parse the request to dump it into
229   ----------------------------------------------
230   | struct nlmsghdr - response header          |
231   ----------------------------------------------
233   ----------------------------------------------
235   ----------------------------------------------
239 implementation-specific and may also be absent.
244 -----------------------
284 and :c:member:`nlattr.nla_len`) always *include* the header.
292   /* Message #1 - reply */
330   /* Message #2 - the ACK */
340   struct nlmsghdr: /* Copy of the request header as we sent it */
352 families, selecting the recipient family on message-by-message basis using
358 ------------
388 ----------------
392 (without impacting the fast-paths updating them).
400 -------------
417 ---------
434 This sort of communication is utilized in UMH (User Mode Helper)-like
439 -----------------------
442 to user space. This is a unidirectional form of communication (kernel ->
501 .. code-block:: c
518 -------------
525 of the recvmsg() system call, *not* a Netlink header).
554 --------
565     header (struct nlmsghdr) in a message as a "Family Header"
575 ---------------
591 ------------------
602 Fixed metadata and structures
603 -----------------------------
605 Classic Netlink made liberal use of fixed-format structures within
616 -------------
624 Each object would also have its own fixed metadata shared by all request
633 -----------------
641 Other request-type-specific flags
642 ---------------------------------
649 For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH`` are combined into
652 For ``DEL`` - ``NLM_F_NONREC`` is only used by nftables and ``NLM_F_BULK``
665 A comment in the main Netlink uAPI header states::
681 with it (e.g. multiple next-hop objects for a route) the new object should be
687 .. kernel-doc:: include/uapi/linux/netlink.h