X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..935ed37a5c468c8a1c07408573c08b8b7ef80e8b:/bsd/man/man2/getsockopt.2 diff --git a/bsd/man/man2/getsockopt.2 b/bsd/man/man2/getsockopt.2 index cd618692a..9e3bef41f 100644 --- 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 -.Fd #include .Fd #include .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 @@ -77,9 +88,9 @@ see .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 @@ -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 , -.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 @@ -112,7 +123,7 @@ section 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, @@ -235,35 +246,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. -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 @@ -280,7 +294,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 -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 @@ -295,10 +310,15 @@ 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; +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 @@ -318,34 +338,72 @@ the error status. 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 +.Fd #include +.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.