Lines Matching +full:kernel +full:- +full:family
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
32 in both directions (to and from the kernel). The operations are still
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),
87 implementing the kernel side of the interface.
92 more Classic Netlink protocols to the kernel.
94 the Linux kernel (or another of the 20 subsystems using Classic
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
110 .. code-block:: c
114 __u16 nlmsg_type; /* Generic Netlink Family (subsystem) ID */
115 __u16 nlmsg_flags; /* Flags - request or dump */
120 __u8 cmd; /* Command, as defined by the Family */
132 information on how to find the Family ID of the subsystem of interest.)
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``).
147 Asynchronous notifications are sent by the kernel and received by
152 - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK``
153 - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | NLM_F_DUMP``
163 This field can be set to ``0`` when talking to the kernel.
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
218 from the kernel is rather wasteful. The absence of request payload
229 ----------------------------------------------
230 | struct nlmsghdr - response header |
231 ----------------------------------------------
233 ----------------------------------------------
235 ----------------------------------------------
239 implementation-specific and may also be absent.
243 Resolving the Family ID
244 -----------------------
246 This section explains how to find the Family ID of a subsystem.
251 Family ID (``GENL_ID_CTRL`` which is equal to ``NLMSG_MIN_TYPE``).
252 The Generic Netlink family implements a command used to find out information
255 To get information about the Generic Netlink family named for example
257 socket. The message should target the Generic Netlink Family (1), be a
259 call would make the kernel respond with information about *all* the families
260 it knows about. Last but not least the name of the family in question has
289 If the family is found kernel will reply with two messages, the response
290 with all the information about the family::
292 /* Message #1 - reply */
316 __u16: 123 /* The Family ID we are after */
330 /* Message #2 - the ACK */
351 family. A socket can be used to exchange messages with many different
352 families, selecting the recipient family on message-by-message basis using
358 ------------
388 ----------------
390 Some of the data structures kernel uses for storing objects make
392 (without impacting the fast-paths updating them).
394 Kernel may set the ``NLM_F_DUMP_INTR`` flag on any message in a dump
400 -------------
402 The basic introspection abilities are enabled by access to the Family
404 the Generic Netlink family, including which operations are supported
405 by the kernel and what attributes the kernel understands.
406 Family information includes the highest ID of an attribute kernel can parse,
408 about supported attributes, including ranges of values the kernel accepts.
410 Querying family information is useful in cases when user space needs
411 to make sure that the kernel has support for a feature before issuing
417 ---------
422 kernel will automatically assign it the ID equal to its Process ID
429 The field is still used today in rare cases when kernel needs to send
431 its socket with a specific PID, it then communicates its PID to the kernel.
432 This way the kernel can reach the specific user space process.
434 This sort of communication is utilized in UMH (User Mode Helper)-like
435 scenarios when kernel needs to trigger user space processing or ask user
439 -----------------------
442 to user space. This is a unidirectional form of communication (kernel ->
446 For example the Generic Netlink family itself defines a set of multicast
447 notifications about registered families. When a new family is added the
473 __u16: 123 /* The Family ID we are after */
490 increasing notification sequence number maintained by the family.
493 notification group. Much like the Family ID, the Group ID for a given
494 multicast group is dynamic and can be found inside the Family information.
497 the groups family.
501 .. code-block:: c
513 and sending requests to the kernel. The asynchronous nature of notifications
518 -------------
549 Most of the concepts and examples here refer to the ``NETLINK_ROUTE`` family,
551 Real documentation of that family, deserves a chapter (or a book) of its own.
554 --------
563 1. AF_NETLINK is a bona fide socket protocol family
565 header (struct nlmsghdr) in a message as a "Family Header"
566 3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows
569 Note that the Generic Netlink Family IDs are in a different "ID space"
575 ---------------
578 in ``NETLINK_ROUTE``. It was needed because historically kernel did not
585 contain trailing data and requests that kernel rejects attributes with
586 type higher than largest attribute type known to the kernel.
591 ------------------
594 it would free the application from having to probe what kernel supports.
603 -----------------------------
605 Classic Netlink made liberal use of fixed-format structures within
616 -------------
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``
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