From: Pavel Emelyanov <xemul@xxxxxxxxxxxxx> Cowritten-by: Dmitry V. Levin <ldv@xxxxxxxxxxxx> Signed-off-by: Pavel Emelyanov <xemul@xxxxxxxxxxxxx> Signed-off-by: Dmitry V. Levin <ldv@xxxxxxxxxxxx> --- man7/sock_diag.7 | 632 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 632 insertions(+) create mode 100644 man7/sock_diag.7 diff --git a/man7/sock_diag.7 b/man7/sock_diag.7 new file mode 100644 index 0000000..d1be9cf --- /dev/null +++ b/man7/sock_diag.7 @@ -0,0 +1,632 @@ +.\" Copyright (c) 2016 Pavel Emelyanov <xemul@xxxxxxxxxxxxx> +.\" Copyright (c) 2016 Dmitry V. Levin <ldv@xxxxxxxxxxxx> +.\" +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, see +.\" <http://www.gnu.org/licenses/>. +.\" %%%LICENSE_END +.TH SOCK_DIAG 7 2016-03-14 "Linux" "Linux Programmer's Manual" +.SH NAME +sock_diag \- querying information about sockets +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <linux/sock_diag.h> +.BR "#include <linux/unix_diag.h>" " /* for UNIX domain sockets */" +.BR "#include <linux/inet_diag.h>" " /* for IPv4 and IPv6 sockets */" + +.BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);" +.fi +.SH DESCRIPTION +The sock_diag netlink subsystem provides a mechanism for querying information +about sockets of various protocol families from the kernel. This subsystem +can be used to query information about individual sockets or request a list of +those. + +In the request the caller can specify the additional information it would +like to query about the socket, e.g. memory info or family-specific stuff. + +When requesting a list of sockets, the caller can specify filters +that would be applied by the kernel to select a subset of sockets to report. +For now there's only the ability to filter sockets by state (connected, +listening, etc.) + +Note that sock_diag reports only those sockets that have a name, +i.e. either bound explicitly with +.BR bind (2) +or auto-bound ones (e.g. connected). This is the same set of sockets that +is available via +.IR /proc/net/unix , +.IR /proc/net/tcp , +.IR /proc/net/udp , +etc. + +.SS Request +The request starts with +.I "struct nlmsghdr" +header that has +.I nlmsg_type +field set to +.BR SOCK_DIAG_BY_FAMILY . +It is followed by a protocol family specific header that starts with a common +part shared by all protocol families: + +.in +4n +.nf +struct sock_diag_req { + __u8 sdiag_family; + __u8 sdiag_protocol; +}; +.fi +.in +.PP +The fields of this structure are as follows: +.TP +.I sdiag_family +The protocol family of querying sockets. It should be set to the appropriate +.B PF_* +constant. +.TP +.I sdiag_protocol +Depends on +.IR sdiag_family . +It should be set to the appropriate +.B IPPROTO_* +constant for +.B PF_INET +and +.BR PF_INET6, +and to 0 otherwise. +.PP +If +.I nlmsg_flags +field of the +.I "struct nlmsghdr" +header has +.BR NLM_F_DUMP +flag set, then a list of sockets is being requested, +otherwise it is a query about an individual socket. + +.SS Response +The response starts with +.I "struct nlmsghdr" +header and is followed by an array of family-specific objects. +The array is to be accessed with the standard +.B NLMSG_* +macros from +.BR netlink (3) +API. +.PP +Each object is the NLA (netlink attributes) list that is to be accessed +with the +.B RTA_* +macros from +.BR rtnetlink (3) +API. + +.SS UNIX domain sockets +For UNIX domain sockets the request is represented in the following structure: + +.in +4n +.nf +struct unix_diag_req { + __u8 sdiag_family; + __u8 sdiag_protocol; + __u16 pad; + __u32 udiag_states; + __u32 udiag_ino; + __u32 udiag_show; + __u32 udiag_cookie[2]; +}; +.fi +.in +.PP +The fields of this structure are as follows: +.TP +.I sdiag_family +This is a protocol family, it should be set to +.BR PF_UNIX . +.PP +.I sdiag_protocol +.PD 0 +.TP +.PD +.I pad +These fields should be set to 0. +.TP +.I udiag_states +This is a bit mask that defines a filter of sockets states. +Only those sockets whose states are in this mask will be reported. +Ignored when querying for an individual socket. +Supported values are: +.PD 0 +.RS +.IP "" 2 +1 << +.B TCP_ESTABLISHED +.IP +1 << +.B TCP_LISTEN +.RE +.PD +.TP +.I udiag_ino +This is an inode number when querying for an individual socket. +Ignored for a bulk dump. +.TP +.I udiag_show +This is a set of flags defining which information to report. +Each requested info is reported back as a netlink attribute as described +below: +.RS +.IP "" 2 +.B UDIAG_SHOW_NAME +.RS 4 +The attribute reported in answer to this request is +.BR UNIX_DIAG_NAME . +The payload associated with this attribute is the name of the socket +to which it was bound (a sequence of bytes up to +.B UNIX_PATH_MAX +length). +.RE +.IP "" 2 +.B UDIAG_SHOW_VFS +.RS 4 +The attribute reported in answer to this request is +.BR UNIX_DIAG_VFS . +The payload associated with this attribute is represented in the following +structure: + +.in +4n +.nf +struct unix_diag_vfs { + __u32 udiag_vfs_dev; + __u32 udiag_vfs_ino; +}; +.fi +.in + +The fields of this structure are as follows: +.PD 0 +.RS 2 +.IP "" 2 +.I udiag_vfs_dev +The device number of the corresponding on-disk socket node. +.IP +.I udiag_vfs_ino +The inode number of the corresponding on-disk socket node. +.RE +.PD +.RE +.IP +.B UDIAG_SHOW_PEER +.RS 4 +The attribute reported in answer to this request is +.BR UNIX_DIAG_PEER . +The payload associated with this attribute is a __u32 value +which is the peer's inode number. +This attribute is reported for connected sockets only. +.RE +.IP +.B UDIAG_SHOW_ICONS +.RS 4 +The attribute reported in answer to this request is +.BR UNIX_DIAG_ICONS . +The payload associated with this attribute is an array of __u32 values +which are inode numbers of sockets that has passed the +.BR connect (2) +call, but hasn't been processed with +.BR accept (2) +yet. This attribute is reported for listening sockets only. +.RE +.IP +.B UDIAG_SHOW_RQLEN +.RS 4 +The attribute reported in answer to this request is +.BR UNIX_DIAG_RQLEN . +The payload associated with this attribute is represented in the following +structure: + +.in +4n +.nf +struct unix_diag_rqlen { + __u32 udiag_rqueue; + __u32 udiag_wqueue; +}; +.fi +.in + +The fields of this structure are as follows: +.PD 0 +.RS 2 +.IP "" 2 +.I udiag_rqueue +.RS 6 +.IP "listening sockets:" 2 +The number of pending connections which equals to +.B UNIX_DIAG_ICONS +array length. +.IP "established sockets:" +The amount of data in incoming queue. +.RE +.IP +.I udiag_wqueue +.RS 6 +.IP "listening sockets:" 2 +The backlog length which equals to the value passed as the second argument to +.BR listen (2). +.IP "established sockets:" +The amount of memory available for sending. +.RE +.RE +.PD +.RE +.IP +.B UDIAG_SHOW_MEMINFO +.RS 4 +The attribute reported in answer to this request is +.BR UNIX_DIAG_MEMINFO . +The payload associated with this attribute is an array of __u32 values +described below in "Socket memory information" subsection. +.RE +.IP +.RE +.RS +The following attributes are reported back without any specific request: +.IP "" 2 +.BR UNIX_DIAG_SHUTDOWN . +The payload associated with this attribute is __u8 value which represents +bits of +.BR shutdown (2) +state. +.RE +.TP +.I udiag_cookie +This is service field, both its cells should be set to \-1. +.PP +The response to a query for UNIX domain sockets is represented as an array of + +.in +4n +.nf +struct unix_diag_msg { + __u8 udiag_family; + __u8 udiag_type; + __u8 udiag_state; + __u8 pad; + __u32 udiag_ino; + __u32 udiag_cookie[2]; +}; +.fi +.in + +followed by netlink attributes. +.PP +The fields of this structure are as follows: +.TP +.I udiag_type +This is set to one of the following constants: +.PD 0 +.RS +.IP "" 2 +.B SOCK_PACKET +.IP +.B SOCK_STREAM +.IP +.B SOCK_SEQPACKET +.RE +.PD +.TP +.I udiag_state +This is set to one of the following constants: +.PD 0 +.RS +.IP "" 2 +.B TCP_LISTEN +.IP +.B TCP_ESTABLISHED +.RE +.PD +.TP +.I udiag_ino +This is the socket inode number. +.PP +.I udiag_family +.PD 0 +.PP +.I pad +.TP +.I udiag_cookie +These fields have the same meaning as in +.IR "struct unix_diag_req" . +.PD + +.SS IPv4 and IPv6 sockets +For IPv4 and IPv6 sockets the request is represented in the following structure: + +.in +4n +.nf +struct inet_diag_req_v2 { + __u8 sdiag_family; + __u8 sdiag_protocol; + __u8 idiag_ext; + __u8 pad; + __u32 idiag_states; + struct inet_diag_sockid id; +}; +.fi +.in + +where +.I "struct inet_diag_sockid" +is defined as follows: + +.in +4n +.nf +struct inet_diag_sockid { + __be16 idiag_sport; + __be16 idiag_dport; + __be32 idiag_src[4]; + __be32 idiag_dst[4]; + __u32 idiag_if; + __u32 idiag_cookie[2]; +}; +.fi +.in +.PP +The fields of +.I "struct inet_diag_req_v2" +are as follows: +.TP +.I sdiag_family +This should be set to either +.B PF_INET +or +.B PF_INET6 +for +.B IPv4 +or +.B IPv6 +sockets respectively. +.TP +.I sdiag_protocol +This should be set to one of the following constants: +.PD 0 +.RS +.IP "" 2 +.B IPPROTO_TCP +.IP +.B IPPROTO_UDP +.IP +.B IPPROTO_UDPLITE +.RE +.PD +.TP +.I idiag_ext +This is a set of flags defining which extended information to report. +Each requested info is reported back as a netlink attribute as described +below: +.RS +.IP "" 2 +.B INET_DIAG_TOS +The payload associated with this attribute is a __u8 value +which is the TOS of the socket. +.IP +.B INET_DIAG_TCLASS +The payload associated with this attribute is a __u8 value +which is the TClass of the socket. IPv6 sockets only. +For LISTEN and CLOSE sockets this is followed by +.B INET_DIAG_SKV6ONLY +attribute with associated __u8 payload value meaning whether the socket +is IPv6-only or not. +.IP +.B INET_DIAG_MEMINFO +The payload associated with this attribute is represented in the following +structure: + +.in +4n +.nf +struct inet_diag_meminfo { + __u32 idiag_rmem; + __u32 idiag_wmem; + __u32 idiag_fmem; + __u32 idiag_tmem; +}; +.fi +.in + +The fields of this structure are as follows: +.PD 0 +.RS 2 +.IP "" 2 +.I idiag_rmem +The amount of data in the receive queue. +.IP +.I idiag_wmem +The amount of data that is queued by TCP but not yet sent. +.IP +.I idiag_fmem +The amount of memory scheduled for future use (TCP only). +.IP +.I idiag_tmem +The amount of data in send queue. +.RE +.PD +.IP +.B INET_DIAG_SKMEMINFO +The payload associated with this attribute is an array of __u32 values +described below in "Socket memory information" subsection. +.IP +.B INET_DIAG_INFO +The payload associated with this attribute is protocol specific. +For TCP sockets it is an object of type +.IR "struct tcp_info" . +.IP +.B INET_DIAG_CONG +The payload associated with this attribute is a string that describes the +congestion control algorithm used. For TCP sockets only. +.RE +.TP +.I pad +This should be set to 0. +.TP +.I idiag_states +This is a bit mask that defines a filter of sockets states. +Only those sockets whose states are in this mask will be reported. +Ignored when querying for an individual socket. +.TP +.I id +This is a socket id object that is used in dump requests, in queries +about individual sockets, and is reported back in each response. +Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified +using addresses and ports. All values are in network byte order. +.PP +The fields of +.I "struct inet_diag_sockid" +are as follows: +.TP +.I idiag_sport +The source port. +.TP +.I idiag_dport +The destination port. +.TP +.I idiag_src +The source address. +.TP +.I idiag_dst +The destination address. +.TP +.I idiag_if +The interface number the socket is bound to. +.TP +.I idiag_cookie +This is a service field, both its cells should be set to \-1. +.PP +The response to a query for IPv4 or IPv6 sockets is represented as an array of + +.in +4n +.nf +struct inet_diag_msg { + __u8 idiag_family; + __u8 idiag_state; + __u8 idiag_timer; + __u8 idiag_retrans; + + struct inet_diag_sockid id; + + __u32 idiag_expires; + __u32 idiag_rqueue; + __u32 idiag_wqueue; + __u32 idiag_uid; + __u32 idiag_inode; +}; +.fi +.in + +followed by netlink attributes. +.PP +The fields of this structure are as follows: +.TP +.I idiag_family +This is the same field as in +.IR "struct inet_diag_req_v2" . +.TP +.I idiag_state +This denotes socket state as in +.IR "struct inet_diag_req_v2" . +.PP +.I idiag_timer +.PD 0 +.PP +.I idiag_retrans +.TP +.I idiag_expires +These fields are TCP-only and represent the timeout that is currently +in action for particular TCP state (0 for established sockets). +.PD +.TP +.I idiag_rqueue +.RS 7 +.IP "listening sockets:" 2 +The number of pending connections. +.IP "other sockets:" +The amount of data in incoming queue. +.RE +.TP +.I idiag_wqueue +.RS 7 +.IP "listening sockets:" 2 +The backlog length. +.IP "other sockets:" +The amount of memory available for sending. +.RE +.TP +.I idiag_uid +This is the socket owner UID. +.TP +.I idiag_inode +This is the socket inode number. + +.SS Socket memory information +The payload associated with +.B UNIX_DIAG_MEMINFO +and +.BR INET_DIAG_SKMEMINFO +netlink attributes is an array of the following __u32 values: +.TP +.B SK_MEMINFO_RMEM_ALLOC +The amount of data in receive queue. +.TP +.B SK_MEMINFO_RCVBUF +The receive socket buffer as set by +.BR SO_RCVBUF . +.TP +.B SK_MEMINFO_WMEM_ALLOC +The amount of data in send queue. +.TP +.B SK_MEMINFO_SNDBUF +The send socket buffer as set by +.BR SO_SNDBUF . +.TP +.B SK_MEMINFO_FWD_ALLOC +The amount of memory scheduled for future use (TCP only). +.TP +.B SK_MEMINFO_WMEM_QUEUED +The amount of data queued by TCP, but not yet sent. +.TP +.B SK_MEMINFO_OPTMEM +The amount of memory allocated for socket's service needs (e.g. socket +filter). +.TP +.B SK_MEMINFO_BACKLOG +The amount of packets in the backlog (not yet processed). +.SH CONFORMING TO +The NETLINK_SOCK_DIAG API is Linux-specific. +.SH VERSIONS +.B NETLINK_SOCK_DIAG +was introduced in Linux 3.3. +.PP +.B UNIX_DIAG_MEMINFO +and +.BR INET_DIAG_SKMEMINFO +were introduced in Linux 3.6. +.SH SEE ALSO +.BR netlink (3), +.BR rtnetlink (3), +.BR netlink (7) -- ldv -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
