xnu-1228.7.58.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..9e3bef41f02f03d9b3ad431a1780fa45c2dd5497 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,


@@ -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.
 .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
 is set to a convenient size for network efficiency, often 1024.
 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
 .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 +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
 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,10 +310,15 @@ 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
 .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
 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
 .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 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
 .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 ,
 .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.
 .Xr protocols 5
 .Sh BUGS
 Several of the socket options should be handled at lower levels of the system.