svn commit: r207923 - head/lib/libc/sys

[Christian Brueffer]

Author: brueffer
Date: Tue May 11 17:02:12 2010
New Revision: 207923
URL: http://svn.freebsd.org/changeset/base/207923

Log:
  Document FIONREAD, FIONWRITE and FIONSPACE.
  
  Obtained from:	NetBSD
  Submitted by:	emaste
  MFC after:	1 week

Modified:
  head/lib/libc/sys/ioctl.2

Modified: head/lib/libc/sys/ioctl.2
==============================================================================
--- head/lib/libc/sys/ioctl.2	Tue May 11 17:01:14 2010	(r207922)
+++ head/lib/libc/sys/ioctl.2	Tue May 11 17:02:12 2010	(r207923)
@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 14, 2007
+.Dd May 11, 2010
 .Dt IOCTL 2
 .Os
 .Sh NAME
@@ -80,6 +80,30 @@ Macros and defines used in specifying an
 .Fa request
 are located in the file
 .In sys/ioctl.h .
+.Sh GENERIC IOCTLS
+Some generic ioctls are not implemented for all types of file
+descriptors.
+These include:
+.Bl -tag -width "xxxxxx"
+.It Dv FIONREAD int
+Get the number of bytes that are immediately available for reading.
+.It Dv FIONWRITE int
+Get the number of bytes in the descriptor's send queue.
+These bytes are data which has been written to the descriptor but
+which are being held by the kernel for further processing.
+The nature of the required processing depends on the underlying device.
+For TCP sockets, these bytes have not yet been acknowledged by the
+other side of the connection.
+.It Dv FIONSPACE int
+Get the free space in the descriptor's send queue.
+This value is the size of the send queue minus the number of bytes
+being held in the queue.
+Note: while this value represents the number of bytes that may be
+added to the queue, other resource limitations may cause a write
+not larger than the send queue's space to be blocked.
+One such limitation would be a lack of network buffers for a write
+to a network connection.
+.El
 .Sh RETURN VALUES
 If an error has occurred, a value of -1 is returned and
 .Va errno