]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
8f0aff2a | 2 | .\" This man page is Copyright (c) 1998 by Andi Kleen. |
2297bf0e | 3 | .\" |
95fb8859 | 4 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
6a717e5e | 5 | .\" |
77117f4f MK |
6 | .\" Based on the original comments from Alexey Kuznetsov |
7 | .\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee> | |
8 | .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ | |
4c1c5274 | 9 | .TH netlink 7 (date) "Linux man-pages (unreleased)" |
77117f4f | 10 | .SH NAME |
f68512e9 | 11 | netlink \- communication between kernel and user space (AF_NETLINK) |
77117f4f MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .B #include <asm/types.h> | |
15 | .B #include <sys/socket.h> | |
16 | .B #include <linux/netlink.h> | |
c6d039a3 | 17 | .P |
d4c8c97c | 18 | .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); |
77117f4f MK |
19 | .fi |
20 | .SH DESCRIPTION | |
0a66259f | 21 | Netlink is used to transfer information between the kernel and |
7fac88a9 MK |
22 | user-space processes. |
23 | It consists of a standard sockets-based interface for user space | |
77117f4f MK |
24 | processes and an internal kernel API for kernel modules. |
25 | The internal kernel interface is not documented in this manual page. | |
26 | There is also an obsolete netlink interface | |
27 | via netlink character devices; this interface is not documented here | |
33a0ccb2 | 28 | and is provided only for backward compatibility. |
c6d039a3 | 29 | .P |
77117f4f MK |
30 | Netlink is a datagram-oriented service. |
31 | Both | |
32 | .B SOCK_RAW | |
33 | and | |
34 | .B SOCK_DGRAM | |
35 | are valid values for | |
36 | .IR socket_type . | |
37 | However, the netlink protocol does not distinguish between datagram | |
38 | and raw sockets. | |
c6d039a3 | 39 | .P |
77117f4f MK |
40 | .I netlink_family |
41 | selects the kernel module or netlink group to communicate with. | |
42 | The currently assigned netlink families are: | |
43 | .TP | |
1ae6b2c7 | 44 | .B NETLINK_ROUTE |
77117f4f MK |
45 | Receives routing and link updates and may be used to modify the routing |
46 | tables (both IPv4 and IPv6), IP addresses, link parameters, | |
3ded684c | 47 | neighbor setups, queueing disciplines, traffic classes, and |
77117f4f MK |
48 | packet classifiers (see |
49 | .BR rtnetlink (7)). | |
50 | .TP | |
b324e17d | 51 | .BR NETLINK_W1 " (Linux 2.6.13 to Linux 2.16.17)" |
77117f4f MK |
52 | Messages from 1-wire subsystem. |
53 | .TP | |
1ae6b2c7 | 54 | .B NETLINK_USERSOCK |
77117f4f MK |
55 | Reserved for user-mode socket protocols. |
56 | .TP | |
fddeaaba MK |
57 | .BR NETLINK_FIREWALL " (up to and including Linux 3.4)" |
58 | .\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84 | |
7fac88a9 | 59 | Transport IPv4 packets from netfilter to user space. |
77117f4f MK |
60 | Used by |
61 | .I ip_queue | |
62 | kernel module. | |
fddeaaba MK |
63 | After a long period of being declared obsolete (in favor of the more advanced |
64 | .I nfnetlink_queue | |
65 | feature), | |
1ae6b2c7 | 66 | .B NETLINK_FIREWALL |
fddeaaba | 67 | was removed in Linux 3.5. |
77117f4f | 68 | .TP |
7f9a6a99 MK |
69 | .BR NETLINK_SOCK_DIAG " (since Linux 3.3)" |
70 | .\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6 | |
77a7e0e2 DL |
71 | Query information about sockets of various protocol families from the kernel |
72 | (see | |
73 | .BR sock_diag (7)). | |
77117f4f | 74 | .TP |
7f9a6a99 MK |
75 | .BR NETLINK_INET_DIAG " (since Linux 2.6.14)" |
76 | An obsolete synonym for | |
77 | .BR NETLINK_SOCK_DIAG . | |
7133b898 | 78 | .TP |
d7fd538c | 79 | .BR NETLINK_NFLOG " (up to and including Linux 3.16)" |
77117f4f MK |
80 | Netfilter/iptables ULOG. |
81 | .TP | |
1ae6b2c7 | 82 | .B NETLINK_XFRM |
77117f4f MK |
83 | .\" FIXME More details on NETLINK_XFRM needed. |
84 | IPsec. | |
85 | .TP | |
6cab1c1f | 86 | .BR NETLINK_SELINUX " (since Linux 2.6.4)" |
77117f4f MK |
87 | SELinux event notifications. |
88 | .TP | |
6cab1c1f | 89 | .BR NETLINK_ISCSI " (since Linux 2.6.15)" |
77117f4f MK |
90 | .\" FIXME More details on NETLINK_ISCSI needed. |
91 | Open-iSCSI. | |
92 | .TP | |
6cab1c1f | 93 | .BR NETLINK_AUDIT " (since Linux 2.6.6)" |
77117f4f MK |
94 | .\" FIXME More details on NETLINK_AUDIT needed. |
95 | Auditing. | |
96 | .TP | |
6cab1c1f | 97 | .BR NETLINK_FIB_LOOKUP " (since Linux 2.6.13)" |
77117f4f | 98 | .\" FIXME More details on NETLINK_FIB_LOOKUP needed. |
7fac88a9 | 99 | Access to FIB lookup from user space. |
77117f4f | 100 | .TP |
6cab1c1f | 101 | .BR NETLINK_CONNECTOR " (since Linux 2.6.14)" |
77117f4f MK |
102 | Kernel connector. |
103 | See | |
b49c2acb | 104 | .I Documentation/driver\-api/connector.rst |
2ece4ef7 | 105 | (or |
1ae6b2c7 | 106 | .I /Documentation/connector/connector.* |
2ece4ef7 | 107 | .\" commit baa293e9544bea71361950d071579f0e4d5713ed |
b324e17d | 108 | in Linux 5.2 and earlier) |
66a9882e | 109 | in the Linux kernel source tree for further information. |
77117f4f | 110 | .TP |
34caa222 | 111 | .BR NETLINK_NETFILTER " (since Linux 2.6.14)" |
77117f4f MK |
112 | .\" FIXME More details on NETLINK_NETFILTER needed. |
113 | Netfilter subsystem. | |
114 | .TP | |
4338604d MK |
115 | .BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)" |
116 | .\" commit 84314fd4740ad73550c76dee4a9578979d84af48 | |
117 | .\" FIXME More details on NETLINK_SCSITRANSPORT needed. | |
118 | SCSI Transports. | |
119 | .TP | |
e39561aa MK |
120 | .BR NETLINK_RDMA " (since Linux 3.0)" |
121 | .\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463 | |
122 | .\" FIXME More details on NETLINK_RDMA needed. | |
123 | Infiniband RDMA. | |
124 | .TP | |
1fcf2003 | 125 | .BR NETLINK_IP6_FW " (up to and including Linux 3.4)" |
7fac88a9 | 126 | Transport IPv6 packets from netfilter to user space. |
77117f4f MK |
127 | Used by |
128 | .I ip6_queue | |
129 | kernel module. | |
130 | .TP | |
131 | .B NETLINK_DNRTMSG | |
132 | DECnet routing messages. | |
133 | .TP | |
6cab1c1f | 134 | .BR NETLINK_KOBJECT_UEVENT " (since Linux 2.6.10)" |
77117f4f | 135 | .\" FIXME More details on NETLINK_KOBJECT_UEVENT needed. |
7fac88a9 | 136 | Kernel messages to user space. |
77117f4f | 137 | .TP |
6cab1c1f | 138 | .BR NETLINK_GENERIC " (since Linux 2.6.15)" |
77117f4f | 139 | Generic netlink family for simplified netlink usage. |
7b429332 | 140 | .TP |
bbb4532b MK |
141 | .BR NETLINK_CRYPTO " (since Linux 3.2)" |
142 | .\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9 | |
143 | .\" Author: Steffen Klassert <steffen.klassert@secunet.com> | |
7b429332 SM |
144 | Netlink interface to request information about ciphers registered |
145 | with the kernel crypto API as well as allow configuration of the | |
146 | kernel crypto API. | |
c6d039a3 | 147 | .P |
77117f4f MK |
148 | Netlink messages consist of a byte stream with one or multiple |
149 | .I nlmsghdr | |
150 | headers and associated payload. | |
33a0ccb2 | 151 | The byte stream should be accessed only with the standard |
77117f4f MK |
152 | .B NLMSG_* |
153 | macros. | |
154 | See | |
155 | .BR netlink (3) | |
156 | for further information. | |
c6d039a3 | 157 | .P |
77117f4f MK |
158 | In multipart messages (multiple |
159 | .I nlmsghdr | |
160 | headers with associated payload in one byte stream) the first and all | |
161 | following headers have the | |
162 | .B NLM_F_MULTI | |
163 | flag set, except for the last header which has the type | |
164 | .BR NLMSG_DONE . | |
c6d039a3 | 165 | .P |
77117f4f MK |
166 | After each |
167 | .I nlmsghdr | |
168 | the payload follows. | |
c6d039a3 | 169 | .P |
77117f4f | 170 | .in +4n |
b8302363 | 171 | .EX |
77117f4f | 172 | struct nlmsghdr { |
115b4e0e AC |
173 | __u32 nlmsg_len; /* Length of message including header */ |
174 | __u16 nlmsg_type; /* Type of message content */ | |
175 | __u16 nlmsg_flags; /* Additional flags */ | |
176 | __u32 nlmsg_seq; /* Sequence number */ | |
177 | __u32 nlmsg_pid; /* Sender port ID */ | |
77117f4f | 178 | }; |
b8302363 | 179 | .EE |
77117f4f | 180 | .in |
c6d039a3 | 181 | .P |
77117f4f MK |
182 | .I nlmsg_type |
183 | can be one of the standard message types: | |
184 | .B NLMSG_NOOP | |
185 | message is to be ignored, | |
186 | .B NLMSG_ERROR | |
187 | message signals an error and the payload contains an | |
188 | .I nlmsgerr | |
189 | structure, | |
190 | .B NLMSG_DONE | |
5e833e27 MK |
191 | message terminates a multipart message. |
192 | Error messages get the | |
7371ef9e | 193 | original request appended, unless the user requests to cap the |
efbcc109 | 194 | error message, and get extra error data if requested. |
c6d039a3 | 195 | .P |
77117f4f | 196 | .in +4n |
b8302363 | 197 | .EX |
77117f4f MK |
198 | struct nlmsgerr { |
199 | int error; /* Negative errno or 0 for acknowledgements */ | |
200 | struct nlmsghdr msg; /* Message header that caused the error */ | |
efbcc109 | 201 | /* |
e5da16f1 AC |
202 | * followed by the message contents |
203 | * unless NETLINK_CAP_ACK was set | |
efbcc109 PS |
204 | * or the ACK indicates success (error == 0). |
205 | * For example Generic Netlink message with attributes. | |
206 | * message length is aligned with NLMSG_ALIGN() | |
207 | */ | |
208 | /* | |
209 | * followed by TLVs defined in enum nlmsgerr_attrs | |
210 | * if NETLINK_EXT_ACK was set | |
211 | */ | |
77117f4f | 212 | }; |
b8302363 | 213 | .EE |
77117f4f | 214 | .in |
c6d039a3 | 215 | .P |
77117f4f MK |
216 | A netlink family usually specifies more message types, see the |
217 | appropriate manual pages for that, for example, | |
218 | .BR rtnetlink (7) | |
219 | for | |
220 | .BR NETLINK_ROUTE . | |
77117f4f MK |
221 | .TS |
222 | tab(:); | |
3421b826 | 223 | l s |
0b174fe0 | 224 | lB lx. |
3421b826 BIG |
225 | Standard flag bits in \fInlmsg_flags\fP |
226 | _ | |
0b174fe0 MK |
227 | NLM_F_REQUEST:T{ |
228 | Must be set on all request messages. | |
229 | T} | |
77117f4f MK |
230 | NLM_F_MULTI:T{ |
231 | The message is part of a multipart message terminated by | |
232 | .BR NLMSG_DONE . | |
233 | T} | |
0b174fe0 | 234 | NLM_F_ACK:T{ |
daff5a66 | 235 | Request for an acknowledgement on success. |
0b174fe0 MK |
236 | T} |
237 | NLM_F_ECHO:T{ | |
238 | Echo this request. | |
239 | T} | |
77117f4f | 240 | .TE |
d33aa381 | 241 | .\" No right adjustment for text blocks in tables |
77117f4f MK |
242 | .TS |
243 | tab(:); | |
3421b826 | 244 | l s |
0b174fe0 | 245 | lB lx. |
3421b826 BIG |
246 | Additional flag bits for GET requests |
247 | _ | |
0b174fe0 MK |
248 | NLM_F_ROOT:T{ |
249 | Return the complete table instead of a single entry. | |
250 | T} | |
77117f4f MK |
251 | NLM_F_MATCH:T{ |
252 | Return all entries matching criteria passed in message content. | |
253 | Not implemented yet. | |
254 | T} | |
0b174fe0 MK |
255 | NLM_F_ATOMIC:T{ |
256 | Return an atomic snapshot of the table. | |
257 | T} | |
3421b826 | 258 | NLM_F_DUMP:T{ |
0eb65d3a | 259 | Convenience macro; equivalent to |
0eb65d3a | 260 | (NLM_F_ROOT|NLM_F_MATCH). |
3421b826 | 261 | T} |
77117f4f | 262 | .TE |
922077e0 | 263 | .\" FIXME NLM_F_ATOMIC is not used anymore? |
c6d039a3 | 264 | .P |
77117f4f MK |
265 | Note that |
266 | .B NLM_F_ATOMIC | |
267 | requires the | |
268 | .B CAP_NET_ADMIN | |
269 | capability or an effective UID of 0. | |
77117f4f MK |
270 | .TS |
271 | tab(:); | |
3421b826 | 272 | l s |
0b174fe0 | 273 | lB lx. |
3421b826 BIG |
274 | Additional flag bits for NEW requests |
275 | _ | |
0b174fe0 MK |
276 | NLM_F_REPLACE:T{ |
277 | Replace existing matching object. | |
278 | T} | |
279 | NLM_F_EXCL:T{ | |
280 | Don't replace if the object already exists. | |
281 | T} | |
282 | NLM_F_CREATE:T{ | |
283 | Create object if it doesn't already exist. | |
284 | T} | |
285 | NLM_F_APPEND:T{ | |
286 | Add to the end of the object list. | |
287 | T} | |
77117f4f | 288 | .TE |
c6d039a3 | 289 | .P |
77117f4f MK |
290 | .I nlmsg_seq |
291 | and | |
292 | .I nlmsg_pid | |
293 | are used to track messages. | |
294 | .I nlmsg_pid | |
295 | shows the origin of the message. | |
296 | Note that there isn't a 1:1 relationship between | |
297 | .I nlmsg_pid | |
298 | and the PID of the process if the message originated from a netlink | |
299 | socket. | |
300 | See the | |
301 | .B ADDRESS FORMATS | |
302 | section for further information. | |
c6d039a3 | 303 | .P |
77117f4f MK |
304 | Both |
305 | .I nlmsg_seq | |
306 | and | |
307 | .I nlmsg_pid | |
308 | .\" FIXME Explain more about nlmsg_seq and nlmsg_pid. | |
309 | are opaque to netlink core. | |
c6d039a3 | 310 | .P |
77117f4f MK |
311 | Netlink is not a reliable protocol. |
312 | It tries its best to deliver a message to its destination(s), | |
313 | but may drop messages when an out-of-memory condition or | |
314 | other error occurs. | |
315 | For reliable transfer the sender can request an | |
316 | acknowledgement from the receiver by setting the | |
317 | .B NLM_F_ACK | |
318 | flag. | |
daff5a66 | 319 | An acknowledgement is an |
77117f4f MK |
320 | .B NLMSG_ERROR |
321 | packet with the error field set to 0. | |
322 | The application must generate acknowledgements for | |
323 | received messages itself. | |
324 | The kernel tries to send an | |
325 | .B NLMSG_ERROR | |
326 | message for every failed packet. | |
327 | A user process should follow this convention too. | |
c6d039a3 | 328 | .P |
77117f4f MK |
329 | However, reliable transmissions from kernel to user are impossible |
330 | in any case. | |
331 | The kernel can't send a netlink message if the socket buffer is full: | |
7fac88a9 | 332 | the message will be dropped and the kernel and the user-space process will |
77117f4f MK |
333 | no longer have the same view of kernel state. |
334 | It is up to the application to detect when this happens (via the | |
335 | .B ENOBUFS | |
336 | error returned by | |
337 | .BR recvmsg (2)) | |
338 | and resynchronize. | |
c634028a | 339 | .SS Address formats |
77117f4f MK |
340 | The |
341 | .I sockaddr_nl | |
342 | structure describes a netlink client in user space or in the kernel. | |
343 | A | |
344 | .I sockaddr_nl | |
345 | can be either unicast (only sent to one peer) or sent to | |
346 | netlink multicast groups | |
347 | .RI ( nl_groups | |
348 | not equal 0). | |
c6d039a3 | 349 | .P |
77117f4f | 350 | .in +4n |
b8302363 | 351 | .EX |
77117f4f MK |
352 | struct sockaddr_nl { |
353 | sa_family_t nl_family; /* AF_NETLINK */ | |
6c5a6b2c MK |
354 | unsigned short nl_pad; /* Zero */ |
355 | pid_t nl_pid; /* Port ID */ | |
115b4e0e | 356 | __u32 nl_groups; /* Multicast groups mask */ |
77117f4f | 357 | }; |
b8302363 | 358 | .EE |
77117f4f | 359 | .in |
c6d039a3 | 360 | .P |
77117f4f MK |
361 | .I nl_pid |
362 | is the unicast address of netlink socket. | |
363 | It's always 0 if the destination is in the kernel. | |
7fac88a9 | 364 | For a user-space process, |
77117f4f MK |
365 | .I nl_pid |
366 | is usually the PID of the process owning the destination socket. | |
367 | However, | |
368 | .I nl_pid | |
369 | identifies a netlink socket, not a process. | |
370 | If a process owns several netlink | |
371 | sockets, then | |
372 | .I nl_pid | |
33a0ccb2 | 373 | can be equal to the process ID only for at most one socket. |
77117f4f MK |
374 | There are two ways to assign |
375 | .I nl_pid | |
376 | to a netlink socket. | |
377 | If the application sets | |
378 | .I nl_pid | |
379 | before calling | |
380 | .BR bind (2), | |
381 | then it is up to the application to make sure that | |
382 | .I nl_pid | |
383 | is unique. | |
384 | If the application sets it to 0, the kernel takes care of assigning it. | |
385 | The kernel assigns the process ID to the first netlink socket the process | |
386 | opens and assigns a unique | |
387 | .I nl_pid | |
388 | to every netlink socket that the process subsequently creates. | |
c6d039a3 | 389 | .P |
77117f4f MK |
390 | .I nl_groups |
391 | is a bit mask with every bit representing a netlink group number. | |
392 | Each netlink family has a set of 32 multicast groups. | |
393 | When | |
394 | .BR bind (2) | |
395 | is called on the socket, the | |
396 | .I nl_groups | |
397 | field in the | |
398 | .I sockaddr_nl | |
399 | should be set to a bit mask of the groups which it wishes to listen to. | |
400 | The default value for this field is zero which means that no multicasts | |
401 | will be received. | |
402 | A socket may multicast messages to any of the multicast groups by setting | |
403 | .I nl_groups | |
404 | to a bit mask of the groups it wishes to send to when it calls | |
405 | .BR sendmsg (2) | |
406 | or does a | |
407 | .BR connect (2). | |
408 | Only processes with an effective UID of 0 or the | |
409 | .B CAP_NET_ADMIN | |
410 | capability may send or listen to a netlink multicast group. | |
b96a8bc5 AV |
411 | Since Linux 2.6.13, |
412 | .\" commit d629b836d151d43332492651dd841d32e57ebe3b | |
413 | messages can't be broadcast to multiple groups. | |
77117f4f MK |
414 | Any replies to a message received for a multicast group should be |
415 | sent back to the sending PID and the multicast group. | |
dfad7db9 JM |
416 | Some Linux kernel subsystems may additionally allow other users |
417 | to send and/or receive messages. | |
50b57418 MK |
418 | As at Linux 3.0, the |
419 | .BR NETLINK_KOBJECT_UEVENT , | |
dfad7db9 | 420 | .BR NETLINK_GENERIC , |
50b57418 MK |
421 | .BR NETLINK_ROUTE , |
422 | and | |
1ae6b2c7 | 423 | .B NETLINK_SELINUX |
dfad7db9 JM |
424 | groups allow other users to receive messages. |
425 | No groups allow other users to send messages. | |
67d0dc13 AV |
426 | .SS Socket options |
427 | To set or get a netlink socket option, call | |
428 | .BR getsockopt (2) | |
429 | to read or | |
430 | .BR setsockopt (2) | |
431 | to write the option with the option level argument set to | |
432 | .BR SOL_NETLINK . | |
433 | Unless otherwise noted, | |
434 | .I optval | |
435 | is a pointer to an | |
436 | .IR int . | |
437 | .TP | |
438 | .BR NETLINK_PKTINFO " (since Linux 2.6.14)" | |
dd4d8039 MK |
439 | .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 |
440 | .\" Author: Patrick McHardy <kaber@trash.net> | |
67d0dc13 AV |
441 | Enable |
442 | .B nl_pktinfo | |
443 | control messages for received packets to get the extended | |
444 | destination group number. | |
445 | .TP | |
6fdb1c03 AC |
446 | .B NETLINK_ADD_MEMBERSHIP |
447 | .TQ | |
448 | .BR NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" | |
67d0dc13 AV |
449 | .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 |
450 | .\" Author: Patrick McHardy <kaber@trash.net> | |
376db9a1 MK |
451 | Join/leave a group specified by |
452 | .IR optval . | |
67d0dc13 AV |
453 | .TP |
454 | .BR NETLINK_LIST_MEMBERSHIPS " (since Linux 4.2)" | |
376db9a1 MK |
455 | .\" commit b42be38b2778eda2237fc759e55e3b698b05b315 |
456 | .\" Author: David Herrmann <dh.herrmann@gmail.com> | |
67d0dc13 AV |
457 | Retrieve all groups a socket is a member of. |
458 | .I optval | |
459 | is a pointer to | |
115b4e0e | 460 | .B __u32 |
67d0dc13 AV |
461 | and |
462 | .I optlen | |
319a5cb8 MK |
463 | is the size of the array. |
464 | The array is filled with the full membership set of the | |
67d0dc13 | 465 | socket, and the required array size is returned in |
4f542fe3 | 466 | .IR optlen . |
67d0dc13 AV |
467 | .TP |
468 | .BR NETLINK_BROADCAST_ERROR " (since Linux 2.6.30)" | |
376db9a1 MK |
469 | .\" commit be0c22a46cfb79ab2342bb28fde99afa94ef868e |
470 | .\" Author: Pablo Neira Ayuso <pablo@netfilter.org> | |
67d0dc13 AV |
471 | When not set, |
472 | .B netlink_broadcast() | |
473 | only reports | |
474 | .B ESRCH | |
475 | errors and silently ignore | |
1191b4e7 | 476 | .B ENOBUFS |
67d0dc13 | 477 | errors. |
67d0dc13 AV |
478 | .TP |
479 | .BR NETLINK_NO_ENOBUFS " (since Linux 2.6.30)" | |
376db9a1 MK |
480 | .\" commit 38938bfe3489394e2eed5e40c9bb8f66a2ce1405 |
481 | .\" Author: Pablo Neira Ayuso <pablo@netfilter.org> | |
67d0dc13 AV |
482 | This flag can be used by unicast and broadcast listeners to avoid receiving |
483 | .B ENOBUFS | |
484 | errors. | |
67d0dc13 AV |
485 | .TP |
486 | .BR NETLINK_LISTEN_ALL_NSID " (since Linux 4.2)" | |
376db9a1 MK |
487 | .\" commit 59324cf35aba5336b611074028777838a963d03b |
488 | .\" Author: Nicolas Dichtel <nicolas.dichtel@6wind.com> | |
489 | When set, this socket will receive netlink notifications from | |
490 | all network namespaces that have an | |
67d0dc13 | 491 | .I nsid |
319a5cb8 MK |
492 | assigned into the network namespace where the socket has been opened. |
493 | The | |
67d0dc13 AV |
494 | .I nsid |
495 | is sent to user space via an ancillary data. | |
67d0dc13 | 496 | .TP |
169db948 | 497 | .BR NETLINK_CAP_ACK " (since Linux 4.3)" |
376db9a1 MK |
498 | .\" commit 0a6a3a23ea6efde079a5b77688541a98bf202721 |
499 | .\" Author: Christophe Ricard <christophe.ricard@gmail.com> | |
daff5a66 | 500 | The kernel may fail to allocate the necessary room for the acknowledgement |
6f858d5c | 501 | message back to user space. |
319a5cb8 | 502 | This option trims off the payload of the original netlink message. |
67d0dc13 | 503 | The netlink message header is still included, so the user can guess from the |
daff5a66 | 504 | sequence number which message triggered the acknowledgement. |
77117f4f | 505 | .SH VERSIONS |
6cab1c1f | 506 | The socket interface to netlink first appeared Linux 2.2. |
c6d039a3 | 507 | .P |
e929e68b | 508 | Linux 2.0 supported a more primitive device-based netlink interface |
77117f4f MK |
509 | (which is still available as a compatibility option). |
510 | This obsolete interface is not described here. | |
77117f4f MK |
511 | .SH NOTES |
512 | It is often better to use netlink via | |
513 | .I libnetlink | |
514 | or | |
515 | .I libnl | |
516 | than via the low-level kernel interface. | |
517 | .SH BUGS | |
518 | This manual page is not complete. | |
a14af333 | 519 | .SH EXAMPLES |
77117f4f MK |
520 | The following example creates a |
521 | .B NETLINK_ROUTE | |
522 | netlink socket which will listen to the | |
523 | .B RTMGRP_LINK | |
524 | (network interface create/delete/up/down events) and | |
525 | .B RTMGRP_IPV4_IFADDR | |
526 | (IPv4 addresses add/delete events) multicast groups. | |
c6d039a3 | 527 | .P |
77117f4f | 528 | .in +4n |
b8302363 | 529 | .EX |
77117f4f | 530 | struct sockaddr_nl sa; |
fe5dba13 | 531 | \& |
77117f4f | 532 | memset(&sa, 0, sizeof(sa)); |
63042553 VN |
533 | sa.nl_family = AF_NETLINK; |
534 | sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR; | |
fe5dba13 | 535 | \& |
77117f4f | 536 | fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); |
48011c24 | 537 | bind(fd, (struct sockaddr *) &sa, sizeof(sa)); |
b8302363 | 538 | .EE |
77117f4f | 539 | .in |
c6d039a3 | 540 | .P |
77117f4f MK |
541 | The next example demonstrates how to send a netlink message to the |
542 | kernel (pid 0). | |
69b77259 | 543 | Note that the application must take care of message sequence numbers |
77117f4f | 544 | in order to reliably track acknowledgements. |
c6d039a3 | 545 | .P |
77117f4f | 546 | .in +4n |
b8302363 | 547 | .EX |
6c5a6b2c | 548 | struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ |
77117f4f | 549 | struct sockaddr_nl sa; |
13f78d96 | 550 | struct iovec iov = { nh, nh\->nlmsg_len }; |
77117f4f | 551 | struct msghdr msg; |
fe5dba13 | 552 | \& |
13f78d96 | 553 | msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; |
77117f4f MK |
554 | memset(&sa, 0, sizeof(sa)); |
555 | sa.nl_family = AF_NETLINK; | |
556 | nh\->nlmsg_pid = 0; | |
557 | nh\->nlmsg_seq = ++sequence_number; | |
6c5a6b2c | 558 | /* Request an ack from kernel by setting NLM_F_ACK */ |
77117f4f | 559 | nh\->nlmsg_flags |= NLM_F_ACK; |
fe5dba13 | 560 | \& |
77117f4f | 561 | sendmsg(fd, &msg, 0); |
b8302363 | 562 | .EE |
77117f4f | 563 | .in |
c6d039a3 | 564 | .P |
77117f4f | 565 | And the last example is about reading netlink message. |
c6d039a3 | 566 | .P |
77117f4f | 567 | .in +4n |
b8302363 | 568 | .EX |
77117f4f | 569 | int len; |
ae10667d AD |
570 | /* 8192 to avoid message truncation on platforms with |
571 | page size > 4096 */ | |
572 | struct nlmsghdr buf[8192/sizeof(struct nlmsghdr)]; | |
77117f4f MK |
573 | struct iovec iov = { buf, sizeof(buf) }; |
574 | struct sockaddr_nl sa; | |
575 | struct msghdr msg; | |
576 | struct nlmsghdr *nh; | |
fe5dba13 | 577 | \& |
13f78d96 | 578 | msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; |
77117f4f | 579 | len = recvmsg(fd, &msg, 0); |
fe5dba13 | 580 | \& |
77117f4f MK |
581 | for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); |
582 | nh = NLMSG_NEXT (nh, len)) { | |
6c5a6b2c | 583 | /* The end of multipart message */ |
77117f4f MK |
584 | if (nh\->nlmsg_type == NLMSG_DONE) |
585 | return; | |
fe5dba13 | 586 | \& |
77117f4f | 587 | if (nh\->nlmsg_type == NLMSG_ERROR) |
6c5a6b2c | 588 | /* Do some error handling */ |
77117f4f | 589 | ... |
fe5dba13 | 590 | \& |
6c5a6b2c | 591 | /* Continue with parsing payload */ |
77117f4f MK |
592 | ... |
593 | } | |
b8302363 | 594 | .EE |
77117f4f | 595 | .in |
47297adb | 596 | .SH SEE ALSO |
77117f4f MK |
597 | .BR cmsg (3), |
598 | .BR netlink (3), | |
599 | .BR capabilities (7), | |
77a7e0e2 DL |
600 | .BR rtnetlink (7), |
601 | .BR sock_diag (7) | |
c6d039a3 | 602 | .P |
5465ae95 | 603 | .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* |
608bf950 SK |
604 | information about libnetlink |
605 | .UE | |
c6d039a3 | 606 | .P |
3f029bc9 | 607 | .UR http://www.infradead.org\:/\[ti]tgr\:/libnl/ |
608bf950 SK |
608 | information about libnl |
609 | .UE | |
c6d039a3 | 610 | .P |
77117f4f | 611 | RFC 3549 "Linux Netlink as an IP Services Protocol" |