1 .. SPDX-License-Identifier: BSD-3-Clause 1 .. SPDX-License-Identifier: BSD-3-Clause
2 2
3 ======================= 3 =======================
4 Introduction to Netlink 4 Introduction to Netlink
5 ======================= 5 =======================
6 6
7 Netlink is often described as an ioctl() repla 7 Netlink is often described as an ioctl() replacement.
8 It aims to replace fixed-format C structures a 8 It aims to replace fixed-format C structures as supplied
9 to ioctl() with a format which allows an easy 9 to ioctl() with a format which allows an easy way to add
10 or extended the arguments. 10 or extended the arguments.
11 11
12 To achieve this Netlink uses a minimal fixed-f 12 To achieve this Netlink uses a minimal fixed-format metadata header
13 followed by multiple attributes in the TLV (ty 13 followed by multiple attributes in the TLV (type, length, value) format.
14 14
15 Unfortunately the protocol has evolved over th 15 Unfortunately the protocol has evolved over the years, in an organic
16 and undocumented fashion, making it hard to co 16 and undocumented fashion, making it hard to coherently explain.
17 To make the most practical sense this document 17 To make the most practical sense this document starts by describing
18 netlink as it is used today and dives into mor 18 netlink as it is used today and dives into more "historical" uses
19 in later sections. 19 in later sections.
20 20
21 Opening a socket 21 Opening a socket
22 ================ 22 ================
23 23
24 Netlink communication happens over sockets, a 24 Netlink communication happens over sockets, a socket needs to be
25 opened first: 25 opened first:
26 26
27 .. code-block:: c 27 .. code-block:: c
28 28
29 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GE 29 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC);
30 30
31 The use of sockets allows for a natural way of 31 The use of sockets allows for a natural way of exchanging information
32 in both directions (to and from the kernel). T 32 in both directions (to and from the kernel). The operations are still
33 performed synchronously when applications send 33 performed synchronously when applications send() the request but
34 a separate recv() system call is needed to rea 34 a separate recv() system call is needed to read the reply.
35 35
36 A very simplified flow of a Netlink "call" wil 36 A very simplified flow of a Netlink "call" will therefore look
37 something like: 37 something like:
38 38
39 .. code-block:: c 39 .. code-block:: c
40 40
41 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GE 41 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC);
42 42
43 /* format the request */ 43 /* format the request */
44 send(fd, &request, sizeof(request)); 44 send(fd, &request, sizeof(request));
45 n = recv(fd, &response, RSP_BUFFER_SIZE); 45 n = recv(fd, &response, RSP_BUFFER_SIZE);
46 /* interpret the response */ 46 /* interpret the response */
47 47
48 Netlink also provides natural support for "dum 48 Netlink also provides natural support for "dumping", i.e. communicating
49 to user space all objects of a certain type (e 49 to user space all objects of a certain type (e.g. dumping all network
50 interfaces). 50 interfaces).
51 51
52 .. code-block:: c 52 .. code-block:: c
53 53
54 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GE 54 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC);
55 55
56 /* format the dump request */ 56 /* format the dump request */
57 send(fd, &request, sizeof(request)); 57 send(fd, &request, sizeof(request));
58 while (1) { 58 while (1) {
59 n = recv(fd, &buffer, RSP_BUFFER_SIZE); 59 n = recv(fd, &buffer, RSP_BUFFER_SIZE);
60 /* one recv() call can read multiple messa 60 /* one recv() call can read multiple messages, hence the loop below */
61 for (nl_msg in buffer) { 61 for (nl_msg in buffer) {
62 if (nl_msg.nlmsg_type == NLMSG_DONE) 62 if (nl_msg.nlmsg_type == NLMSG_DONE)
63 goto dump_finished; 63 goto dump_finished;
64 /* process the object */ 64 /* process the object */
65 } 65 }
66 } 66 }
67 dump_finished: 67 dump_finished:
68 68
69 The first two arguments of the socket() call r 69 The first two arguments of the socket() call require little explanation -
70 it is opening a Netlink socket, with all heade 70 it is opening a Netlink socket, with all headers provided by the user
71 (hence NETLINK, RAW). The last argument is the 71 (hence NETLINK, RAW). The last argument is the protocol within Netlink.
72 This field used to identify the subsystem with 72 This field used to identify the subsystem with which the socket will
73 communicate. 73 communicate.
74 74
75 Classic vs Generic Netlink 75 Classic vs Generic Netlink
76 -------------------------- 76 --------------------------
77 77
78 Initial implementation of Netlink depended on 78 Initial implementation of Netlink depended on a static allocation
79 of IDs to subsystems and provided little suppo 79 of IDs to subsystems and provided little supporting infrastructure.
80 Let us refer to those protocols collectively a 80 Let us refer to those protocols collectively as **Classic Netlink**.
81 The list of them is defined on top of the ``in 81 The list of them is defined on top of the ``include/uapi/linux/netlink.h``
82 file, they include among others - general netw 82 file, they include among others - general networking (NETLINK_ROUTE),
83 iSCSI (NETLINK_ISCSI), and audit (NETLINK_AUDI 83 iSCSI (NETLINK_ISCSI), and audit (NETLINK_AUDIT).
84 84
85 **Generic Netlink** (introduced in 2005) allow 85 **Generic Netlink** (introduced in 2005) allows for dynamic registration of
86 subsystems (and subsystem ID allocation), intr 86 subsystems (and subsystem ID allocation), introspection and simplifies
87 implementing the kernel side of the interface. 87 implementing the kernel side of the interface.
88 88
89 The following section describes how to use Gen 89 The following section describes how to use Generic Netlink, as the
90 number of subsystems using Generic Netlink out 90 number of subsystems using Generic Netlink outnumbers the older
91 protocols by an order of magnitude. There are 91 protocols by an order of magnitude. There are also no plans for adding
92 more Classic Netlink protocols to the kernel. 92 more Classic Netlink protocols to the kernel.
93 Basic information on how communicating with co 93 Basic information on how communicating with core networking parts of
94 the Linux kernel (or another of the 20 subsyst 94 the Linux kernel (or another of the 20 subsystems using Classic
95 Netlink) differs from Generic Netlink is provi 95 Netlink) differs from Generic Netlink is provided later in this document.
96 96
97 Generic Netlink 97 Generic Netlink
98 =============== 98 ===============
99 99
100 In addition to the Netlink fixed metadata head 100 In addition to the Netlink fixed metadata header each Netlink protocol
101 defines its own fixed metadata header. (Simila 101 defines its own fixed metadata header. (Similarly to how network
102 headers stack - Ethernet > IP > TCP we have Ne 102 headers stack - Ethernet > IP > TCP we have Netlink > Generic N. > Family.)
103 103
104 A Netlink message always starts with struct nl 104 A Netlink message always starts with struct nlmsghdr, which is followed
105 by a protocol-specific header. In case of Gene 105 by a protocol-specific header. In case of Generic Netlink the protocol
106 header is struct genlmsghdr. 106 header is struct genlmsghdr.
107 107
108 The practical meaning of the fields in case of 108 The practical meaning of the fields in case of Generic Netlink is as follows:
109 109
110 .. code-block:: c 110 .. code-block:: c
111 111
112 struct nlmsghdr { 112 struct nlmsghdr {
113 __u32 nlmsg_len; /* Length of m 113 __u32 nlmsg_len; /* Length of message including headers */
114 __u16 nlmsg_type; /* Generic Net 114 __u16 nlmsg_type; /* Generic Netlink Family (subsystem) ID */
115 __u16 nlmsg_flags; /* Flags - req 115 __u16 nlmsg_flags; /* Flags - request or dump */
116 __u32 nlmsg_seq; /* Sequence nu 116 __u32 nlmsg_seq; /* Sequence number */
117 __u32 nlmsg_pid; /* Port ID, se 117 __u32 nlmsg_pid; /* Port ID, set to 0 */
118 }; 118 };
119 struct genlmsghdr { 119 struct genlmsghdr {
120 __u8 cmd; /* Command, as 120 __u8 cmd; /* Command, as defined by the Family */
121 __u8 version; /* Irrelevant, 121 __u8 version; /* Irrelevant, set to 1 */
122 __u16 reserved; /* Reserved, s 122 __u16 reserved; /* Reserved, set to 0 */
123 }; 123 };
124 /* TLV attributes follow... */ 124 /* TLV attributes follow... */
125 125
126 In Classic Netlink :c:member:`nlmsghdr.nlmsg_t 126 In Classic Netlink :c:member:`nlmsghdr.nlmsg_type` used to identify
127 which operation within the subsystem the messa 127 which operation within the subsystem the message was referring to
128 (e.g. get information about a netdev). Generic 128 (e.g. get information about a netdev). Generic Netlink needs to mux
129 multiple subsystems in a single protocol so it 129 multiple subsystems in a single protocol so it uses this field to
130 identify the subsystem, and :c:member:`genlmsg 130 identify the subsystem, and :c:member:`genlmsghdr.cmd` identifies
131 the operation instead. (See :ref:`res_fam` for 131 the operation instead. (See :ref:`res_fam` for
132 information on how to find the Family ID of th 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 133 Note that the first 16 values (0 - 15) of this field are reserved for
134 control messages both in Classic Netlink and G 134 control messages both in Classic Netlink and Generic Netlink.
135 See :ref:`nl_msg_type` for more details. 135 See :ref:`nl_msg_type` for more details.
136 136
137 There are 3 usual types of message exchanges o 137 There are 3 usual types of message exchanges on a Netlink socket:
138 138
139 - performing a single action (``do``); 139 - performing a single action (``do``);
140 - dumping information (``dump``); 140 - dumping information (``dump``);
141 - getting asynchronous notifications (``multi 141 - getting asynchronous notifications (``multicast``).
142 142
143 Classic Netlink is very flexible and presumabl 143 Classic Netlink is very flexible and presumably allows other types
144 of exchanges to happen, but in practice those 144 of exchanges to happen, but in practice those are the three that get
145 used. 145 used.
146 146
147 Asynchronous notifications are sent by the ker 147 Asynchronous notifications are sent by the kernel and received by
148 the user sockets which subscribed to them. ``d 148 the user sockets which subscribed to them. ``do`` and ``dump`` requests
149 are initiated by the user. :c:member:`nlmsghdr 149 are initiated by the user. :c:member:`nlmsghdr.nlmsg_flags` should
150 be set as follows: 150 be set as follows:
151 151
152 - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK`` 152 - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK``
153 - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | 153 - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | NLM_F_DUMP``
154 154
155 :c:member:`nlmsghdr.nlmsg_seq` should be a set 155 :c:member:`nlmsghdr.nlmsg_seq` should be a set to a monotonically
156 increasing value. The value gets echoed back i 156 increasing value. The value gets echoed back in responses and doesn't
157 matter in practice, but setting it to an incre 157 matter in practice, but setting it to an increasing value for each
158 message sent is considered good hygiene. The p 158 message sent is considered good hygiene. The purpose of the field is
159 matching responses to requests. Asynchronous n 159 matching responses to requests. Asynchronous notifications will have
160 :c:member:`nlmsghdr.nlmsg_seq` of ``0``. 160 :c:member:`nlmsghdr.nlmsg_seq` of ``0``.
161 161
162 :c:member:`nlmsghdr.nlmsg_pid` is the Netlink 162 :c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address.
163 This field can be set to ``0`` when talking to 163 This field can be set to ``0`` when talking to the kernel.
164 See :ref:`nlmsg_pid` for the (uncommon) uses o 164 See :ref:`nlmsg_pid` for the (uncommon) uses of the field.
165 165
166 The expected use for :c:member:`genlmsghdr.ver 166 The expected use for :c:member:`genlmsghdr.version` was to allow
167 versioning of the APIs provided by the subsyst 167 versioning of the APIs provided by the subsystems. No subsystem to
168 date made significant use of this field, so se 168 date made significant use of this field, so setting it to ``1`` seems
169 like a safe bet. 169 like a safe bet.
170 170
171 .. _nl_msg_type: 171 .. _nl_msg_type:
172 172
173 Netlink message types 173 Netlink message types
174 --------------------- 174 ---------------------
175 175
176 As previously mentioned :c:member:`nlmsghdr.nl 176 As previously mentioned :c:member:`nlmsghdr.nlmsg_type` carries
177 protocol specific values but the first 16 iden 177 protocol specific values but the first 16 identifiers are reserved
178 (first subsystem specific message type should 178 (first subsystem specific message type should be equal to
179 ``NLMSG_MIN_TYPE`` which is ``0x10``). 179 ``NLMSG_MIN_TYPE`` which is ``0x10``).
180 180
181 There are only 4 Netlink control messages defi 181 There are only 4 Netlink control messages defined:
182 182
183 - ``NLMSG_NOOP`` - ignore the message, not us 183 - ``NLMSG_NOOP`` - ignore the message, not used in practice;
184 - ``NLMSG_ERROR`` - carries the return code o 184 - ``NLMSG_ERROR`` - carries the return code of an operation;
185 - ``NLMSG_DONE`` - marks the end of a dump; 185 - ``NLMSG_DONE`` - marks the end of a dump;
186 - ``NLMSG_OVERRUN`` - socket buffer has overf 186 - ``NLMSG_OVERRUN`` - socket buffer has overflown, not used to date.
187 187
188 ``NLMSG_ERROR`` and ``NLMSG_DONE`` are of prac 188 ``NLMSG_ERROR`` and ``NLMSG_DONE`` are of practical importance.
189 They carry return codes for operations. Note t 189 They carry return codes for operations. Note that unless
190 the ``NLM_F_ACK`` flag is set on the request N 190 the ``NLM_F_ACK`` flag is set on the request Netlink will not respond
191 with ``NLMSG_ERROR`` if there is no error. To 191 with ``NLMSG_ERROR`` if there is no error. To avoid having to special-case
192 this quirk it is recommended to always set ``N 192 this quirk it is recommended to always set ``NLM_F_ACK``.
193 193
194 The format of ``NLMSG_ERROR`` is described by 194 The format of ``NLMSG_ERROR`` is described by struct nlmsgerr::
195 195
196 -------------------------------------------- 196 ----------------------------------------------
197 | struct nlmsghdr - response header 197 | struct nlmsghdr - response header |
198 -------------------------------------------- 198 ----------------------------------------------
199 | int error 199 | int error |
200 -------------------------------------------- 200 ----------------------------------------------
201 | struct nlmsghdr - original request header 201 | struct nlmsghdr - original request header |
202 -------------------------------------------- 202 ----------------------------------------------
203 | ** optionally (1) payload of the request 203 | ** optionally (1) payload of the request |
204 -------------------------------------------- 204 ----------------------------------------------
205 | ** optionally (2) extended ACK 205 | ** optionally (2) extended ACK |
206 -------------------------------------------- 206 ----------------------------------------------
207 207
208 There are two instances of struct nlmsghdr her 208 There are two instances of struct nlmsghdr here, first of the response
209 and second of the request. ``NLMSG_ERROR`` car 209 and second of the request. ``NLMSG_ERROR`` carries the information about
210 the request which led to the error. This could 210 the request which led to the error. This could be useful when trying
211 to match requests to responses or re-parse the 211 to match requests to responses or re-parse the request to dump it into
212 logs. 212 logs.
213 213
214 The payload of the request is not echoed in me 214 The payload of the request is not echoed in messages reporting success
215 (``error == 0``) or if ``NETLINK_CAP_ACK`` set 215 (``error == 0``) or if ``NETLINK_CAP_ACK`` setsockopt() was set.
216 The latter is common 216 The latter is common
217 and perhaps recommended as having to read a co 217 and perhaps recommended as having to read a copy of every request back
218 from the kernel is rather wasteful. The absenc 218 from the kernel is rather wasteful. The absence of request payload
219 is indicated by ``NLM_F_CAPPED`` in :c:member: 219 is indicated by ``NLM_F_CAPPED`` in :c:member:`nlmsghdr.nlmsg_flags`.
220 220
221 The second optional element of ``NLMSG_ERROR`` 221 The second optional element of ``NLMSG_ERROR`` are the extended ACK
222 attributes. See :ref:`ext_ack` for more detail 222 attributes. See :ref:`ext_ack` for more details. The presence
223 of extended ACK is indicated by ``NLM_F_ACK_TL 223 of extended ACK is indicated by ``NLM_F_ACK_TLVS`` in
224 :c:member:`nlmsghdr.nlmsg_flags`. 224 :c:member:`nlmsghdr.nlmsg_flags`.
225 225
226 ``NLMSG_DONE`` is simpler, the request is neve 226 ``NLMSG_DONE`` is simpler, the request is never echoed but the extended
227 ACK attributes may be present:: 227 ACK attributes may be present::
228 228
229 -------------------------------------------- 229 ----------------------------------------------
230 | struct nlmsghdr - response header 230 | struct nlmsghdr - response header |
231 -------------------------------------------- 231 ----------------------------------------------
232 | int error 232 | int error |
233 -------------------------------------------- 233 ----------------------------------------------
234 | ** optionally extended ACK 234 | ** optionally extended ACK |
235 -------------------------------------------- 235 ----------------------------------------------
236 236
237 Note that some implementations may issue custo <<
238 in reply to ``do`` action requests. In that ca <<
239 implementation-specific and may also be absent <<
240 <<
241 .. _res_fam: 237 .. _res_fam:
242 238
243 Resolving the Family ID 239 Resolving the Family ID
244 ----------------------- 240 -----------------------
245 241
246 This section explains how to find the Family I 242 This section explains how to find the Family ID of a subsystem.
247 It also serves as an example of Generic Netlin 243 It also serves as an example of Generic Netlink communication.
248 244
249 Generic Netlink is itself a subsystem exposed 245 Generic Netlink is itself a subsystem exposed via the Generic Netlink API.
250 To avoid a circular dependency Generic Netlink 246 To avoid a circular dependency Generic Netlink has a statically allocated
251 Family ID (``GENL_ID_CTRL`` which is equal to 247 Family ID (``GENL_ID_CTRL`` which is equal to ``NLMSG_MIN_TYPE``).
252 The Generic Netlink family implements a comman 248 The Generic Netlink family implements a command used to find out information
253 about other families (``CTRL_CMD_GETFAMILY``). 249 about other families (``CTRL_CMD_GETFAMILY``).
254 250
255 To get information about the Generic Netlink f 251 To get information about the Generic Netlink family named for example
256 ``"test1"`` we need to send a message on the p 252 ``"test1"`` we need to send a message on the previously opened Generic Netlink
257 socket. The message should target the Generic 253 socket. The message should target the Generic Netlink Family (1), be a
258 ``do`` (2) call to ``CTRL_CMD_GETFAMILY`` (3). 254 ``do`` (2) call to ``CTRL_CMD_GETFAMILY`` (3). A ``dump`` version of this
259 call would make the kernel respond with inform 255 call would make the kernel respond with information about *all* the families
260 it knows about. Last but not least the name of 256 it knows about. Last but not least the name of the family in question has
261 to be specified (4) as an attribute with the a 257 to be specified (4) as an attribute with the appropriate type::
262 258
263 struct nlmsghdr: 259 struct nlmsghdr:
264 __u32 nlmsg_len: 32 260 __u32 nlmsg_len: 32
265 __u16 nlmsg_type: GENL_ID_CTRL 261 __u16 nlmsg_type: GENL_ID_CTRL // (1)
266 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ 262 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK // (2)
267 __u32 nlmsg_seq: 1 263 __u32 nlmsg_seq: 1
268 __u32 nlmsg_pid: 0 264 __u32 nlmsg_pid: 0
269 265
270 struct genlmsghdr: 266 struct genlmsghdr:
271 __u8 cmd: CTRL_CMD_GETFAMILY 267 __u8 cmd: CTRL_CMD_GETFAMILY // (3)
272 __u8 version: 2 /* or 1, doesn't mat 268 __u8 version: 2 /* or 1, doesn't matter */
273 __u16 reserved: 0 269 __u16 reserved: 0
274 270
275 struct nlattr: 271 struct nlattr: // (4)
276 __u16 nla_len: 10 272 __u16 nla_len: 10
277 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 273 __u16 nla_type: CTRL_ATTR_FAMILY_NAME
278 char data: test1\0 274 char data: test1\0
279 275
280 (padding:) 276 (padding:)
281 char data: \0\0 277 char data: \0\0
282 278
283 The length fields in Netlink (:c:member:`nlmsg 279 The length fields in Netlink (:c:member:`nlmsghdr.nlmsg_len`
284 and :c:member:`nlattr.nla_len`) always *includ 280 and :c:member:`nlattr.nla_len`) always *include* the header.
285 Attribute headers in netlink must be aligned t 281 Attribute headers in netlink must be aligned to 4 bytes from the start
286 of the message, hence the extra ``\0\0`` after 282 of the message, hence the extra ``\0\0`` after ``CTRL_ATTR_FAMILY_NAME``.
287 The attribute lengths *exclude* the padding. 283 The attribute lengths *exclude* the padding.
288 284
289 If the family is found kernel will reply with 285 If the family is found kernel will reply with two messages, the response
290 with all the information about the family:: 286 with all the information about the family::
291 287
292 /* Message #1 - reply */ 288 /* Message #1 - reply */
293 struct nlmsghdr: 289 struct nlmsghdr:
294 __u32 nlmsg_len: 136 290 __u32 nlmsg_len: 136
295 __u16 nlmsg_type: GENL_ID_CTRL 291 __u16 nlmsg_type: GENL_ID_CTRL
296 __u16 nlmsg_flags: 0 292 __u16 nlmsg_flags: 0
297 __u32 nlmsg_seq: 1 /* echoed from ou 293 __u32 nlmsg_seq: 1 /* echoed from our request */
298 __u32 nlmsg_pid: 5831 /* The PID of our 294 __u32 nlmsg_pid: 5831 /* The PID of our user space process */
299 295
300 struct genlmsghdr: 296 struct genlmsghdr:
301 __u8 cmd: CTRL_CMD_GETFAMILY 297 __u8 cmd: CTRL_CMD_GETFAMILY
302 __u8 version: 2 298 __u8 version: 2
303 __u16 reserved: 0 299 __u16 reserved: 0
304 300
305 struct nlattr: 301 struct nlattr:
306 __u16 nla_len: 10 302 __u16 nla_len: 10
307 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 303 __u16 nla_type: CTRL_ATTR_FAMILY_NAME
308 char data: test1\0 304 char data: test1\0
309 305
310 (padding:) 306 (padding:)
311 data: \0\0 307 data: \0\0
312 308
313 struct nlattr: 309 struct nlattr:
314 __u16 nla_len: 6 310 __u16 nla_len: 6
315 __u16 nla_type: CTRL_ATTR_FAMILY_ID 311 __u16 nla_type: CTRL_ATTR_FAMILY_ID
316 __u16: 123 /* The Family ID 312 __u16: 123 /* The Family ID we are after */
317 313
318 (padding:) 314 (padding:)
319 char data: \0\0 315 char data: \0\0
320 316
321 struct nlattr: 317 struct nlattr:
322 __u16 nla_len: 9 318 __u16 nla_len: 9
323 __u16 nla_type: CTRL_ATTR_FAMILY_VERSI 319 __u16 nla_type: CTRL_ATTR_FAMILY_VERSION
324 __u16: 1 320 __u16: 1
325 321
326 /* ... etc, more attributes will follow. */ 322 /* ... etc, more attributes will follow. */
327 323
328 And the error code (success) since ``NLM_F_ACK 324 And the error code (success) since ``NLM_F_ACK`` had been set on the request::
329 325
330 /* Message #2 - the ACK */ 326 /* Message #2 - the ACK */
331 struct nlmsghdr: 327 struct nlmsghdr:
332 __u32 nlmsg_len: 36 328 __u32 nlmsg_len: 36
333 __u16 nlmsg_type: NLMSG_ERROR 329 __u16 nlmsg_type: NLMSG_ERROR
334 __u16 nlmsg_flags: NLM_F_CAPPED /* There 330 __u16 nlmsg_flags: NLM_F_CAPPED /* There won't be a payload */
335 __u32 nlmsg_seq: 1 /* echoed from ou 331 __u32 nlmsg_seq: 1 /* echoed from our request */
336 __u32 nlmsg_pid: 5831 /* The PID of our 332 __u32 nlmsg_pid: 5831 /* The PID of our user space process */
337 333
338 int error: 0 334 int error: 0
339 335
340 struct nlmsghdr: /* Copy of the request head 336 struct nlmsghdr: /* Copy of the request header as we sent it */
341 __u32 nlmsg_len: 32 337 __u32 nlmsg_len: 32
342 __u16 nlmsg_type: GENL_ID_CTRL 338 __u16 nlmsg_type: GENL_ID_CTRL
343 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ 339 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK
344 __u32 nlmsg_seq: 1 340 __u32 nlmsg_seq: 1
345 __u32 nlmsg_pid: 0 341 __u32 nlmsg_pid: 0
346 342
347 The order of attributes (struct nlattr) is not 343 The order of attributes (struct nlattr) is not guaranteed so the user
348 has to walk the attributes and parse them. 344 has to walk the attributes and parse them.
349 345
350 Note that Generic Netlink sockets are not asso 346 Note that Generic Netlink sockets are not associated or bound to a single
351 family. A socket can be used to exchange messa 347 family. A socket can be used to exchange messages with many different
352 families, selecting the recipient family on me 348 families, selecting the recipient family on message-by-message basis using
353 the :c:member:`nlmsghdr.nlmsg_type` field. 349 the :c:member:`nlmsghdr.nlmsg_type` field.
354 350
355 .. _ext_ack: 351 .. _ext_ack:
356 352
357 Extended ACK 353 Extended ACK
358 ------------ 354 ------------
359 355
360 Extended ACK controls reporting of additional 356 Extended ACK controls reporting of additional error/warning TLVs
361 in ``NLMSG_ERROR`` and ``NLMSG_DONE`` messages 357 in ``NLMSG_ERROR`` and ``NLMSG_DONE`` messages. To maintain backward
362 compatibility this feature has to be explicitl 358 compatibility this feature has to be explicitly enabled by setting
363 the ``NETLINK_EXT_ACK`` setsockopt() to ``1``. 359 the ``NETLINK_EXT_ACK`` setsockopt() to ``1``.
364 360
365 Types of extended ack attributes are defined i 361 Types of extended ack attributes are defined in enum nlmsgerr_attrs.
366 The most commonly used attributes are ``NLMSGE 362 The most commonly used attributes are ``NLMSGERR_ATTR_MSG``,
367 ``NLMSGERR_ATTR_OFFS`` and ``NLMSGERR_ATTR_MIS 363 ``NLMSGERR_ATTR_OFFS`` and ``NLMSGERR_ATTR_MISS_*``.
368 364
369 ``NLMSGERR_ATTR_MSG`` carries a message in Eng 365 ``NLMSGERR_ATTR_MSG`` carries a message in English describing
370 the encountered problem. These messages are fa 366 the encountered problem. These messages are far more detailed
371 than what can be expressed thru standard UNIX 367 than what can be expressed thru standard UNIX error codes.
372 368
373 ``NLMSGERR_ATTR_OFFS`` points to the attribute 369 ``NLMSGERR_ATTR_OFFS`` points to the attribute which caused the problem.
374 370
375 ``NLMSGERR_ATTR_MISS_TYPE`` and ``NLMSGERR_ATT 371 ``NLMSGERR_ATTR_MISS_TYPE`` and ``NLMSGERR_ATTR_MISS_NEST``
376 inform about a missing attribute. 372 inform about a missing attribute.
377 373
378 Extended ACKs can be reported on errors as wel 374 Extended ACKs can be reported on errors as well as in case of success.
379 The latter should be treated as a warning. 375 The latter should be treated as a warning.
380 376
381 Extended ACKs greatly improve the usability of 377 Extended ACKs greatly improve the usability of Netlink and should
382 always be enabled, appropriately parsed and re 378 always be enabled, appropriately parsed and reported to the user.
383 379
384 Advanced topics 380 Advanced topics
385 =============== 381 ===============
386 382
387 Dump consistency 383 Dump consistency
388 ---------------- 384 ----------------
389 385
390 Some of the data structures kernel uses for st 386 Some of the data structures kernel uses for storing objects make
391 it hard to provide an atomic snapshot of all t 387 it hard to provide an atomic snapshot of all the objects in a dump
392 (without impacting the fast-paths updating the 388 (without impacting the fast-paths updating them).
393 389
394 Kernel may set the ``NLM_F_DUMP_INTR`` flag on 390 Kernel may set the ``NLM_F_DUMP_INTR`` flag on any message in a dump
395 (including the ``NLMSG_DONE`` message) if the 391 (including the ``NLMSG_DONE`` message) if the dump was interrupted and
396 may be inconsistent (e.g. missing objects). Us 392 may be inconsistent (e.g. missing objects). User space should retry
397 the dump if it sees the flag set. 393 the dump if it sees the flag set.
398 394
399 Introspection 395 Introspection
400 ------------- 396 -------------
401 397
402 The basic introspection abilities are enabled 398 The basic introspection abilities are enabled by access to the Family
403 object as reported in :ref:`res_fam`. User can 399 object as reported in :ref:`res_fam`. User can query information about
404 the Generic Netlink family, including which op 400 the Generic Netlink family, including which operations are supported
405 by the kernel and what attributes the kernel u 401 by the kernel and what attributes the kernel understands.
406 Family information includes the highest ID of 402 Family information includes the highest ID of an attribute kernel can parse,
407 a separate command (``CTRL_CMD_GETPOLICY``) pr 403 a separate command (``CTRL_CMD_GETPOLICY``) provides detailed information
408 about supported attributes, including ranges o 404 about supported attributes, including ranges of values the kernel accepts.
409 405
410 Querying family information is useful in cases 406 Querying family information is useful in cases when user space needs
411 to make sure that the kernel has support for a 407 to make sure that the kernel has support for a feature before issuing
412 a request. 408 a request.
413 409
414 .. _nlmsg_pid: 410 .. _nlmsg_pid:
415 411
416 nlmsg_pid 412 nlmsg_pid
417 --------- 413 ---------
418 414
419 :c:member:`nlmsghdr.nlmsg_pid` is the Netlink 415 :c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address.
420 It is referred to as Port ID, sometimes Proces 416 It is referred to as Port ID, sometimes Process ID because for historical
421 reasons if the application does not select (bi 417 reasons if the application does not select (bind() to) an explicit Port ID
422 kernel will automatically assign it the ID equ 418 kernel will automatically assign it the ID equal to its Process ID
423 (as reported by the getpid() system call). 419 (as reported by the getpid() system call).
424 420
425 Similarly to the bind() semantics of the TCP/I 421 Similarly to the bind() semantics of the TCP/IP network protocols the value
426 of zero means "assign automatically", hence it 422 of zero means "assign automatically", hence it is common for applications
427 to leave the :c:member:`nlmsghdr.nlmsg_pid` fi 423 to leave the :c:member:`nlmsghdr.nlmsg_pid` field initialized to ``0``.
428 424
429 The field is still used today in rare cases wh 425 The field is still used today in rare cases when kernel needs to send
430 a unicast notification. User space application 426 a unicast notification. User space application can use bind() to associate
431 its socket with a specific PID, it then commun 427 its socket with a specific PID, it then communicates its PID to the kernel.
432 This way the kernel can reach the specific use 428 This way the kernel can reach the specific user space process.
433 429
434 This sort of communication is utilized in UMH 430 This sort of communication is utilized in UMH (User Mode Helper)-like
435 scenarios when kernel needs to trigger user sp 431 scenarios when kernel needs to trigger user space processing or ask user
436 space for a policy decision. 432 space for a policy decision.
437 433
438 Multicast notifications 434 Multicast notifications
439 ----------------------- 435 -----------------------
440 436
441 One of the strengths of Netlink is the ability 437 One of the strengths of Netlink is the ability to send event notifications
442 to user space. This is a unidirectional form o 438 to user space. This is a unidirectional form of communication (kernel ->
443 user) and does not involve any control message 439 user) and does not involve any control messages like ``NLMSG_ERROR`` or
444 ``NLMSG_DONE``. 440 ``NLMSG_DONE``.
445 441
446 For example the Generic Netlink family itself 442 For example the Generic Netlink family itself defines a set of multicast
447 notifications about registered families. When 443 notifications about registered families. When a new family is added the
448 sockets subscribed to the notifications will g 444 sockets subscribed to the notifications will get the following message::
449 445
450 struct nlmsghdr: 446 struct nlmsghdr:
451 __u32 nlmsg_len: 136 447 __u32 nlmsg_len: 136
452 __u16 nlmsg_type: GENL_ID_CTRL 448 __u16 nlmsg_type: GENL_ID_CTRL
453 __u16 nlmsg_flags: 0 449 __u16 nlmsg_flags: 0
454 __u32 nlmsg_seq: 0 450 __u32 nlmsg_seq: 0
455 __u32 nlmsg_pid: 0 451 __u32 nlmsg_pid: 0
456 452
457 struct genlmsghdr: 453 struct genlmsghdr:
458 __u8 cmd: CTRL_CMD_NEWFAMILY 454 __u8 cmd: CTRL_CMD_NEWFAMILY
459 __u8 version: 2 455 __u8 version: 2
460 __u16 reserved: 0 456 __u16 reserved: 0
461 457
462 struct nlattr: 458 struct nlattr:
463 __u16 nla_len: 10 459 __u16 nla_len: 10
464 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 460 __u16 nla_type: CTRL_ATTR_FAMILY_NAME
465 char data: test1\0 461 char data: test1\0
466 462
467 (padding:) 463 (padding:)
468 data: \0\0 464 data: \0\0
469 465
470 struct nlattr: 466 struct nlattr:
471 __u16 nla_len: 6 467 __u16 nla_len: 6
472 __u16 nla_type: CTRL_ATTR_FAMILY_ID 468 __u16 nla_type: CTRL_ATTR_FAMILY_ID
473 __u16: 123 /* The Family ID 469 __u16: 123 /* The Family ID we are after */
474 470
475 (padding:) 471 (padding:)
476 char data: \0\0 472 char data: \0\0
477 473
478 struct nlattr: 474 struct nlattr:
479 __u16 nla_len: 9 475 __u16 nla_len: 9
480 __u16 nla_type: CTRL_ATTR_FAMILY_VERSI 476 __u16 nla_type: CTRL_ATTR_FAMILY_VERSION
481 __u16: 1 477 __u16: 1
482 478
483 /* ... etc, more attributes will follow. */ 479 /* ... etc, more attributes will follow. */
484 480
485 The notification contains the same information 481 The notification contains the same information as the response
486 to the ``CTRL_CMD_GETFAMILY`` request. 482 to the ``CTRL_CMD_GETFAMILY`` request.
487 483
488 The Netlink headers of the notification are mo 484 The Netlink headers of the notification are mostly 0 and irrelevant.
489 The :c:member:`nlmsghdr.nlmsg_seq` may be eith 485 The :c:member:`nlmsghdr.nlmsg_seq` may be either zero or a monotonically
490 increasing notification sequence number mainta 486 increasing notification sequence number maintained by the family.
491 487
492 To receive notifications the user socket must 488 To receive notifications the user socket must subscribe to the relevant
493 notification group. Much like the Family ID, t 489 notification group. Much like the Family ID, the Group ID for a given
494 multicast group is dynamic and can be found in 490 multicast group is dynamic and can be found inside the Family information.
495 The ``CTRL_ATTR_MCAST_GROUPS`` attribute conta 491 The ``CTRL_ATTR_MCAST_GROUPS`` attribute contains nests with names
496 (``CTRL_ATTR_MCAST_GRP_NAME``) and IDs (``CTRL 492 (``CTRL_ATTR_MCAST_GRP_NAME``) and IDs (``CTRL_ATTR_MCAST_GRP_ID``) of
497 the groups family. 493 the groups family.
498 494
499 Once the Group ID is known a setsockopt() call 495 Once the Group ID is known a setsockopt() call adds the socket to the group:
500 496
501 .. code-block:: c 497 .. code-block:: c
502 498
503 unsigned int group_id; 499 unsigned int group_id;
504 500
505 /* .. find the group ID... */ 501 /* .. find the group ID... */
506 502
507 setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMB 503 setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP,
508 &group_id, sizeof(group_id)); 504 &group_id, sizeof(group_id));
509 505
510 The socket will now receive notifications. 506 The socket will now receive notifications.
511 507
512 It is recommended to use separate sockets for 508 It is recommended to use separate sockets for receiving notifications
513 and sending requests to the kernel. The asynch 509 and sending requests to the kernel. The asynchronous nature of notifications
514 means that they may get mixed in with the resp 510 means that they may get mixed in with the responses making the message
515 handling much harder. 511 handling much harder.
516 512
517 Buffer sizing 513 Buffer sizing
518 ------------- 514 -------------
519 515
520 Netlink sockets are datagram sockets rather th 516 Netlink sockets are datagram sockets rather than stream sockets,
521 meaning that each message must be received in 517 meaning that each message must be received in its entirety by a single
522 recv()/recvmsg() system call. If the buffer pr 518 recv()/recvmsg() system call. If the buffer provided by the user is too
523 short, the message will be truncated and the ` 519 short, the message will be truncated and the ``MSG_TRUNC`` flag set
524 in struct msghdr (struct msghdr is the second 520 in struct msghdr (struct msghdr is the second argument
525 of the recvmsg() system call, *not* a Netlink 521 of the recvmsg() system call, *not* a Netlink header).
526 522
527 Upon truncation the remaining part of the mess 523 Upon truncation the remaining part of the message is discarded.
528 524
529 Netlink expects that the user buffer will be a 525 Netlink expects that the user buffer will be at least 8kB or a page
530 size of the CPU architecture, whichever is big 526 size of the CPU architecture, whichever is bigger. Particular Netlink
531 families may, however, require a larger buffer 527 families may, however, require a larger buffer. 32kB buffer is recommended
532 for most efficient handling of dumps (larger b 528 for most efficient handling of dumps (larger buffer fits more dumped
533 objects and therefore fewer recvmsg() calls ar 529 objects and therefore fewer recvmsg() calls are needed).
534 530
535 .. _classic_netlink: <<
536 <<
537 Classic Netlink 531 Classic Netlink
538 =============== 532 ===============
539 533
540 The main differences between Classic and Gener 534 The main differences between Classic and Generic Netlink are the dynamic
541 allocation of subsystem identifiers and availa 535 allocation of subsystem identifiers and availability of introspection.
542 In theory the protocol does not differ signifi 536 In theory the protocol does not differ significantly, however, in practice
543 Classic Netlink experimented with concepts whi 537 Classic Netlink experimented with concepts which were abandoned in Generic
544 Netlink (really, they usually only found use i 538 Netlink (really, they usually only found use in a small corner of a single
545 subsystem). This section is meant as an explai 539 subsystem). This section is meant as an explainer of a few of such concepts,
546 with the explicit goal of giving the Generic N 540 with the explicit goal of giving the Generic Netlink
547 users the confidence to ignore them when readi 541 users the confidence to ignore them when reading the uAPI headers.
548 542
549 Most of the concepts and examples here refer t 543 Most of the concepts and examples here refer to the ``NETLINK_ROUTE`` family,
550 which covers much of the configuration of the 544 which covers much of the configuration of the Linux networking stack.
551 Real documentation of that family, deserves a 545 Real documentation of that family, deserves a chapter (or a book) of its own.
552 546
553 Families 547 Families
554 -------- 548 --------
555 549
556 Netlink refers to subsystems as families. This 550 Netlink refers to subsystems as families. This is a remnant of using
557 sockets and the concept of protocol families, 551 sockets and the concept of protocol families, which are part of message
558 demultiplexing in ``NETLINK_ROUTE``. 552 demultiplexing in ``NETLINK_ROUTE``.
559 553
560 Sadly every layer of encapsulation likes to re 554 Sadly every layer of encapsulation likes to refer to whatever it's carrying
561 as "families" making the term very confusing: 555 as "families" making the term very confusing:
562 556
563 1. AF_NETLINK is a bona fide socket protocol 557 1. AF_NETLINK is a bona fide socket protocol family
564 2. AF_NETLINK's documentation refers to what 558 2. AF_NETLINK's documentation refers to what comes after its own
565 header (struct nlmsghdr) in a message as a 559 header (struct nlmsghdr) in a message as a "Family Header"
566 3. Generic Netlink is a family for AF_NETLINK 560 3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows
567 struct nlmsghdr), yet it also calls its us 561 struct nlmsghdr), yet it also calls its users "Families".
568 562
569 Note that the Generic Netlink Family IDs are i 563 Note that the Generic Netlink Family IDs are in a different "ID space"
570 and overlap with Classic Netlink protocol numb 564 and overlap with Classic Netlink protocol numbers (e.g. ``NETLINK_CRYPTO``
571 has the Classic Netlink protocol ID of 21 whic 565 has the Classic Netlink protocol ID of 21 which Generic Netlink will
572 happily allocate to one of its families as wel 566 happily allocate to one of its families as well).
573 567
574 Strict checking 568 Strict checking
575 --------------- 569 ---------------
576 570
577 The ``NETLINK_GET_STRICT_CHK`` socket option e 571 The ``NETLINK_GET_STRICT_CHK`` socket option enables strict input checking
578 in ``NETLINK_ROUTE``. It was needed because hi 572 in ``NETLINK_ROUTE``. It was needed because historically kernel did not
579 validate the fields of structures it didn't pr 573 validate the fields of structures it didn't process. This made it impossible
580 to start using those fields later without risk 574 to start using those fields later without risking regressions in applications
581 which initialized them incorrectly or not at a 575 which initialized them incorrectly or not at all.
582 576
583 ``NETLINK_GET_STRICT_CHK`` declares that the a 577 ``NETLINK_GET_STRICT_CHK`` declares that the application is initializing
584 all fields correctly. It also opts into valida 578 all fields correctly. It also opts into validating that message does not
585 contain trailing data and requests that kernel 579 contain trailing data and requests that kernel rejects attributes with
586 type higher than largest attribute type known 580 type higher than largest attribute type known to the kernel.
587 581
588 ``NETLINK_GET_STRICT_CHK`` is not used outside 582 ``NETLINK_GET_STRICT_CHK`` is not used outside of ``NETLINK_ROUTE``.
589 583
590 Unknown attributes 584 Unknown attributes
591 ------------------ 585 ------------------
592 586
593 Historically Netlink ignored all unknown attri 587 Historically Netlink ignored all unknown attributes. The thinking was that
594 it would free the application from having to p 588 it would free the application from having to probe what kernel supports.
595 The application could make a request to change 589 The application could make a request to change the state and check which
596 parts of the request "stuck". 590 parts of the request "stuck".
597 591
598 This is no longer the case for new Generic Net 592 This is no longer the case for new Generic Netlink families and those opting
599 in to strict checking. See enum netlink_valida 593 in to strict checking. See enum netlink_validation for validation types
600 performed. 594 performed.
601 595
602 Fixed metadata and structures 596 Fixed metadata and structures
603 ----------------------------- 597 -----------------------------
604 598
605 Classic Netlink made liberal use of fixed-form 599 Classic Netlink made liberal use of fixed-format structures within
606 the messages. Messages would commonly have a s 600 the messages. Messages would commonly have a structure with
607 a considerable number of fields after struct n 601 a considerable number of fields after struct nlmsghdr. It was also
608 common to put structures with multiple members 602 common to put structures with multiple members inside attributes,
609 without breaking each member into an attribute 603 without breaking each member into an attribute of its own.
610 604
611 This has caused problems with validation and e 605 This has caused problems with validation and extensibility and
612 therefore using binary structures is actively 606 therefore using binary structures is actively discouraged for new
613 attributes. 607 attributes.
614 608
615 Request types 609 Request types
616 ------------- 610 -------------
617 611
618 ``NETLINK_ROUTE`` categorized requests into 4 612 ``NETLINK_ROUTE`` categorized requests into 4 types ``NEW``, ``DEL``, ``GET``,
619 and ``SET``. Each object can handle all or som 613 and ``SET``. Each object can handle all or some of those requests
620 (objects being netdevs, routes, addresses, qdi 614 (objects being netdevs, routes, addresses, qdiscs etc.) Request type
621 is defined by the 2 lowest bits of the message 615 is defined by the 2 lowest bits of the message type, so commands for
622 new objects would always be allocated with a s 616 new objects would always be allocated with a stride of 4.
623 617
624 Each object would also have its own fixed meta !! 618 Each object would also have it's own fixed metadata shared by all request
625 types (e.g. struct ifinfomsg for netdev reques 619 types (e.g. struct ifinfomsg for netdev requests, struct ifaddrmsg for address
626 requests, struct tcmsg for qdisc requests). 620 requests, struct tcmsg for qdisc requests).
627 621
628 Even though other protocols and Generic Netlin 622 Even though other protocols and Generic Netlink commands often use
629 the same verbs in their message names (``GET`` 623 the same verbs in their message names (``GET``, ``SET``) the concept
630 of request types did not find wider adoption. 624 of request types did not find wider adoption.
631 625
632 Notification echo 626 Notification echo
633 ----------------- 627 -----------------
634 628
635 ``NLM_F_ECHO`` requests for notifications resu 629 ``NLM_F_ECHO`` requests for notifications resulting from the request
636 to be queued onto the requesting socket. This 630 to be queued onto the requesting socket. This is useful to discover
637 the impact of the request. 631 the impact of the request.
638 632
639 Note that this feature is not universally impl 633 Note that this feature is not universally implemented.
640 634
641 Other request-type-specific flags 635 Other request-type-specific flags
642 --------------------------------- 636 ---------------------------------
643 637
644 Classic Netlink defined various flags for its 638 Classic Netlink defined various flags for its ``GET``, ``NEW``
645 and ``DEL`` requests in the upper byte of nlms 639 and ``DEL`` requests in the upper byte of nlmsg_flags in struct nlmsghdr.
646 Since request types have not been generalized 640 Since request types have not been generalized the request type specific
647 flags are rarely used (and considered deprecat 641 flags are rarely used (and considered deprecated for new families).
648 642
649 For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH 643 For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH`` are combined into
650 ``NLM_F_DUMP``, and not used separately. ``NLM 644 ``NLM_F_DUMP``, and not used separately. ``NLM_F_ATOMIC`` is never used.
651 645
652 For ``DEL`` - ``NLM_F_NONREC`` is only used by 646 For ``DEL`` - ``NLM_F_NONREC`` is only used by nftables and ``NLM_F_BULK``
653 only by FDB some operations. 647 only by FDB some operations.
654 648
655 The flags for ``NEW`` are used most commonly i 649 The flags for ``NEW`` are used most commonly in classic Netlink. Unfortunately,
656 the meaning is not crystal clear. The followin 650 the meaning is not crystal clear. The following description is based on the
657 best guess of the intention of the authors, an 651 best guess of the intention of the authors, and in practice all families
658 stray from it in one way or another. ``NLM_F_R 652 stray from it in one way or another. ``NLM_F_REPLACE`` asks to replace
659 an existing object, if no matching object exis 653 an existing object, if no matching object exists the operation should fail.
660 ``NLM_F_EXCL`` has the opposite semantics and 654 ``NLM_F_EXCL`` has the opposite semantics and only succeeds if object already
661 existed. 655 existed.
662 ``NLM_F_CREATE`` asks for the object to be cre 656 ``NLM_F_CREATE`` asks for the object to be created if it does not
663 exist, it can be combined with ``NLM_F_REPLACE 657 exist, it can be combined with ``NLM_F_REPLACE`` and ``NLM_F_EXCL``.
664 658
665 A comment in the main Netlink uAPI header stat 659 A comment in the main Netlink uAPI header states::
666 660
667 4.4BSD ADD NLM_F_CREATE|NLM_F_EXC 661 4.4BSD ADD NLM_F_CREATE|NLM_F_EXCL
668 4.4BSD CHANGE NLM_F_REPLACE 662 4.4BSD CHANGE NLM_F_REPLACE
669 663
670 True CHANGE NLM_F_CREATE|NLM_F_REP 664 True CHANGE NLM_F_CREATE|NLM_F_REPLACE
671 Append NLM_F_CREATE 665 Append NLM_F_CREATE
672 Check NLM_F_EXCL 666 Check NLM_F_EXCL
673 667
674 which seems to indicate that those flags preda 668 which seems to indicate that those flags predate request types.
675 ``NLM_F_REPLACE`` without ``NLM_F_CREATE`` was 669 ``NLM_F_REPLACE`` without ``NLM_F_CREATE`` was initially used instead
676 of ``SET`` commands. 670 of ``SET`` commands.
677 ``NLM_F_EXCL`` without ``NLM_F_CREATE`` was us 671 ``NLM_F_EXCL`` without ``NLM_F_CREATE`` was used to check if object exists
678 without creating it, presumably predating ``GE 672 without creating it, presumably predating ``GET`` commands.
679 673
680 ``NLM_F_APPEND`` indicates that if one key can 674 ``NLM_F_APPEND`` indicates that if one key can have multiple objects associated
681 with it (e.g. multiple next-hop objects for a 675 with it (e.g. multiple next-hop objects for a route) the new object should be
682 added to the list rather than replacing the en 676 added to the list rather than replacing the entire list.
683 677
684 uAPI reference 678 uAPI reference
685 ============== 679 ==============
686 680
687 .. kernel-doc:: include/uapi/linux/netlink.h 681 .. kernel-doc:: include/uapi/linux/netlink.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.