home | help
GETSOCKOPT(2)		       System Calls Manual		   GETSOCKOPT(2)

NAME
     getsockopt, setsockopt -- get and set options on sockets

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #include <sys/socket.h>

     int
     getsockopt(int s, int level, int optname, void * restrict optval,
	 socklen_t * restrict optlen);

     int
     setsockopt(int s, int level, int optname, const void *optval,
	 socklen_t optlen);

DESCRIPTION
     The getsockopt() and setsockopt() system calls manipulate the options asso-
     ciated  with a socket.  Options may exist at multiple protocol levels; they
     are always present at the uppermost "socket" level.

     When manipulating socket options the level at which the option resides  and
     the  name	of  the  option must be specified.  To manipulate options at the
     socket level, level is specified as SOL_SOCKET.  To manipulate  options  at
     any other level the protocol number of the appropriate protocol controlling
     the  option  is supplied.	For example, to indicate that an option is to be
     interpreted by the TCP protocol, level should be set to the protocol number
     of TCP; see getprotoent(3).

     The optval and optlen arguments are used to access option values  for  set-
     sockopt().   For getsockopt() they identify a buffer in which the value for
     the requested option(s) are to be returned.  For getsockopt(), optlen is  a
     value-result  argument, initially containing the size of the buffer pointed
     to by optval, and modified on return to indicate the  actual  size  of  the
     value  returned.	If no option value is to be supplied or returned, optval
     may be NULL.

     The optname argument and any specified options are passed uninterpreted  to
     the  appropriate  protocol  module  for  interpretation.	The include file
     <sys/socket.h> contains definitions for socket level options, described be-
     low.  Options at other protocol levels vary in format and name; consult the
     appropriate entries in section 4 of the manual.

     Most socket-level options utilize an int argument for optval.  For setsock-
     opt(), the argument should be non-zero to enable a boolean option, or  zero
     if  the option is to be disabled.	SO_LINGER uses a struct linger argument,
     defined in <sys/socket.h>, which specifies the desired state of the  option
     and  the  linger  interval  (see below).  SO_SNDTIMEO and SO_RCVTIMEO use a
     struct timeval argument, defined in <sys/time.h>.

     The following options are recognized at the socket level.	Except as noted,
     each may be examined with getsockopt() and set with setsockopt().

	   SO_DEBUG	      enables recording of debugging information
	   SO_REUSEADDR       enables local address reuse
	   SO_REUSEPORT       enables duplicate address and port bindings
	   SO_KEEPALIVE       enables keep connections alive
	   SO_DONTROUTE       enables routing bypass for outgoing messages
	   SO_LINGER	      linger on close if data present
	   SO_BROADCAST       enables permission to transmit broadcast messages
	   SO_OOBINLINE       enables reception of out-of-band data in band
	   SO_SNDBUF	      set buffer size for output
	   SO_RCVBUF	      set buffer size for input
	   SO_SNDLOWAT	      set minimum count for output
	   SO_RCVLOWAT	      set minimum count for input
	   SO_SNDTIMEO	      set timeout value for output
	   SO_RCVTIMEO	      set timeout value for input
	   SO_ACCEPTFILTER    set accept filter on listening socket
	   SO_TYPE	      get the type of the socket (get only)
	   SO_ERROR	      get and clear error on the socket (get only)

     SO_DEBUG  enables	 debugging   in   the	underlying   protocol	modules.
     SO_REUSEADDR indicates that the rules used in validating addresses supplied
     in   a   bind(2)  system  call  should  allow  reuse  of  local  addresses.
     SO_REUSEPORT allows completely duplicate bindings by multiple processes  if
     they  all	set  SO_REUSEPORT  before binding the port.  This option permits
     multiple instances of a program to each receive UDP/IP multicast or  broad-
     cast datagrams destined for the bound port.  SO_KEEPALIVE enables the peri-
     odic  transmission of messages on a connected socket.  Should the connected
     party fail to respond to these messages, the connection is considered  bro-
     ken  and  processes using the socket are notified via a SIGPIPE signal when
     attempting to send data.  SO_DONTROUTE  indicates	that  outgoing	messages
     should  bypass  the standard routing facilities.  Instead, messages are di-
     rected to the appropriate network interface according to the  network  por-
     tion of the destination address.

     SO_LINGER	controls  the  action  taken  when unsent messages are queued on
     socket and a close(2) is performed.  If the socket promises reliable deliv-
     ery of data and SO_LINGER is set, the system will block the process on  the
     close(2)  attempt until it is able to transmit the data or until it decides
     it is unable to deliver the  information  (a  timeout  period,  termed  the
     linger  interval,	is  specified in seconds in the setsockopt() system call
     when SO_LINGER is requested).  If SO_LINGER is disabled and a  close(2)  is
     issued,  the  system  will  process  the  close in a manner that allows the
     process to continue as quickly as possible.

     The option SO_BROADCAST requests permission to send broadcast datagrams  on
     the  socket.   Broadcast  was a privileged operation in earlier versions of
     the system.  With protocols that support out-of-band data, the SO_OOBINLINE
     option requests that out-of-band data be placed in the  normal  data  input
     queue as received; it will then be accessible with recv(2) or read(2) calls
     without  the  MSG_OOB flag.  Some protocols always behave as if this option
     is set.  SO_SNDBUF and SO_RCVBUF are options to adjust  the  normal  buffer
     sizes  allocated  for  output  and input buffers, respectively.  The buffer
     size may be increased for high-volume connections, or may be  decreased  to
     limit the possible backlog of incoming data.  The system places an absolute
     maximum  on  these  values,  which  is accessible through the sysctl(3) MIB
     variable "kern.ipc.maxsockbuf".

     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, deliv-
     ering  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
     or the entire request to be processed.  A select(2) operation  testing  the
     ability  to  write  to a socket will return true only if the low water mark
     amount could be processed.  The default value for SO_SNDLOWAT is set  to  a
     convenient  size for network efficiency, often 1024.  SO_RCVLOWAT is an op-
     tion to set the minimum count for input operations.   In  general,  receive
     calls  will block until any (non-zero) amount of data is received, then re-
     turn with the smaller of the amount available or the amount requested.  The
     default value for SO_RCVLOWAT is 1.  If 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 different from
     that which was returned.

     SO_SNDTIMEO is an option to set a timeout value for output operations.   It
     accepts  a struct timeval argument with the number of seconds and microsec-
     onds used to limit waits for output operations to complete.  If a send  op-
     eration  has blocked for this much time, it returns with a partial count or
     with the error EWOULDBLOCK if no data were sent.  In the current  implemen-
     tation,  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.
     SO_RCVTIMEO  is  an option to set a timeout value for input operations.  It
     accepts a struct timeval argument with the number of seconds and  microsec-
     onds  used to limit waits for input operations to complete.  In the current
     implementation, this timer is restarted each time additional data	are  re-
     ceived  by  the  protocol,  and  thus  the limit is in effect an inactivity
     timer.  If a receive operation has been blocked for this much time  without
     receiving	additional data, it returns with a short count or with the error
     EWOULDBLOCK if no data were received.

     SO_ACCEPTFILTER places an accept_filter(9) on the socket, which will filter
     incoming connections on a listening stream socket	before	being  presented
     for  accept(2).   Once  more, listen(2) must be called on the socket before
     trying to install the filter on it, or else the  setsockopt()  system  call
     will fail.

     struct  accept_filter_arg {
	     char    af_name[16];
	     char    af_arg[256-16];
     };

     The  optval  argument  should point to a struct accept_filter_arg that will
     select and configure the accept_filter(9).  The af_name argument should  be
     filled  with  the	name of the accept filter that the application wishes to
     place on the listening socket.  The optional argument af_arg can be  passed
     to  the accept filter specified by af_name to provide additional configura-
     tion options at attach time.  Passing in an optval of NULL will remove  the
     filter.

     Finally,  SO_TYPE	and  SO_ERROR  are  options used only with getsockopt().
     SO_TYPE returns the type of the socket, such as SOCK_STREAM; it  is  useful
     for  servers that inherit sockets on startup.  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 asyn-
     chronous errors.

RETURN VALUES
     Upon successful completion, the value 0 is returned; otherwise the value -1
     is returned and the global variable errno is set to indicate the error.

ERRORS
     The call succeeds unless:

     [EBADF]		The argument s is not a valid descriptor.

     [ENOTSOCK] 	The argument s is a file, not a socket.

     [ENOPROTOOPT]	The option is unknown at the level indicated.

     [EFAULT]		The address pointed to by optval is not in a valid  part
			of  the  process  address space.  For getsockopt(), this
			error may also be returned if optlen is not in	a  valid
			part of the process address space.

     [EINVAL]		Installing an accept_filter(9) on a non-listening socket
			was attempted.

SEE ALSO
     ioctl(2),	socket(2),  getprotoent(3),  sysctl(3), protocols(5), sysctl(8),
     accept_filter(9)

BUGS
     Several of the socket options should be handled at lower levels of the sys-
     tem.

HISTORY
     The getsockopt() system call appeared in 4.2BSD.

FreeBSD 5.3			   May 2, 1995			   GETSOCKOPT(2)

home | help