NAME

     getsockopt, setsockopt - get and set options on sockets


SYNOPSIS

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


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

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


DESCRIPTION

     Getsockopt and setsockopt manipulate the options  associated
     with  a socket.  Options may exist at multiple protocol lev-
     els; 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  speci-
     fied  as  SOL_SOCKET.   To  manipulate  options at any other
     level the protocol number of the appropriate  protocol  con-
     trolling  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 get-
     protoent(3).

     The parameters optval and optlen are used to  access  option
     values  for  setsockopt.   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
     parameter, 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.

     Optname 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 below.  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  parameter  for
     optval.  For setsockopt, the parameter should be non-zero to
     enable a boolean option, or zero if the option is to be dis-
     abled.  SO_LINGER uses a struct linger parameter, defined in
     <linux/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  parameter,  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_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
             get timeout value for output (get only)

     SO_RCVTIMEO
             get timeout value for input (get only)

     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) call should allow
     reuse of local addresses.  SO_KEEPALIVE enables the periodic
     transmission of messages on a connected socket.  Should  the
     connected  party fail to respond to these messages, the con-
     nection is considered broken 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 directed to the appropriate network interface  according
     to the network portion 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 delivery of data and SO_LINGER is set, the
     system  will block the process on the close 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  the  setsockopt  call
     when SO_LINGER is requested). If SO_LINGER is disabled and a
     close is issued, the system will  process  the  close  in  a
     manner  that  allows  the  process to continue as quickly as
     possible.

     The linger structure is defined in <linux/socket.h> as  fol-
     lows:

          struct linger {
                  int  l_onoff;   /* Linger active */
                  int  l_linger;  /* How long to linger for */
          };

     l_onoff indicates wether to linger or not. If it is set to 1
     then l_linger contains the time in hundredths of seconds how
     long the process should linger to complete  the  close.   If
     l_onoff is set to zero the process returns immediately.

     The option SO_BROADCAST requests permission to  send  broad-
     cast  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 or read 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 limit on these values.

     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  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 pro-
     cessed.  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 effi-
     ciency, often 1024.

     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
     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 than that returned.

     SO_SNDTIMEO is an option to get the timeout value for output
     operations.   (It  can  be  used  with getsockopt only).  It
     returns a  struct  timeval  parameter  with  the  number  of
     seconds  and  microseconds  used  to  limit waits for output
     operations to complete.  If a send operation 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
     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.   SO_RCVTIMEO
     is  an option to get the timeout value for input operations.
     (It can be used with getsockopt only).  It returns a  struct
     timeval   parameter   with   the   number   of  seconds  and
     microseconds used to limit waits  for  input  operations  to
     complete.  In the current implementation, this timer is res-
     tarted each time additional data are received by the  proto-
     col,  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.

     Finally, also 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 asynchronous errors.


RETURN VALUE

     On success, zero is returned.  On error, -1 is returned, and
     errno is set appropriately.


ERRORS

     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.


CONFORMING TO

     SVr4, 4.4BSD (these system calls first appeared in  4.2BSD).
     SVr4  documents additional ENOMEM and ENOSR error codes, but
     does not document the SO_SNDLOWAT, SO_RCVLOWAT, SO_SNDTIMEO,
     options


BUGS

     Several of the socket options should  be  handled  at  lower
     levels of the system.


SEE ALSO

     ioctl(2), socket(2), getprotoent(3),