.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,
.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.
+.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
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;
-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
It may be used to check for asynchronous errors on connected
datagram sockets or for other asynchronous errors.
.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 memory buffers are available.
+.\" ==========
+.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.
.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 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