1 .\" Copyright (c) 2016 Pavel Emelyanov <xemul@virtuozzo.com>
2 .\" Copyright (c) 2016 Dmitry V. Levin <ldv@altlinux.org>
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .TH sock_diag 7 (date) "Linux man-pages (unreleased)"
7 sock_diag \- obtaining information about sockets
10 .B #include <sys/socket.h>
11 .B #include <linux/sock_diag.h>
12 .BR "#include <linux/unix_diag.h>" " /* for UNIX domain sockets */"
13 .BR "#include <linux/inet_diag.h>" " /* for IPv4 and IPv6 sockets */"
15 .BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);"
18 The sock_diag netlink subsystem provides a mechanism for obtaining
19 information about sockets of various address families from the kernel.
20 This subsystem can be used to obtain information about individual
21 sockets or request a list of sockets.
23 In the request, the caller can specify additional information it would
24 like to obtain about the socket, for example, memory information or
25 information specific to the address family.
27 When requesting a list of sockets, the caller can specify filters that
28 would be applied by the kernel to select a subset of sockets to report.
29 For now, there is only the ability to filter sockets by state (connected,
30 listening, and so on.)
32 Note that sock_diag reports only those sockets that have a name;
33 that is, either sockets bound explicitly with
35 or sockets that were automatically bound to an address (e.g., by
37 This is the same set of sockets that is available via
44 The request starts with a
51 .BR SOCK_DIAG_BY_FAMILY .
52 It is followed by a header specific to the address family that starts with
53 a common part shared by all address families:
57 struct sock_diag_req {
64 The fields of this structure are as follows:
68 It should be set to the appropriate
75 It should be set to the appropriate
89 flag set, it means that a list of sockets is being requested;
90 otherwise it is a query about an individual socket.
93 The response starts with a
95 header and is followed by an array of objects specific to the address family.
96 The array is to be accessed with the standard
102 Each object is the NLA (netlink attributes) list that is to be accessed
109 .SS UNIX domain sockets
110 For UNIX domain sockets the request is represented in the following structure:
114 struct unix_diag_req {
121 __u32 udiag_cookie[2];
126 The fields of this structure are as follows:
129 The address family; it should be set to
137 These fields should be set to 0.
140 This is a bit mask that defines a filter of sockets states.
141 Only those sockets whose states are in this mask will be reported.
142 Ignored when querying for an individual socket.
143 Supported values are:
154 This is an inode number when querying for an individual socket.
155 Ignored when querying for a list of sockets.
158 This is a set of flags defining what kind of information to report.
159 Each requested kind of information is reported back as a netlink
160 attribute as described below:
164 The attribute reported in answer to this request is
166 The payload associated with this attribute is the pathname to which
167 the socket was bound (a sequence of bytes up to
172 The attribute reported in answer to this request is
174 The payload associated with this attribute is represented in the following
179 struct unix_diag_vfs {
186 The fields of this structure are as follows:
190 The device number of the corresponding on-disk socket inode.
193 The inode number of the corresponding on-disk socket inode.
197 The attribute reported in answer to this request is
199 The payload associated with this attribute is a __u32 value
200 which is the peer's inode number.
201 This attribute is reported for connected sockets only.
204 The attribute reported in answer to this request is
205 .BR UNIX_DIAG_ICONS .
206 The payload associated with this attribute is an array of __u32 values
207 which are inode numbers of sockets that has passed the
209 call, but hasn't been processed with
212 This attribute is reported for listening sockets only.
215 The attribute reported in answer to this request is
216 .BR UNIX_DIAG_RQLEN .
217 The payload associated with this attribute is represented in the following
222 struct unix_diag_rqlen {
229 The fields of this structure are as follows:
233 For listening sockets:
234 the number of pending connections.
235 The length of the array associated with the
237 response attribute is equal to this value.
239 For established sockets:
240 the amount of data in incoming queue.
243 For listening sockets:
244 the backlog length which equals to the value passed as the second argument to
247 For established sockets:
248 the amount of memory available for sending.
251 .B UDIAG_SHOW_MEMINFO
252 The attribute reported in answer to this request is
253 .BR UNIX_DIAG_MEMINFO .
254 The payload associated with this attribute is an array of __u32 values
255 described below in the subsection "Socket memory information".
257 The following attributes are reported back without any specific request:
259 .B UNIX_DIAG_SHUTDOWN
260 The payload associated with this attribute is __u8 value which represents
267 This is an array of opaque identifiers that could be used along with
269 to specify an individual socket.
270 It is ignored when querying for a list
271 of sockets, as well as when all its elements are set to \-1.
273 The response to a query for UNIX domain sockets is represented as an array of
277 struct unix_diag_msg {
283 __u32 udiag_cookie[2];
288 followed by netlink attributes.
290 The fields of this structure are as follows:
293 This field has the same meaning as in
294 .IR "struct unix_diag_req" .
297 This is set to one of
304 This is set to one of
307 .BR TCP_ESTABLISHED .
310 This field is set to 0.
313 This is the socket inode number.
316 This is an array of opaque identifiers that could be used in subsequent
319 .SS IPv4 and IPv6 sockets
320 For IPv4 and IPv6 sockets,
321 the request is represented in the following structure:
325 struct inet_diag_req_v2 {
331 struct inet_diag_sockid id;
337 .I "struct inet_diag_sockid"
338 is defined as follows:
342 struct inet_diag_sockid {
348 __u32 idiag_cookie[2];
354 .I "struct inet_diag_req_v2"
358 This should be set to either
362 for IPv4 or IPv6 sockets respectively.
365 This should be set to one of
369 .BR IPPROTO_UDPLITE .
372 This is a set of flags defining what kind of extended information to report.
373 Each requested kind of information is reported back as a netlink attribute
378 The payload associated with this attribute is a __u8 value
379 which is the TOS of the socket.
382 The payload associated with this attribute is a __u8 value
383 which is the TClass of the socket.
385 For LISTEN and CLOSE sockets, this is followed by
386 .B INET_DIAG_SKV6ONLY
387 attribute with associated __u8 payload value meaning whether the socket
391 The payload associated with this attribute is represented in the following
396 struct inet_diag_meminfo {
405 The fields of this structure are as follows:
409 The amount of data in the receive queue.
412 The amount of data that is queued by TCP but not yet sent.
415 The amount of memory scheduled for future use (TCP only).
418 The amount of data in send queue.
421 .B INET_DIAG_SKMEMINFO
422 The payload associated with this attribute is an array of __u32 values
423 described below in the subsection "Socket memory information".
426 The payload associated with this attribute is specific to the address family.
427 For TCP sockets, it is an object of type
428 .IR "struct tcp_info" .
431 The payload associated with this attribute is a string that describes the
432 congestion control algorithm used.
433 For TCP sockets only.
437 This should be set to 0.
440 This is a bit mask that defines a filter of socket states.
441 Only those sockets whose states are in this mask will be reported.
442 Ignored when querying for an individual socket.
445 This is a socket ID object that is used in dump requests, in queries
446 about individual sockets, and is reported back in each response.
447 Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified
448 using addresses and ports.
449 All values are in network byte order.
452 .I "struct inet_diag_sockid"
459 The destination port.
465 The destination address.
468 The interface number the socket is bound to.
471 This is an array of opaque identifiers that could be used along with
472 other fields of this structure to specify an individual socket.
473 It is ignored when querying for a list of sockets, as well as
474 when all its elements are set to \-1.
476 The response to a query for IPv4 or IPv6 sockets is represented as an array of
480 struct inet_diag_msg {
486 struct inet_diag_sockid id;
497 followed by netlink attributes.
499 The fields of this structure are as follows:
502 This is the same field as in
503 .IR "struct inet_diag_req_v2" .
506 This denotes socket state as in
507 .IR "struct inet_diag_req_v2" .
510 For TCP sockets, this field describes the type of timer that is currently
511 active for the socket.
512 It is set to one of the following constants:
530 a zero window probe timer
534 For non-TCP sockets, this field is set to 0.
539 values 1, 2, and 4, this field contains the number of retransmits.
542 values, this field is set to 0.
545 For TCP sockets that have an active timer, this field describes its expiration
546 time in milliseconds.
547 For other sockets, this field is set to 0.
550 For listening sockets:
551 the number of pending connections.
554 the amount of data in the incoming queue.
557 For listening sockets:
561 the amount of memory available for sending.
564 This is the socket owner UID.
567 This is the socket inode number.
569 .SS Socket memory information
570 The payload associated with
573 .B INET_DIAG_SKMEMINFO
574 netlink attributes is an array of the following __u32 values:
576 .B SK_MEMINFO_RMEM_ALLOC
577 The amount of data in receive queue.
580 The receive socket buffer as set by
583 .B SK_MEMINFO_WMEM_ALLOC
584 The amount of data in send queue.
587 The send socket buffer as set by
590 .B SK_MEMINFO_FWD_ALLOC
591 The amount of memory scheduled for future use (TCP only).
593 .B SK_MEMINFO_WMEM_QUEUED
594 The amount of data queued by TCP, but not yet sent.
597 The amount of memory allocated for the socket's service needs (e.g., socket
600 .B SK_MEMINFO_BACKLOG
601 The amount of packets in the backlog (not yet processed).
604 was introduced in Linux 2.6.14 and supported
609 In Linux 3.3, it was renamed to
611 and extended to support
617 .B INET_DIAG_SKMEMINFO
618 were introduced in Linux 3.6.
622 The following example program prints inode number, peer's inode number,
623 and name of all UNIX domain sockets in the current namespace.
630 #include <sys/socket.h>
632 #include <linux/netlink.h>
633 #include <linux/rtnetlink.h>
634 #include <linux/sock_diag.h>
635 #include <linux/unix_diag.h>
640 struct sockaddr_nl nladdr = {
641 .nl_family = AF_NETLINK
646 struct unix_diag_req udr;
649 .nlmsg_len = sizeof(req),
650 .nlmsg_type = SOCK_DIAG_BY_FAMILY,
651 .nlmsg_flags = NLM_F_REQUEST | NLM_F_DUMP
654 .sdiag_family = AF_UNIX,
656 .udiag_show = UDIAG_SHOW_NAME | UDIAG_SHOW_PEER
661 .iov_len = sizeof(req)
663 struct msghdr msg = {
665 .msg_namelen = sizeof(nladdr),
671 if (sendmsg(fd, &msg, 0) < 0) {
684 print_diag(const struct unix_diag_msg *diag, unsigned int len)
686 if (len < NLMSG_LENGTH(sizeof(*diag))) {
687 fputs("short response\en", stderr);
690 if (diag\->udiag_family != AF_UNIX) {
691 fprintf(stderr, "unexpected family %u\en", diag\->udiag_family);
695 unsigned int rta_len = len \- NLMSG_LENGTH(sizeof(*diag));
696 unsigned int peer = 0;
698 char path[sizeof(((struct sockaddr_un *) 0)\->sun_path) + 1];
700 for (struct rtattr *attr = (struct rtattr *) (diag + 1);
701 RTA_OK(attr, rta_len); attr = RTA_NEXT(attr, rta_len)) {
702 switch (attr\->rta_type) {
705 path_len = RTA_PAYLOAD(attr);
706 if (path_len > sizeof(path) \- 1)
707 path_len = sizeof(path) \- 1;
708 memcpy(path, RTA_DATA(attr), path_len);
709 path[path_len] = \[aq]\e0\[aq];
714 if (RTA_PAYLOAD(attr) >= sizeof(peer))
715 peer = *(unsigned int *) RTA_DATA(attr);
720 printf("inode=%u", diag\->udiag_ino);
723 printf(", peer=%u", peer);
726 printf(", name=%s%s", *path ? "" : "@",
727 *path ? path : path + 1);
729 putchar(\[aq]\en\[aq]);
734 receive_responses(int fd)
736 long buf[8192 / sizeof(long)];
737 struct sockaddr_nl nladdr;
740 .iov_len = sizeof(buf)
745 struct msghdr msg = {
747 .msg_namelen = sizeof(nladdr),
752 ssize_t ret = recvmsg(fd, &msg, flags);
764 if (nladdr.nl_family != AF_NETLINK) {
765 fputs("!AF_NETLINK\en", stderr);
769 const struct nlmsghdr *h = (struct nlmsghdr *) buf;
771 if (!NLMSG_OK(h, ret)) {
772 fputs("!NLMSG_OK\en", stderr);
776 for (; NLMSG_OK(h, ret); h = NLMSG_NEXT(h, ret)) {
777 if (h\->nlmsg_type == NLMSG_DONE)
780 if (h\->nlmsg_type == NLMSG_ERROR) {
781 const struct nlmsgerr *err = NLMSG_DATA(h);
783 if (h\->nlmsg_len < NLMSG_LENGTH(sizeof(*err))) {
784 fputs("NLMSG_ERROR\en", stderr);
786 errno = \-err\->error;
787 perror("NLMSG_ERROR");
793 if (h\->nlmsg_type != SOCK_DIAG_BY_FAMILY) {
794 fprintf(stderr, "unexpected nlmsg_type %u\en",
795 (unsigned) h\->nlmsg_type);
799 if (print_diag(NLMSG_DATA(h), h\->nlmsg_len))
808 int fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_SOCK_DIAG);
815 int ret = send_query(fd) || receive_responses(fd);