Hello Dmitry, Pavel, Ping! Cheers, Michael On 04/04/2016 10:34 AM, Michael Kerrisk (man-pages) wrote: > Hello Dmitry > > Thanks for taking the time to work on this! > > I will probably have more comments, for a future draft, but here are > a few initial comments. Could you take a look and send a new draft? > > On 03/16/2016 06:25 AM, Dmitry V. Levin wrote: >> 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. > > Sorry, it's not clear what "those" refers to. Could you replace with a noun? > >> + >> +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. > > s/query/obtain/ > >> + >> +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 . > > I think it might be useful to either show the nlmsghdr structure here, or > add a note to tell the reader that this structure defintion is hown in > netlink(7). > >> +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 > > The meaning of "querying sockets" is unclear. Can you reword/elaborate? > >> +.B PF_* > > AF_* constant, I would say. POSIX doesn't talk about PF*, and in practice > there's always a one to one relationship between AF_* and PF_*, so all other > man pages use AF_*. > >> +constant. >> +.TP >> +.I sdiag_protocol >> +Depends on >> +.IR sdiag_family . >> +It should be set to the appropriate >> +.B IPPROTO_* >> +constant for >> +.B PF_INET > > AF_... > >> +and >> +.BR PF_INET6, > > AF_... > >> +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. > > The meaning of "bulk dump" is not clear. > >> +.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. > > What does "service field" mean? I think this needs to be clarified. > >> +.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 > > Replace the last line with > > .TP > >> +.B INET_DIAG_TOS >> +The payload associated with this attribute is a __u8 value >> +which is the TOS of the socket. >> +.IP > > .TP > >> +.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 > > .TP > >> +.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 > > Delete previous line. > >> +.RS 2 > > Make the last line > > .RS > >> +.IP "" 2 > > Change the last line to > > .TP 12 > >> +.I idiag_rmem >> +The amount of data in the receive queue. >> +.IP > > .TP > >> +.I idiag_wmem >> +The amount of data that is queued by TCP but not yet sent. >> +.IP > > .TP > >> +.I idiag_fmem >> +The amount of memory scheduled for future use (TCP only). >> +.IP > > .TP > >> +.I idiag_tmem >> +The amount of data in send queue. >> +.RE >> +.PD > > Remove previous line > >> +.IP > > .TP > >> +.B INET_DIAG_SKMEMINFO >> +The payload associated with this attribute is an array of __u32 values >> +described below in "Socket memory information" subsection. >> +.IP > > .TP > >> +.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 > > .TP > >> +.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. > > Again, I think the meaning of "service" filed needs to be clarified. > >> +.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). > > Can you elaborate with an example of a state that has a timeout. > (Is this just TIME_WAIT, or others also?) > >> +.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) > > In the next iteration, I think it would be simplest to just include > the example program in the same patch. > > Thanks, > > Michael > > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- 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
