| blob | 33fb2702f02193d944df3fc6146ddf1a9459319b |
1 .\" Copyright (c) 2016 Pavel Emelyanov <xemul@virtuozzo.com>
2 .\" Copyright (c) 2016 Dmitry V. Levin <ldv@altlinux.org>
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .TH sock_diag 7 (date) "Linux man-pages (unreleased)"
6 .SH NAME
7 sock_diag \- obtaining information about sockets
8 .SH SYNOPSIS
9 .nf
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 */"
14 .P
15 .BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);"
16 .fi
17 .SH DESCRIPTION
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.
22 .P
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.
26 .P
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.)
31 .P
32 Note that sock_diag reports only those sockets that have a name;
33 that is, either sockets bound explicitly with
34 .BR bind (2)
35 or sockets that were automatically bound to an address (e.g., by
36 .BR connect (2)).
37 This is the same set of sockets that is available via
38 .IR /proc/net/unix ,
39 .IR /proc/net/tcp ,
40 .IR /proc/net/udp ,
41 and so on.
42 .\"
43 .SS Request
44 The request starts with a
45 .I "struct nlmsghdr"
46 header described in
47 .BR netlink (7)
48 with
49 .I nlmsg_type
50 field set to
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:
54 .P
55 .in +4n
56 .EX
57 struct sock_diag_req {
58 __u8 sdiag_family;
59 __u8 sdiag_protocol;
60 };
61 .EE
62 .in
63 .P
64 The fields of this structure are as follows:
65 .TP
66 .I sdiag_family
67 An address family.
68 It should be set to the appropriate
69 .B AF_*
70 constant.
71 .TP
72 .I sdiag_protocol
73 Depends on
74 .IR sdiag_family .
75 It should be set to the appropriate
76 .B IPPROTO_*
77 constant for
78 .B AF_INET
79 and
80 .BR AF_INET6 ,
81 and to 0 otherwise.
82 .P
83 If the
84 .I nlmsg_flags
85 field of the
86 .I "struct nlmsghdr"
87 header has the
88 .B NLM_F_DUMP
89 flag set, it means that a list of sockets is being requested;
90 otherwise it is a query about an individual socket.
91 .\"
92 .SS Response
93 The response starts with a
94 .I "struct nlmsghdr"
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
97 .B NLMSG_*
98 macros from the
99 .BR netlink (3)
100 API.
101 .P
102 Each object is the NLA (netlink attributes) list that is to be accessed
103 with the
104 .B RTA_*
105 macros from
106 .BR rtnetlink (3)
107 API.
108 .\"
109 .SS UNIX domain sockets
110 For UNIX domain sockets the request is represented in the following structure:
111 .P
112 .in +4n
113 .EX
114 struct unix_diag_req {
115 __u8 sdiag_family;
116 __u8 sdiag_protocol;
117 __u16 pad;
118 __u32 udiag_states;
119 __u32 udiag_ino;
120 __u32 udiag_show;
121 __u32 udiag_cookie[2];
122 };
123 .EE
124 .in
125 .P
126 The fields of this structure are as follows:
127 .TP
128 .I sdiag_family
129 The address family; it should be set to
130 .BR AF_UNIX .
131 .P
132 .I sdiag_protocol
133 .PD 0
134 .TP
135 .PD
136 .I pad
137 These fields should be set to 0.
138 .TP
139 .I udiag_states
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:
144 .P
145 .RS 12
146 1 <<
147 .B TCP_ESTABLISHED
148 .P
149 1 <<
150 .B TCP_LISTEN
151 .RE
152 .TP
153 .I udiag_ino
154 This is an inode number when querying for an individual socket.
155 Ignored when querying for a list of sockets.
156 .TP
157 .I udiag_show
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:
161 .RS
162 .TP
163 .B UDIAG_SHOW_NAME
164 The attribute reported in answer to this request is
165 .BR UNIX_DIAG_NAME .
166 The payload associated with this attribute is the pathname to which
167 the socket was bound (a sequence of bytes up to
168 .B UNIX_PATH_MAX
169 length).
170 .TP
171 .B UDIAG_SHOW_VFS
172 The attribute reported in answer to this request is
173 .BR UNIX_DIAG_VFS .
174 The payload associated with this attribute is represented in the following
175 structure:
176 .IP
177 .in +4n
178 .EX
179 struct unix_diag_vfs {
180 __u32 udiag_vfs_dev;
181 __u32 udiag_vfs_ino;
182 };
183 .EE
184 .in
185 .IP
186 The fields of this structure are as follows:
187 .RS
188 .TP
189 .I udiag_vfs_dev
190 The device number of the corresponding on-disk socket inode.
191 .TP
192 .I udiag_vfs_ino
193 The inode number of the corresponding on-disk socket inode.
194 .RE
195 .TP
196 .B UDIAG_SHOW_PEER
197 The attribute reported in answer to this request is
198 .BR UNIX_DIAG_PEER .
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.
202 .TP
203 .B UDIAG_SHOW_ICONS
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
208 .BR connect (2)
209 call, but hasn't been processed with
210 .BR accept (2)
211 yet.
212 This attribute is reported for listening sockets only.
213 .TP
214 .B UDIAG_SHOW_RQLEN
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
218 structure:
219 .IP
220 .in +4n
221 .EX
222 struct unix_diag_rqlen {
223 __u32 udiag_rqueue;
224 __u32 udiag_wqueue;
225 };
226 .EE
227 .in
228 .IP
229 The fields of this structure are as follows:
230 .RS
231 .TP
232 .I udiag_rqueue
233 For listening sockets:
234 the number of pending connections.
235 The length of the array associated with the
236 .B UNIX_DIAG_ICONS
237 response attribute is equal to this value.
238 .IP
239 For established sockets:
240 the amount of data in incoming queue.
241 .TP
242 .I udiag_wqueue
243 For listening sockets:
244 the backlog length which equals to the value passed as the second argument to
245 .BR listen (2).
246 .IP
247 For established sockets:
248 the amount of memory available for sending.
249 .RE
250 .TP
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".
256 .P
257 The following attributes are reported back without any specific request:
258 .TP
259 .B UNIX_DIAG_SHUTDOWN
260 The payload associated with this attribute is __u8 value which represents
261 bits of
262 .BR shutdown (2)
263 state.
264 .RE
265 .TP
266 .I udiag_cookie
267 This is an array of opaque identifiers that could be used along with
268 .I udiag_ino
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.
272 .P
273 The response to a query for UNIX domain sockets is represented as an array of
274 .P
275 .in +4n
276 .EX
277 struct unix_diag_msg {
278 __u8 udiag_family;
279 __u8 udiag_type;
280 __u8 udiag_state;
281 __u8 pad;
282 __u32 udiag_ino;
283 __u32 udiag_cookie[2];
284 };
285 .EE
286 .in
287 .P
288 followed by netlink attributes.
289 .P
290 The fields of this structure are as follows:
291 .TP
292 .I udiag_family
293 This field has the same meaning as in
294 .IR "struct unix_diag_req" .
295 .TP
296 .I udiag_type
297 This is set to one of
298 .BR SOCK_PACKET ,
299 .BR SOCK_STREAM ,
300 or
301 .BR SOCK_SEQPACKET .
302 .TP
303 .I udiag_state
304 This is set to one of
305 .B TCP_LISTEN
306 or
307 .BR TCP_ESTABLISHED .
308 .TP
309 .I pad
310 This field is set to 0.
311 .TP
312 .I udiag_ino
313 This is the socket inode number.
314 .TP
315 .I udiag_cookie
316 This is an array of opaque identifiers that could be used in subsequent
317 queries.
318 .\"
319 .SS IPv4 and IPv6 sockets
320 For IPv4 and IPv6 sockets,
321 the request is represented in the following structure:
322 .P
323 .in +4n
324 .EX
325 struct inet_diag_req_v2 {
326 __u8 sdiag_family;
327 __u8 sdiag_protocol;
328 __u8 idiag_ext;
329 __u8 pad;
330 __u32 idiag_states;
331 struct inet_diag_sockid id;
332 };
333 .EE
334 .in
335 .P
336 where
337 .I "struct inet_diag_sockid"
338 is defined as follows:
339 .P
340 .in +4n
341 .EX
342 struct inet_diag_sockid {
343 __be16 idiag_sport;
344 __be16 idiag_dport;
345 __be32 idiag_src[4];
346 __be32 idiag_dst[4];
347 __u32 idiag_if;
348 __u32 idiag_cookie[2];
349 };
350 .EE
351 .in
352 .P
353 The fields of
354 .I "struct inet_diag_req_v2"
355 are as follows:
356 .TP
357 .I sdiag_family
358 This should be set to either
359 .B AF_INET
360 or
361 .B AF_INET6
362 for IPv4 or IPv6 sockets respectively.
363 .TP
364 .I sdiag_protocol
365 This should be set to one of
366 .BR IPPROTO_TCP ,
367 .BR IPPROTO_UDP ,
368 or
369 .BR IPPROTO_UDPLITE .
370 .TP
371 .I idiag_ext
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
374 as described below:
375 .RS
376 .TP
377 .B INET_DIAG_TOS
378 The payload associated with this attribute is a __u8 value
379 which is the TOS of the socket.
380 .TP
381 .B INET_DIAG_TCLASS
382 The payload associated with this attribute is a __u8 value
383 which is the TClass of the socket.
384 IPv6 sockets only.
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
388 is IPv6-only or not.
389 .TP
390 .B INET_DIAG_MEMINFO
391 The payload associated with this attribute is represented in the following
392 structure:
393 .IP
394 .in +4n
395 .EX
396 struct inet_diag_meminfo {
397 __u32 idiag_rmem;
398 __u32 idiag_wmem;
399 __u32 idiag_fmem;
400 __u32 idiag_tmem;
401 };
402 .EE
403 .in
404 .IP
405 The fields of this structure are as follows:
406 .RS
407 .TP 12
408 .I idiag_rmem
409 The amount of data in the receive queue.
410 .TP
411 .I idiag_wmem
412 The amount of data that is queued by TCP but not yet sent.
413 .TP
414 .I idiag_fmem
415 The amount of memory scheduled for future use (TCP only).
416 .TP
417 .I idiag_tmem
418 The amount of data in send queue.
419 .RE
420 .TP
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".
424 .TP
425 .B INET_DIAG_INFO
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" .
429 .TP
430 .B INET_DIAG_CONG
431 The payload associated with this attribute is a string that describes the
432 congestion control algorithm used.
433 For TCP sockets only.
434 .RE
435 .TP
436 .I pad
437 This should be set to 0.
438 .TP
439 .I idiag_states
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.
443 .TP
444 .I id
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.
450 .P
451 The fields of
452 .I "struct inet_diag_sockid"
453 are as follows:
454 .TP
455 .I idiag_sport
456 The source port.
457 .TP
458 .I idiag_dport
459 The destination port.
460 .TP
461 .I idiag_src
462 The source address.
463 .TP
464 .I idiag_dst
465 The destination address.
466 .TP
467 .I idiag_if
468 The interface number the socket is bound to.
469 .TP
470 .I idiag_cookie
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.
475 .P
476 The response to a query for IPv4 or IPv6 sockets is represented as an array of
477 .P
478 .in +4n
479 .EX
480 struct inet_diag_msg {
481 __u8 idiag_family;
482 __u8 idiag_state;
483 __u8 idiag_timer;
484 __u8 idiag_retrans;
485 \&
486 struct inet_diag_sockid id;
487 \&
488 __u32 idiag_expires;
489 __u32 idiag_rqueue;
490 __u32 idiag_wqueue;
491 __u32 idiag_uid;
492 __u32 idiag_inode;
493 };
494 .EE
495 .in
496 .P
497 followed by netlink attributes.
498 .P
499 The fields of this structure are as follows:
500 .TP
501 .I idiag_family
502 This is the same field as in
503 .IR "struct inet_diag_req_v2" .
504 .TP
505 .I idiag_state
506 This denotes socket state as in
507 .IR "struct inet_diag_req_v2" .
508 .TP
509 .I idiag_timer
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:
513 .IP
514 .PD 0
515 .RS 12
516 .TP
517 .B 0
518 no timer is active
519 .TP
520 .B 1
521 a retransmit timer
522 .TP
523 .B 2
524 a keep-alive timer
525 .TP
526 .B 3
527 a TIME_WAIT timer
528 .TP
529 .B 4
530 a zero window probe timer
531 .RE
532 .PD
533 .IP
534 For non-TCP sockets, this field is set to 0.
535 .TP
536 .I idiag_retrans
537 For
538 .I idiag_timer
539 values 1, 2, and 4, this field contains the number of retransmits.
540 For other
541 .I idiag_timer
542 values, this field is set to 0.
543 .TP
544 .I idiag_expires
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.
548 .TP
549 .I idiag_rqueue
550 For listening sockets:
551 the number of pending connections.
552 .IP
553 For other sockets:
554 the amount of data in the incoming queue.
555 .TP
556 .I idiag_wqueue
557 For listening sockets:
558 the backlog length.
559 .IP
560 For other sockets:
561 the amount of memory available for sending.
562 .TP
563 .I idiag_uid
564 This is the socket owner UID.
565 .TP
566 .I idiag_inode
567 This is the socket inode number.
568 .\"
569 .SS Socket memory information
570 The payload associated with
571 .B UNIX_DIAG_MEMINFO
572 and
573 .B INET_DIAG_SKMEMINFO
574 netlink attributes is an array of the following __u32 values:
575 .TP
576 .B SK_MEMINFO_RMEM_ALLOC
577 The amount of data in receive queue.
578 .TP
579 .B SK_MEMINFO_RCVBUF
580 The receive socket buffer as set by
581 .BR SO_RCVBUF .
582 .TP
583 .B SK_MEMINFO_WMEM_ALLOC
584 The amount of data in send queue.
585 .TP
586 .B SK_MEMINFO_SNDBUF
587 The send socket buffer as set by
588 .BR SO_SNDBUF .
589 .TP
590 .B SK_MEMINFO_FWD_ALLOC
591 The amount of memory scheduled for future use (TCP only).
592 .TP
593 .B SK_MEMINFO_WMEM_QUEUED
594 The amount of data queued by TCP, but not yet sent.
595 .TP
596 .B SK_MEMINFO_OPTMEM
597 The amount of memory allocated for the socket's service needs (e.g., socket
598 filter).
599 .TP
600 .B SK_MEMINFO_BACKLOG
601 The amount of packets in the backlog (not yet processed).
602 .SH VERSIONS
603 .B NETLINK_INET_DIAG
604 was introduced in Linux 2.6.14 and supported
605 .B AF_INET
606 and
607 .B AF_INET6
608 sockets only.
609 In Linux 3.3, it was renamed to
610 .B NETLINK_SOCK_DIAG
611 and extended to support
612 .B AF_UNIX
613 sockets.
614 .P
615 .B UNIX_DIAG_MEMINFO
616 and
617 .B INET_DIAG_SKMEMINFO
618 were introduced in Linux 3.6.
619 .SH STANDARDS
620 Linux.
621 .SH EXAMPLES
622 The following example program prints inode number, peer's inode number,
623 and name of all UNIX domain sockets in the current namespace.
624 .P
625 .EX
626 #include <errno.h>
627 #include <stdio.h>
628 #include <string.h>
629 #include <unistd.h>
630 #include <sys/socket.h>
631 #include <sys/un.h>
632 #include <linux/netlink.h>
633 #include <linux/rtnetlink.h>
634 #include <linux/sock_diag.h>
635 #include <linux/unix_diag.h>
636 \&
637 static int
638 send_query(int fd)
639 {
640 struct sockaddr_nl nladdr = {
641 .nl_family = AF_NETLINK
642 };
643 struct
644 {
645 struct nlmsghdr nlh;
646 struct unix_diag_req udr;
647 } req = {
648 .nlh = {
649 .nlmsg_len = sizeof(req),
650 .nlmsg_type = SOCK_DIAG_BY_FAMILY,
651 .nlmsg_flags = NLM_F_REQUEST | NLM_F_DUMP
652 },
653 .udr = {
654 .sdiag_family = AF_UNIX,
655 .udiag_states = \-1,
656 .udiag_show = UDIAG_SHOW_NAME | UDIAG_SHOW_PEER
657 }
658 };
659 struct iovec iov = {
660 .iov_base = &req,
661 .iov_len = sizeof(req)
662 };
663 struct msghdr msg = {
664 .msg_name = &nladdr,
665 .msg_namelen = sizeof(nladdr),
666 .msg_iov = &iov,
667 .msg_iovlen = 1
668 };
669 \&
670 for (;;) {
671 if (sendmsg(fd, &msg, 0) < 0) {
672 if (errno == EINTR)
673 continue;
674 \&
675 perror("sendmsg");
676 return \-1;
677 }
678 \&
679 return 0;
680 }
681 }
682 \&
683 static int
684 print_diag(const struct unix_diag_msg *diag, unsigned int len)
685 {
686 if (len < NLMSG_LENGTH(sizeof(*diag))) {
687 fputs("short response\[rs]n", stderr);
688 return \-1;
689 }
690 if (diag\->udiag_family != AF_UNIX) {
691 fprintf(stderr, "unexpected family %u\[rs]n", diag\->udiag_family);
692 return \-1;
693 }
694 \&
695 unsigned int rta_len = len \- NLMSG_LENGTH(sizeof(*diag));
696 unsigned int peer = 0;
697 size_t path_len = 0;
698 char path[sizeof(((struct sockaddr_un *) 0)\->sun_path) + 1];
699 \&
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) {
703 case UNIX_DIAG_NAME:
704 if (!path_len) {
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]\[rs]0\[aq];
710 }
711 break;
712 \&
713 case UNIX_DIAG_PEER:
714 if (RTA_PAYLOAD(attr) >= sizeof(peer))
715 peer = *(unsigned int *) RTA_DATA(attr);
716 break;
717 }
718 }
719 \&
720 printf("inode=%u", diag\->udiag_ino);
721 \&
722 if (peer)
723 printf(", peer=%u", peer);
724 \&
725 if (path_len)
726 printf(", name=%s%s", *path ? "" : "@",
727 *path ? path : path + 1);
728 \&
729 putchar(\[aq]\[rs]n\[aq]);
730 return 0;
731 }
732 \&
733 static int
734 receive_responses(int fd)
735 {
736 long buf[8192 / sizeof(long)];
737 struct sockaddr_nl nladdr;
738 struct iovec iov = {
739 .iov_base = buf,
740 .iov_len = sizeof(buf)
741 };
742 int flags = 0;
743 \&
744 for (;;) {
745 struct msghdr msg = {
746 .msg_name = &nladdr,
747 .msg_namelen = sizeof(nladdr),
748 .msg_iov = &iov,
749 .msg_iovlen = 1
750 };
751 \&
752 ssize_t ret = recvmsg(fd, &msg, flags);
753 \&
754 if (ret < 0) {
755 if (errno == EINTR)
756 continue;
757 \&
758 perror("recvmsg");
759 return \-1;
760 }
761 if (ret == 0)
762 return 0;
763 \&
764 if (nladdr.nl_family != AF_NETLINK) {
765 fputs("!AF_NETLINK\[rs]n", stderr);
766 return \-1;
767 }
768 \&
769 const struct nlmsghdr *h = (struct nlmsghdr *) buf;
770 \&
771 if (!NLMSG_OK(h, ret)) {
772 fputs("!NLMSG_OK\[rs]n", stderr);
773 return \-1;
774 }
775 \&
776 for (; NLMSG_OK(h, ret); h = NLMSG_NEXT(h, ret)) {
777 if (h\->nlmsg_type == NLMSG_DONE)
778 return 0;
779 \&
780 if (h\->nlmsg_type == NLMSG_ERROR) {
781 const struct nlmsgerr *err = NLMSG_DATA(h);
782 \&
783 if (h\->nlmsg_len < NLMSG_LENGTH(sizeof(*err))) {
784 fputs("NLMSG_ERROR\[rs]n", stderr);
785 } else {
786 errno = \-err\->error;
787 perror("NLMSG_ERROR");
788 }
789 \&
790 return \-1;
791 }
792 \&
793 if (h\->nlmsg_type != SOCK_DIAG_BY_FAMILY) {
794 fprintf(stderr, "unexpected nlmsg_type %u\[rs]n",
795 (unsigned) h\->nlmsg_type);
796 return \-1;
797 }
798 \&
799 if (print_diag(NLMSG_DATA(h), h\->nlmsg_len))
800 return \-1;
801 }
802 }
803 }
804 \&
805 int
806 main(void)
807 {
808 int fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_SOCK_DIAG);
809 \&
810 if (fd < 0) {
811 perror("socket");
812 return 1;
813 }
814 \&
815 int ret = send_query(fd) || receive_responses(fd);
816 \&
817 close(fd);
818 return ret;
819 }
820 .EE
821 .SH SEE ALSO
822 .BR netlink (3),
823 .BR rtnetlink (3),
824 .BR netlink (7),
825 .BR tcp (7)