: unix.7: mentioning SOCK_STREAM socket for ioctl_type of ioctl function

PATCH In review Jan Chaloupka 2 participants 6 messages Jul 23, 2014 – Oct 18, 2014 2 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Jan Chaloupka

author

2014-07-23 10:54 UTC #0 lore raw

PATCH 1/1 : unix.7: mentioning SOCK_STREAM socket for ioctl_type of ioctl function

From https://bugzilla.redhat.com/show_bug.cgi?id=1110401.

unix.7 is not clear about socket type of ioctl_type argument of ioctl function. The description of SIOCINQ is applicable only for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives correct description of SIOCINQ.

---
 man7/unix.7 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

man7/unix.7 +9 -2

index b0ade5b..6bcc8ba 100644
@@ -299,7 +299,9 @@ The correct syntax is:
 can be:
 .TP
 .B SIOCINQ
-Returns the amount of queued unread data in the receive buffer.
+For
+.B SOCK_STREAM
+socket the function returns the amount of queued unread data in the receive buffer.
 The socket must not be in LISTEN state, otherwise an error
 .RB ( EINVAL )
 is returned.

@@ -319,6 +321,10 @@ defined in
 .\" That number is normally larger than the number of bytes of pending
 .\" output. Since this info is, from userland's point of view, imprecise,
 .\" and it may well change, probably best not to document this now.
+For
+.B SOCK_DGRAM
+socket, see
+.BR udp (7).
 .SH ERRORS
 .TP
 .B EADDRINUSE

@@ -450,4 +456,5 @@ see
 .BR cmsg (3),
 .BR capabilities (7),
 .BR credentials (7),
-.BR socket (7)
+.BR socket (7),
+.BR udp (7)

Signature · 5 lines

1.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Jan Chaloupka

author

2014-08-14 13:40 UTC #2 lore raw

ping

Quoted 43 lines · Jan Chaloupka

From https://bugzilla.redhat.com/show_bug.cgi?id=1110401.
unix.7 is not clear about socket type of ioctl_type argument of ioctl function. The description of SIOCINQ is applicable only for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives correct description of SIOCINQ.
---
 man7/unix.7 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)
man7/unix.7 +3 -1
index b0ade5b..6bcc8ba 100644
@@ -299,7 +299,9 @@ The correct syntax is:
 can be:
 .TP
 .B SIOCINQ
-Returns the amount of queued unread data in the receive buffer.
+For
+.B SOCK_STREAM
+socket the function returns the amount of queued unread data in the 
receive buffer.
The socket must not be in LISTEN state, otherwise an error .RB ( EINVAL )
is returned.
man7/unix.7 +4 -0
@@ -319,6 +321,10 @@ defined in
 .\" That number is normally larger than the number of bytes of pending
 .\" output. Since this info is, from userland's point of view, 
 imprecise,
 .\" and it may well change, probably best not to document this now.
+For
+.B SOCK_DGRAM
+socket, see
+.BR udp (7).
 .SH ERRORS
 .TP
.B EADDRINUSE
man7/unix.7 +2 -1
@@ -450,4 +456,5 @@ see
 .BR cmsg (3),
 .BR capabilities (7),
 .BR credentials (7),
-.BR socket (7)
+.BR socket (7),
+.BR udp (7)

Signature · 11 lines

Jan Chaloupka
------------------------------
* Software Engineer          *
* ENG Base Operating Systems *
* Red Hat Czech, s. r. o.    *
* UTC+1 (CET), jchaloup      *

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Jan Chaloupka

author

2014-09-09 07:05 UTC #3 lore raw

In reply to a message not in the archive

ping

Quoted 37 lines · Jan Chaloupka

From https://bugzilla.redhat.com/show_bug.cgi?id=1110401.
unix.7 is not clear about socket type of ioctl_type argument of ioctl function. The description of SIOCINQ is applicable only for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives correct description of SIOCINQ.
---
 man7/unix.7 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)
man7/unix.7 +3 -1
index b0ade5b..6bcc8ba 100644
@@ -299,7 +299,9 @@ The correct syntax is:
 can be:
 .TP
 .B SIOCINQ
-Returns the amount of queued unread data in the receive buffer.
+For
+.B SOCK_STREAM
+socket the function returns the amount of queued unread data in the 
receive buffer.
The socket must not be in LISTEN state, otherwise an error .RB ( EINVAL )
is returned.
man7/unix.7 +4 -0
@@ -319,6 +321,10 @@ defined in
 .\" That number is normally larger than the number of bytes of pending
 .\" output. Since this info is, from userland's point of view, 
 imprecise,
 .\" and it may well change, probably best not to document this now.
+For
+.B SOCK_DGRAM
+socket, see
+.BR udp (7).
 .SH ERRORS
 .TP
.B EADDRINUSE

man7/unix.7 see · line 460

Quoted 6 lines

man7/unix.7 +2 -1

@@ -450,4 +456,5 @@ see
 .BR cmsg (3),
 .BR capabilities (7),
 .BR credentials (7),
-.BR socket (7)
+.BR socket (7),
+.BR udp (7)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Jan Chaloupka

author

2014-10-16 10:51 UTC #4 lore raw

In reply to a message not in the archive

ping

Quoted 37 lines · Jan Chaloupka

From https://bugzilla.redhat.com/show_bug.cgi?id=1110401.
unix.7 is not clear about socket type of ioctl_type argument of ioctl function. The description of SIOCINQ is applicable only for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives correct description of SIOCINQ.
---
 man7/unix.7 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)
man7/unix.7 +3 -1
index b0ade5b..6bcc8ba 100644
@@ -299,7 +299,9 @@ The correct syntax is:
 can be:
 .TP
 .B SIOCINQ
-Returns the amount of queued unread data in the receive buffer.
+For
+.B SOCK_STREAM
+socket the function returns the amount of queued unread data in the 
receive buffer.
The socket must not be in LISTEN state, otherwise an error .RB ( EINVAL )
is returned.
man7/unix.7 +4 -0
@@ -319,6 +321,10 @@ defined in
 .\" That number is normally larger than the number of bytes of pending
 .\" output. Since this info is, from userland's point of view, 
 imprecise,
 .\" and it may well change, probably best not to document this now.
+For
+.B SOCK_DGRAM
+socket, see
+.BR udp (7).
 .SH ERRORS
 .TP
.B EADDRINUSE

man7/unix.7 see · line 460

Quoted 6 lines

man7/unix.7 +2 -1

@@ -450,4 +456,5 @@ see
 .BR cmsg (3),
 .BR capabilities (7),
 .BR credentials (7),
-.BR socket (7)
+.BR socket (7),
+.BR udp (7)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael Kerrisk (man-pages)

2014-10-17 14:35 UTC #5 lore raw

In reply to a message not in the archive

Hello Jan,

Quoted 6 lines · Jan Chaloupka

From https://bugzilla.redhat.com/show_bug.cgi?id=1110401.
unix.7 is not clear about socket type of ioctl_type argument of ioctl function. The description of SIOCINQ is applicable only for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives correct description of SIOCINQ.

Again, the intent of this patch seems correct, but some details need fixing, I think.

Quoted 21 lines

---
  man7/unix.7 | 11 +++++++++--
  1 file changed, 9 insertions(+), 2 deletions(-)

man7/unix.7 +3 -1

index b0ade5b..6bcc8ba 100644
@@ -299,7 +299,9 @@ The correct syntax is:
  can be:
  .TP
  .B SIOCINQ
-Returns the amount of queued unread data in the receive buffer.
+For
+.B SOCK_STREAM
+socket the function returns the amount of queued unread data in the

receive buffer.
The socket must not be in LISTEN state, otherwise an error .RB ( EINVAL )
is returned.

man7/unix.7 defined in · line 327

Quoted 7 lines

man7/unix.7 +4 -0

@@ -319,6 +321,10 @@ defined in
  .\" That number is normally larger than the number of bytes of pending
  .\" output. Since this info is, from userland's point of view, imprecise,
  .\" and it may well change, probably best not to document this now.
+For
+.B SOCK_DGRAM
+socket, see
+.BR udp (7).

It feels a bit odd to simply point at udp(7), since that describes another socket domain (Internet). Maybe say something like:

For SOCK_DRAM sockets, the returned value is the same as for Internet domain datagram sockets; see udp(7).

What do you think?

Cheers,

Michael

Quoted 11 lines

man7/unix.7 +2 -1

  .SH ERRORS
  .TP
  .B EADDRINUSE

@@ -450,4 +456,5 @@ see
  .BR cmsg (3),
  .BR capabilities (7),
  .BR credentials (7),
-.BR socket (7)
+.BR socket (7),
+.BR udp (7)

Signature · 7 lines

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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Jan Chaloupka

author

2014-10-18 15:26 UTC #7 lore raw

Quoted 43 lines · Michael Kerrisk (man-pages)

Hello Jan,
Quoted 6 lines · Jan Chaloupka
From https://bugzilla.redhat.com/show_bug.cgi?id=1110401.
unix.7 is not clear about socket type of ioctl_type argument of ioctl function. The description of SIOCINQ is applicable only for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives correct description of SIOCINQ.
Again, the intent of this patch seems correct, but some details need fixing, I think.
Quoted 21 lines
---
   man7/unix.7 | 11 +++++++++--
   1 file changed, 9 insertions(+), 2 deletions(-)
man7/unix.7 +3 -1
index b0ade5b..6bcc8ba 100644
@@ -299,7 +299,9 @@ The correct syntax is:
   can be:
   .TP
   .B SIOCINQ
-Returns the amount of queued unread data in the receive buffer.
+For
+.B SOCK_STREAM
+socket the function returns the amount of queued unread data in the
receive buffer.
The socket must not be in LISTEN state, otherwise an error .RB ( EINVAL )
is returned.
man7/unix.7 defined in · line 327
Quoted 7 lines
man7/unix.7 +4 -0
@@ -319,6 +321,10 @@ defined in
   .\" That number is normally larger than the number of bytes of pending
   .\" output. Since this info is, from userland's point of view, imprecise,
   .\" and it may well change, probably best not to document this now.
+For
+.B SOCK_DGRAM
+socket, see
+.BR udp (7).
It feels a bit odd to simply point at udp(7), since that describes another socket domain (Internet). Maybe say something like:

Quoted 4 lines

For SOCK_DRAM sockets, the returned value is the same as for Internet domain datagram sockets; see udp(7).
What do you think?

Yeah, you are right. The reason of referring to udp(7) is stated in the patch but not in the man page itself. I agree with this change.

Quoted 4 lines

Cheers,
Michael

Quoted 12 lines

man7/unix.7 see · line 460

Quoted 11 lines

man7/unix.7 +2 -1

   .SH ERRORS
   .TP
   .B EADDRINUSE

@@ -450,4 +456,5 @@ see
   .BR cmsg (3),
   .BR capabilities (7),
   .BR credentials (7),
-.BR socket (7)
+.BR socket (7),
+.BR udp (7)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html