update: add current options and cross-reference

SCCS-vsn: lib/libc/sys/recv.2 6.10
SCCS-vsn: lib/libc/sys/getsockopt.2 6.8

diff --git a/usr/src/lib/libc/sys/getsockopt.2 b/usr/src/lib/libc/sys/getsockopt.2
index 1a16690..8d3f871 100644 (file)
--- a/usr/src/lib/libc/sys/getsockopt.2
+++ b/usr/src/lib/libc/sys/getsockopt.2
@@ -3,18 +3,18 @@
 .\"
 .\" %sccs.include.redist.man%
 .\"
 .\"
 .\" %sccs.include.redist.man%
 .\"

-.\"     @(#)getsockopt.2       6.7 (Berkeley) %G%
+.\"     @(#)getsockopt.2       6.8 (Berkeley) %G%

 .\"
 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
 .\" All rights reserved.
 .\"
 .\" %sccs.include.redist.man%
 .\"
 .\"
 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
 .\" All rights reserved.
 .\"
 .\" %sccs.include.redist.man%
 .\"

-.\"     @(#)getsockopt.2       6.7 (Berkeley) %G%
+.\"     @(#)getsockopt.2       6.8 (Berkeley) %G%

 .\"
 .Dd 
 .Dt GETSOCKOPT 2
 .\"
 .Dd 
 .Dt GETSOCKOPT 2

-.Os BSD 4.2
+.Os BSD 4.3r

 .Sh NAME
 .Nm getsockopt ,
 .Nm setsockopt
 .Sh NAME
 .Nm getsockopt ,
 .Nm setsockopt


@@ -88,7 +88,7 @@ name; consult the appropriate entries in
 section
 4 of the manual.
 .Pp
 section
 4 of the manual.
 .Pp

-Most socket-level options take an
+Most socket-level options utilize an

 .Fa int
 parameter for
 .Fa optval .
 .Fa int
 parameter for
 .Fa optval .


@@ -103,6 +103,13 @@ parameter, defined in
 .Ao Pa sys/socket.h Ac ,
 which specifies the desired state of the option and the
 linger interval (see below).
 .Ao Pa sys/socket.h Ac ,
 which specifies the desired state of the option and the
 linger interval (see below).

+.Dv SO_SNDTIMEO
+and
+.Dv SO_RCVTIMEO
+use a
+.Fa struct timeval
+parameter, defined in
+.Ao Pa sys/time.h Ac .

 .Pp
 The following options are recognized at the socket level.
 Except as noted, each may be examined with
 .Pp
 The following options are recognized at the socket level.
 Except as noted, each may be examined with


@@ -110,17 +117,21 @@ Except as noted, each may be examined with
 and set with
 .Fn setsockopt .
 .Bl -column SO_OOBINLINE -offset indent
 and set with
 .Fn setsockopt .
 .Bl -column SO_OOBINLINE -offset indent

-.It Dv SO_DEBUG  Ta enables recording of debugging information
-.It Dv SO_REUSEADDR Ta enables local address reuse
-.It Dv SO_KEEPALIVE Ta enables keep connections alive
-.It Dv SO_DONTROUTE Ta enables routing bypass for outgoing messages
-.It Dv SO_LINGER  Ta linger on close if data present
-.It Dv SO_BROADCAST Ta enables permission to transmit broadcast messages
-.It Dv SO_OOBINLINE Ta enables reception of out-of-band data in band
-.It Dv SO_SNDBUF Ta set buffer size for output
-.It Dv SO_RCVBUF Ta set buffer size for input
-.It Dv SO_TYPE Ta get the type of the socket (get only)
-.It Dv SO_ERROR Ta get and clear error on the socket (get only)
+.It Dv SO_DEBUG Ta "enables recording of debugging information"
+.It Dv SO_REUSEADDR Ta "enables local address reuse"
+.It Dv SO_KEEPALIVE Ta "enables keep connections alive"
+.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages"
+.It Dv SO_LINGER  Ta "linger on close if data present"
+.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages"
+.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band"
+.It Dv SO_SNDBUF Ta "set buffer size for output"
+.It Dv SO_RCVBUF Ta "set buffer size for input"
+.It Dv SO_SNDLOWAT Ta "set minimum count for output"
+.It Dv SO_RCVLOWAT Ta "set minimum count for input"
+.It Dv SO_SNDTIMEO Ta "set timeout value for output"
+.It Dv SO_RCVTIMEO Ta "set timeout value for input"
+.It Dv SO_TYPE Ta "get the type of the socket (get only)"
+.It Dv SO_ERROR Ta "get and clear error on the socket (get only)"

 .El
 .Pp
 .Dv SO_DEBUG
 .El
 .Pp
 .Dv SO_DEBUG


@@ -136,7 +147,7 @@ periodic transmission of messages on a connected socket.  Should the
 connected party fail to respond to these messages, the connection is
 considered broken and processes using the socket are notified via a
 .Dv SIGPIPE
 connected party fail to respond to these messages, the connection is
 considered broken and processes using the socket are notified via a
 .Dv SIGPIPE

-signal.
+signal when attempting to send data.

 .Dv SO_DONTROUTE
 indicates that outgoing messages should
 bypass the standard routing facilities.  Instead, messages are directed
 .Dv SO_DONTROUTE
 indicates that outgoing messages should
 bypass the standard routing facilities.  Instead, messages are directed


@@ -182,6 +193,7 @@ or
 calls without the
 .Dv MSG_OOB
 flag.
 calls without the
 .Dv MSG_OOB
 flag.

+Some protocols always behave as if this option is set.

 .Dv SO_SNDBUF
 and
 .Dv SO_RCVBUF
 .Dv SO_SNDBUF
 and
 .Dv SO_RCVBUF


@@ -190,6 +202,70 @@ buffer sizes allocated for output and input buffers, respectively.
 The buffer size may be increased for high-volume connections,
 or may be decreased to limit the possible backlog of incoming data.
 The system places an absolute limit on these values.
 The buffer size may be increased for high-volume connections,
 or may be decreased to limit the possible backlog of incoming data.
 The system places an absolute limit on these values.

+.Pp
+.Dv SO_SNDLOWAT
+is an option to set the minimum count for output operations.
+Most output operations process all of the data supplied
+by the call, delivering data to the protocol for transmission
+and blocking as necessary for flow control.
+Nonblocking output operations will process as much data as permitted
+subject to flow control without blocking, but will process no data
+if flow control does not allow the smaller of the low water mark value
+or the entire request to be processed.
+A
+.Xr select 2
+operation testing the ability to write to a socket will return true
+only if the low water mark amount could be processed.
+The default value for
+.Dv SO_SNDLOWAT
+is set to a convenient size for network efficiency, often 1024.
+.Dv SO_RCVLOWAT
+is an option to set the minimum count for input operations.
+In general, receive calls will block until any (non-zero) amount of data
+is received, then return with smaller of the amount available or the amount
+requested.
+The default value for
+.Dv SO_SNDLOWAT
+is 1.
+If 
+.Dv SO_SNDLOWAT
+is set to a larger value, blocking receive calls normally
+wait until they have received the smaller of the low water mark value
+or the requested amount.
+Receive calls may still return less than the low water mark if an error
+occurs, a signal is caught, or the type of data next in the receive queue
+is different than that returned.
+.Pp
+.Dv SO_SNDTIMEO
+is an option to set a timeout value for output operations.
+It accepts a
+.Fa struct timeval
+parameter with the number of seconds and microseconds
+used to limit waits for output operations to complete.
+If a send operation has blocked for this much time,
+it returns with a partial count
+or with the error
+.Er EWOULDBLOCK
+if no data were sent.
+In the current implementation, this timer is restarted each time additional
+data are delivered to the protocol,
+implying that the limit applies to output portions ranging in size
+from the low water mark to the high water mark for output.
+.Dv SO_RCVTIMEO
+is an option to set a timeout value for input operations.
+It accepts a
+.Fa struct timeval
+parameter with the number of seconds and microseconds
+used to limit waits for input operations to complete.
+In the current implementation, this timer is restarted each time additional
+data are received by the protocol,
+and thus the limit is in effect an inactivity timer.
+If a receive operation has been blocked for this much time without
+receiving additional data, it returns with a short count
+or with the error
+.Er EWOULDBLOCK
+if no data were received.
+.Pp

 Finally,
 .Dv SO_TYPE
 and
 Finally,
 .Dv SO_TYPE
 and

diff --git a/usr/src/lib/libc/sys/recv.2 b/usr/src/lib/libc/sys/recv.2
index 7e26fcb..0d934df 100644 (file)
--- a/usr/src/lib/libc/sys/recv.2
+++ b/usr/src/lib/libc/sys/recv.2
@@ -3,11 +3,11 @@
 .\"
 .\" %sccs.include.redist.man%
 .\"
 .\"
 .\" %sccs.include.redist.man%
 .\"

-.\"     @(#)recv.2     6.9 (Berkeley) %G%
+.\"     @(#)recv.2     6.10 (Berkeley) %G%

 .\"
 .Dd 
 .Dt RECV 2
 .\"
 .Dd 
 .Dt RECV 2

-.Os BSD 4.2
+.Os BSD 4.3r

 .Sh NAME
 .Nm recv ,
 .Nm recvfrom ,
 .Sh NAME
 .Nm recv ,
 .Nm recvfrom ,


@@ -27,12 +27,13 @@
 and
 .Fn recvmsg
 are used to receive messages from a socket,
 and
 .Fn recvmsg
 are used to receive messages from a socket,

-and may be used to receive data on a socket whether
-it is in a connected state or not.
+and may be used to receive data on a socket whether or not
+it is connection-oriented.

 .Pp
 If
 .Fa from
 .Pp
 If
 .Fa from

-is non-nil, the source address of the message is filled in.
+is non-nil, and the socket is not connection-oriented,
+the source address of the message is filled in.

 .Fa Fromlen
 is a value-result parameter, initialized to the size of
 the buffer associated with
 .Fa Fromlen
 is a value-result parameter, initialized to the size of
 the buffer associated with


@@ -63,30 +64,51 @@ the message is received from (see
 If no messages are available at the socket, the
 receive call waits for a message to arrive, unless
 the socket is nonblocking (see
 If no messages are available at the socket, the
 receive call waits for a message to arrive, unless
 the socket is nonblocking (see

-.Xr ioctl 2 )
+.Xr fcntl 2 )

 in which case the value
 -1 is returned and the external variable
 .Va errno
 set to
 .Er EWOULDBLOCK.
 in which case the value
 -1 is returned and the external variable
 .Va errno
 set to
 .Er EWOULDBLOCK.

+The receive calls normally return any data available,
+up to the requested amount,
+rather than waiting for receipt of the full amount requested;
+this behavior is affected by the socket-level options
+.Dv SO_RCVLOWAT
+and
+.Dv SO_RCVTIMEO
+described in
+.Xr getsockopt 2 .

 .Pp
 The
 .Xr select 2
 .Pp
 The
 .Xr select 2

-call may be used to determine when more data arrives.
+call may be used to determine when more data arrive.

 .Pp
 The
 .Fa flags
 argument to a recv call is formed by 
 .Em or Ap ing
 one or more of the values:
 .Pp
 The
 .Fa flags
 argument to a recv call is formed by 
 .Em or Ap ing
 one or more of the values:

-.Bd -literal
-#define        MSG_OOB         0x1     /* process out-of-band data */
-#define        MSG_PEEK        0x2     /* peek at incoming message */
-#define        MSG_DONTROUTE   0x4     /* send without using routing tables */
-#define        MSG_EOR         0x8     /* data completes record */
-#define        MSG_TRUNC       0x10    /* data discarded before delivery */
-#define        MSG_CTRUNC      0x20    /* control data lost before delivery */
-.Ed
+.Bl -column MSG_WAITALL -offset indent
+.It Dv MSG_OOB Ta process out-of-band data
+.It Dv MSG_PEEK Ta peek at incoming message
+.It Dv MSG_WAITALL Ta wait for full request or error
+.El
+The
+.Dv MSG_OOB
+flag requests receipt of out-of-band data
+that would not be received in the normal data stream.
+Some protocols place expedited data at the head of the normal
+data queue, and thus this flag cannot be used with such protocols.
+The MSG_PEEK flag causes the receive operation to return data
+from the beginning of the receive queue without removing that
+data from the queue.
+Thus, a subsequent receive call will return the same data.
+The MSG_WAITALL flag requests that the operation block until
+the full request is satisfied.
+However, the call may still return less data than requested
+if a signal is caught, an error or disconnect occurs,
+or the next data to be received is of a different type than that returned.

 .Pp
 The
 .Fn recvmsg
 .Pp
 The
 .Fn recvmsg


@@ -137,34 +159,38 @@ struct cmsghdr {
 .Ed
 As an example, one could use this to learn of changes in the data-stream
 in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
 .Ed
 As an example, one could use this to learn of changes in the data-stream
 in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting

-a recvmsg with no uio provided immediately after an
-.Fn accept ,
-thought of here in the sense of get-next-connection-request without
-an implicit connection confirmation.
+a recvmsg with no data buffer provided immediately after an
+.Fn accept
+call.

 .Pp
 Open file descriptors are now passed as ancillary data for
 .Dv AF_UNIX
 domain sockets, with
 .Fa cmsg_level
 .Pp
 Open file descriptors are now passed as ancillary data for
 .Dv AF_UNIX
 domain sockets, with
 .Fa cmsg_level

-being
+set to

 .Dv SOL_SOCKET
 and
 .Fa cmsg_type
 .Dv SOL_SOCKET
 and
 .Fa cmsg_type

-being
+set to

 .Dv SCM_RIGHTS .
 .Pp
 .Dv SCM_RIGHTS .
 .Pp

-.Fa Msg_flags
-is set on return according to the message received.
+The
+.Fa msg_flags
+field is set on return according to the message received.

 .Dv MSG_EOR
 .Dv MSG_EOR

-indicates end-of-record,
+indicates end-of-record;
+the data returned completed a record (generally used with sockets of type
+.Dv SOCK_SEQPACKET ) .

 .Dv MSG_TRUNC
 indicates that
 .Dv MSG_TRUNC
 indicates that

-some trailing datagram data was discarded,
+the trailing portion of a datagram was discarded because the datagram
+was larger than the buffer supplied.

 .Dv MSG_CTRUNC
 indicates that some
 .Dv MSG_CTRUNC
 indicates that some

-control data was discarded due to lack of space,
+control data were discarded due to lack of space in the buffer
+for ancillary data.

 .Dv MSG_OOB
 .Dv MSG_OOB

-is returned to indicate that expedited data was received.
+is returned to indicate that expedited or out-of-band data were received.

 .Pp
 .Sh RETURN VALUES
 These calls return the number of bytes received, or -1
 .Pp
 .Sh RETURN VALUES
 These calls return the number of bytes received, or -1


@@ -176,16 +202,24 @@ The calls fail if:
 The argument
 .Fa s
 is an invalid descriptor.
 The argument
 .Fa s
 is an invalid descriptor.

+.It Bq Er ENOTCONN
+The socket is assoicated with a connection-oriented protocol
+and has not been connected (see
+.Xr connect 2
+and
+.Xr accept 2 ).

 .It Bq Er ENOTSOCK
 The argument
 .Fa s
 .It Bq Er ENOTSOCK
 The argument
 .Fa s

-is not a socket.
+does not refer to a socket.

 .It Bq Er EWOULDBLOCK
 .It Bq Er EWOULDBLOCK

-The socket is marked non-blocking and the receive operation
-would block.
+The socket is marked non-blocking, and the receive operation
+would block, or
+a receive timeout had been set,
+and the timeout expired before data were received.

 .It Bq Er EINTR
 The receive was interrupted by delivery of a signal before
 .It Bq Er EINTR
 The receive was interrupted by delivery of a signal before

-any data was available.
+any data were available.

 .It Bq Er EFAULT
 The receive buffer pointer(s) point outside the process's
 address space.
 .It Bq Er EFAULT
 The receive buffer pointer(s) point outside the process's
 address space.


@@ -193,7 +227,6 @@ address space.
 .Sh SEE ALSO
 .Xr fcntl 2 ,
 .Xr read 2 ,
 .Sh SEE ALSO
 .Xr fcntl 2 ,
 .Xr read 2 ,

-.Xr send 2 ,

 .Xr select 2 ,
 .Xr getsockopt 2 ,
 .Xr socket 2
 .Xr select 2 ,
 .Xr getsockopt 2 ,
 .Xr socket 2