unix.7: Document SIOCINQ ioctl() operation

Reported-by: Jim Belton <jim.belton@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/unix.7

@@ -12,7 +12,7 @@
 .\"     address that can appear in the sockaddr_un structure: pathname,
 .\"     unnamed, and abstract.
 .\"
-.TH UNIX  7 2008-12-01 "Linux" "Linux Programmer's Manual"
+.TH UNIX  7 2010-09-10 "Linux" "Linux Programmer's Manual"
 .SH NAME
 unix, AF_UNIX, AF_LOCAL \- Sockets for local
 interprocess communication
@@ -253,6 +253,44 @@ To receive a
 message the
 .B SO_PASSCRED
 option must be enabled on the socket.
+.SS Ioctls
+The following
+.BR ioctl (2)
+calls return information in
+.IR value .
+The correct syntax is:
+.PP
+.RS
+.nf
+.BI int " value";
+.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");"
+.fi
+.RE
+.PP
+.I ioctl_type
+can be:
+.TP
+.B SIOCINQ
+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.
+.B SIOCINQ
+is defined in
+.IR <linux/sockios.h> .
+.\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002,
+.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
+Alternatively,
+you can use the synonymous
+.BR FIONREAD ,
+defined in
+.IR <sys/ioctl.h> .
+.\" SIOCOUTQ also has an effect for UNIX doamin sockets, but not
+.\" quite what userland might expect. It seems to return the number
+.\" of bytes allocated for buffers containing pending output.
+.\" 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.
 .SH ERRORS
 .TP
 .B EADDRINUSE