xnu-3248.20.55.tar.gz

[apple/xnu.git] / bsd / man / man2 / getsockopt.2

diff --git a/bsd/man/man2/getsockopt.2 b/bsd/man/man2/getsockopt.2
index cd618692ac4bf469c35053339eec5149cfdfc51b..0ec25a00086c76f65633fdb5d44d306b3cbc32c3 100644 (file)
--- a/bsd/man/man2/getsockopt.2
+++ b/bsd/man/man2/getsockopt.2
@@ -41,12 +41,23 @@
 .Nm setsockopt
 .Nd get and set options on sockets
 .Sh SYNOPSIS
 .Nm setsockopt
 .Nd get and set options on sockets
 .Sh SYNOPSIS

-.Fd #include <sys/types.h>

 .Fd #include <sys/socket.h>
 .Ft int
 .Fd #include <sys/socket.h>
 .Ft int

-.Fn getsockopt "int s" "int level" "int optname" "void *optval" "int *optlen"
+.Fo getsockopt
+.Fa "int socket"
+.Fa "int level"
+.Fa "int option_name"
+.Fa "void *restrict option_value"
+.Fa "socklen_t *restrict option_len"
+.Fc

 .Ft int
 .Ft int

-.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "int optlen"
+.Fo setsockopt
+.Fa "int socket"
+.Fa "int level"
+.Fa "int option_name"
+.Fa "const void *option_value"
+.Fa "socklen_t option_len"
+.Fc

 .Sh DESCRIPTION
 .Fn Getsockopt
 and
 .Sh DESCRIPTION
 .Fn Getsockopt
 and


@@ -77,9 +88,9 @@ see
 .Xr getprotoent 3 .
 .Pp
 The parameters
 .Xr getprotoent 3 .
 .Pp
 The parameters

-.Fa optval
+.Fa option_value

 and
 and

-.Fa optlen
+.Fa option_len

 are used to access option values for
 .Fn setsockopt .
 For
 are used to access option values for
 .Fn setsockopt .
 For


@@ -87,17 +98,17 @@ For
 they identify a buffer in which the value for the
 requested option(s) are to be returned.  For
 .Fn getsockopt ,
 they identify a buffer in which the value for the
 requested option(s) are to be returned.  For
 .Fn getsockopt ,

-.Fa optlen
+.Fa option_len

 is a value-result parameter, initially containing the
 size of the buffer pointed to by
 is a value-result parameter, initially containing the
 size of the buffer pointed to by

-.Fa optval ,
+.Fa option_value ,

 and modified on return to indicate the actual size of
 the value returned.  If no option value is
 to be supplied or returned,
 and modified on return to indicate the actual size of
 the value returned.  If no option value is
 to be supplied or returned,

-.Fa optval
+.Fa option_value

 may be NULL.
 .Pp
 may be NULL.
 .Pp

-.Fa Optname
+.Fa option_name

 and any specified options are passed uninterpreted to the appropriate
 protocol module for interpretation.
 The include file
 and any specified options are passed uninterpreted to the appropriate
 protocol module for interpretation.
 The include file


@@ -112,7 +123,7 @@ section
 Most socket-level options utilize an
 .Fa int
 parameter for
 Most socket-level options utilize an
 .Fa int
 parameter for

-.Fa optval .
+.Fa option_value .

 For
 .Fn setsockopt ,
 the parameter should be non-zero to enable a boolean option,
 For
 .Fn setsockopt ,
 the parameter should be non-zero to enable a boolean option,


@@ -155,15 +166,20 @@ and set with
 .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_NOSIGPIPE Ta "do not generate SIGPIPE, instead return EPIPE"
 .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_NOSIGPIPE Ta "do not generate SIGPIPE, instead return EPIPE"

+.It Dv SO_NREAD Ta "number of bytes to be read (get only)"
+.It Dv SO_NWRITE Ta "number of bytes written not yet sent by the protocol (get only)"
+.It Dv SO_LINGER_SEC Ta "linger on close if data present with timeout in seconds"

 .El
 .Pp
 .Dv SO_DEBUG
 enables debugging in the underlying protocol modules.
 .El
 .Pp
 .Dv SO_DEBUG
 enables debugging in the underlying protocol modules.

+.Pp

 .Dv SO_REUSEADDR
 indicates that the rules used in validating addresses supplied
 in a
 .Xr bind 2
 call should allow reuse of local addresses.
 .Dv SO_REUSEADDR
 indicates that the rules used in validating addresses supplied
 in a
 .Xr bind 2
 call should allow reuse of local addresses.

+.Pp

 .Dv SO_REUSEPORT
 allows completely duplicate bindings by multiple processes
 if they all set
 .Dv SO_REUSEPORT
 allows completely duplicate bindings by multiple processes
 if they all set


@@ -171,6 +187,7 @@ if they all set
 before binding the port.
 This option permits multiple instances of a program to each
 receive UDP/IP multicast or broadcast datagrams destined for the bound port.
 before binding the port.
 This option permits multiple instances of a program to each
 receive UDP/IP multicast or broadcast datagrams destined for the bound port.

+.Pp

 .Dv SO_KEEPALIVE
 enables the
 periodic transmission of messages on a connected socket.  Should the
 .Dv SO_KEEPALIVE
 enables the
 periodic transmission of messages on a connected socket.  Should the


@@ -178,6 +195,7 @@ 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 when attempting to send data.
 considered broken and processes using the socket are notified via a
 .Dv SIGPIPE
 signal when attempting to send data.

+.Pp

 .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


@@ -207,11 +225,18 @@ is disabled and a
 is issued, the system will process the close in a manner that allows
 the process to continue as quickly as possible.
 .Pp
 is issued, the system will process the close in a manner that allows
 the process to continue as quickly as possible.
 .Pp

+.Dv SO_LINGER_SEC
+is the same option as 
+.Dv SO_LINGER 
+except the linger time is in seconds for 
+.Dv SO_LINGER_SEC .
+.Pp

 The option
 .Dv SO_BROADCAST
 requests permission to send broadcast datagrams
 on the socket.
 Broadcast was a privileged operation in earlier versions of the system.
 The option
 .Dv SO_BROADCAST
 requests permission to send broadcast datagrams
 on the socket.
 Broadcast was a privileged operation in earlier versions of the system.

+.Pp

 With protocols that support out-of-band data, the
 .Dv SO_OOBINLINE
 option
 With protocols that support out-of-band data, the
 .Dv SO_OOBINLINE
 option


@@ -224,6 +249,7 @@ calls without the
 .Dv MSG_OOB
 flag.
 Some protocols always behave as if this option is set.
 .Dv MSG_OOB
 flag.
 Some protocols always behave as if this option is set.

+.Pp

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


@@ -235,35 +261,38 @@ The system places an absolute limit on these values.
 .Pp
 .Dv SO_SNDLOWAT
 is an option to set the minimum count for output operations.
 .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
+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
 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
+(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
 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.
+only if the low-water mark amount could be processed.

 The default value for
 .Dv SO_SNDLOWAT
 The default value for
 .Dv SO_SNDLOWAT

-is set to a convenient size for network efficiency, often 1024.
+is set to a convenient size for network efficiency, often 2048.
+.Pp

 .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
 .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 the smaller of the amount available or the amount
-requested.
+is received, then return with the smaller of the amount available
+or the amount requested.

 The default value for
 .Dv SO_RCVLOWAT
 is 1.
 If 
 .Dv SO_RCVLOWAT
 The default value for
 .Dv SO_RCVLOWAT
 is 1.
 If 
 .Dv SO_RCVLOWAT

-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 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 different than that returned.
 .Pp
 .Dv SO_SNDTIMEO


@@ -280,7 +309,8 @@ 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
 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.
+from the low-water mark to the high-water mark for output.
+.Pp

 .Dv SO_RCVTIMEO
 is an option to set a timeout value for input operations.
 It accepts a
 .Dv SO_RCVTIMEO
 is an option to set a timeout value for input operations.
 It accepts a


@@ -295,57 +325,123 @@ receiving additional data, it returns with a short count
 or with the error
 .Er EWOULDBLOCK
 if no data were received.
 or with the error
 .Er EWOULDBLOCK
 if no data were received.

+The struct timeval parameter must represent a positive time interval;
+otherwise,
+.Fn setsockopt 
+returns with the error
+.Er EDOM .

 .Pp
 .Dv SO_NOSIGPIPE is an option that prevents SIGPIPE from being raised 
 when a write fails on a socket to which there is no reader; 
 .Pp
 .Dv SO_NOSIGPIPE is an option that prevents SIGPIPE from being raised 
 when a write fails on a socket to which there is no reader; 

-instead the write to the socket returns with the error 
+instead, the write to the socket returns with the error 

 .Er EPIPE
 when there is no reader.
 .Pp
 Finally,
 .Er EPIPE
 when there is no reader.
 .Pp
 Finally,

-.Dv SO_TYPE
-and
-.Dv SO_ERROR
+.Dv SO_TYPE ,
+.Dv SO_ERROR ,
+.Dv SO_NREAD , and
+.Dv SO_NWRITE

 are options used only with
 .Fn getsockopt .
 are options used only with
 .Fn getsockopt .

+.Pp

 .Dv SO_TYPE
 returns the type of the socket, such as
 .Dv SOCK_STREAM ;
 it is useful for servers that inherit sockets on startup.
 .Dv SO_TYPE
 returns the type of the socket, such as
 .Dv SOCK_STREAM ;
 it is useful for servers that inherit sockets on startup.

+.Pp

 .Dv SO_ERROR
 returns any pending error on the socket and clears
 the error status.
 It may be used to check for asynchronous errors on connected
 datagram sockets or for other asynchronous errors.
 .Dv SO_ERROR
 returns any pending error on the socket and clears
 the error status.
 It may be used to check for asynchronous errors on connected
 datagram sockets or for other asynchronous errors.

+.Pp
+.Dv SO_NREAD
+returns the amount of data in the input buffer that is available to be received. 
+For datagram oriented sockets,
+.Dv SO_NREAD
+returns the size of the first packet -- this differs from the 
+.Fn ioctl 
+command 
+.Dv FIONREAD 
+that returns the total amount of data available.
+.Pp
+.Dv SO_NWRITE 
+returns the amount of data in the output buffer not yet sent by the protocol.

 .Sh RETURN VALUES
 .Sh RETURN VALUES

-A 0 is returned if the call succeeds, -1 if it fails.
+.Rv -std

 .Sh ERRORS
 .Sh ERRORS

-The call succeeds unless:
+The
+.Fn getsockopt
+and
+.Fn setsockopt
+system calls will succeed unless:

 .Bl -tag -width Er
 .Bl -tag -width Er

+.\" ==========

 .It Bq Er EBADF
 The argument
 .It Bq Er EBADF
 The argument

-.Fa s
-is not a valid descriptor.
-.It Bq Er ENOTSOCK
-The argument
-.Fa s
-is a file, not a socket.
-.It Bq Er ENOPROTOOPT
-The option is unknown at the level indicated.
+.Fa socket
+is not a valid file descriptor.
+.\" ==========

 .It Bq Er EFAULT
 The address pointed to by 
 .It Bq Er EFAULT
 The address pointed to by 

-.Fa optval
+.Fa option_value

 is not in a valid part of the process address space.
 For
 .Fn getsockopt ,
 this error may also be returned if
 is not in a valid part of the process address space.
 For
 .Fn getsockopt ,
 this error may also be returned if

-.Fa optlen
+.Fa option_len

 is not in a valid part of the process address space.
 is not in a valid part of the process address space.

+.\" ==========
+.It Bq Er EINVAL
+The option is invalid at the level indicated.
+.\" ==========
+.It Bq Er ENOBUFS
+Insufficient system resources available for the call to complete.
+.\" ==========
+.It Bq Er ENOMEM
+Insufficient memory available for the system call to complete.
+.\" ==========
+.It Bq Er ENOPROTOOPT
+The option is unknown at the level indicated.
+.\" ==========
+.It Bq Er ENOTSOCK
+The argument
+.Fa socket
+is not a socket (e.g., a plain file).
+.El
+.Pp
+The
+.Fn setsockopt
+system call will succeed unless:
+.Bl -tag -width Er
+.\" ==========
+.It Bq Er EDOM
+The argument
+.Fa option_value
+is out of bounds. 
+.\" ==========
+.It Bq Er EISCONN
+.Fa socket
+is already connected
+and a specified option cannot be set
+while this is the case.
+.\" ==========
+.It Bq Er EINVAL
+The socket has been shut down.

 .El
 .El

+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.

 .Sh SEE ALSO
 .Sh SEE ALSO

-.Xr ioctl 2 ,

 .Xr socket 2 ,
 .Xr socket 2 ,

-.Xr getprotoent 3
+.Xr bind 2 ,
+.Xr ioctl 2 ,
+.Xr getprotoent 3 ,

 .Xr protocols 5
 .Sh BUGS
 Several of the socket options should be handled at lower levels of the system.
 .Xr protocols 5
 .Sh BUGS
 Several of the socket options should be handled at lower levels of the system.