.Nm setsockopt
.Nd get and set options on sockets
.Sh SYNOPSIS
-.Fd #include <sys/types.h>
.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
-.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
.Xr getprotoent 3 .
.Pp
The parameters
-.Fa optval
+.Fa option_value
and
-.Fa optlen
+.Fa option_len
are used to access option values for
.Fn setsockopt .
For
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
-.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,
-.Fa optval
+.Fa option_value
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
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,
.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.
+.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.
+.Pp
.Dv SO_REUSEPORT
allows completely duplicate bindings by multiple processes
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.
+.Pp
.Dv SO_KEEPALIVE
enables the
periodic transmission of messages on a connected socket. Should the
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
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.
+.Pp
With protocols that support out-of-band data, the
.Dv SO_OOBINLINE
option
.Dv MSG_OOB
flag.
Some protocols always behave as if this option is set.
+.Pp
.Dv SO_SNDBUF
and
.Dv SO_RCVBUF
.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
-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
-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
-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
-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
-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
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
receiving additional data, it returns with a short count
or with the error
.Er EWOULDBLOCK
-if no data were received. The struct timeval parameter must represent a
-positive time interval less than SHRT_MAX * 10 milliseconds (5 minutes
-and 28 seconds) otherwise
+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;
-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,
-.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 .
+.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.
+.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.
+.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
-A 0 is returned if the call succeeds, -1 if it fails.
+.Rv -std
.Sh ERRORS
-The call succeeds unless:
+The
+.Fn getsockopt
+and
+.Fn setsockopt
+system calls will succeed unless:
.Bl -tag -width Er
+.\" ==========
.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
-.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
-.Fa optlen
+.Fa option_len
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 value is out of bounds.
+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
+.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
-.Xr ioctl 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.
projects / apple / xnu.git / blobdiff