GETSOCKOPT(2)       Linux Programmer's Manual       GETSOCKOPT(2)

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 *opt-
       val, socklen_t *optlen);

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

DESCRIPTION
       Getsockopt  and  setsockopt manipulate the options associ-
       ated with a socket.  Options may exist at multiple  proto-
       col  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 speci-
       fied.  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  proto-
       col  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 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
       disabled.   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  parame-
       ter, 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 mod-
       ules.  SO_REUSEADDR indicates that the rules used in vali-
       dating  addresses  supplied in a bind(2) call should allow
       reuse of local addresses.  SO_KEEPALIVE enables the  peri-
       odic  transmission  of  messages  on  a  connected socket.
       Should the connected party fail to respond to  these  mes-
       sages,  the  connection is considered broken and processes
       using the socket are notified via a  SIGPIPE  signal  when
       attempting to send data.  SO_DONTROUTE indicates that out-
       going messages should bypass the standard routing  facili-
       ties.   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
       follows:

              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  proto-
       cols  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 out-
       put 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  con-
       trol.   Nonblocking output operations will process as much
       data as permitted subject to flow control  without  block-
       ing,  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  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 out-
       put  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 restarted  each  time  additional  data  are
       received  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.

       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  sock-
       ets 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 getsock-
               opt, 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, SO_RCVTIMEO options

NOTE
       The  fifth  argument  of  getsockopt  and setsockopt is in
       reality an int [*] (and this is what BSD 4.* and libc4 and
       libc5 have).  Some POSIX confusion resulted in the present
       socklen_t.  The draft standard has not been  adopted  yet,
       but  glibc2 already follows it and also has socklen_t [*].
       See also accept(2).

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

SEE ALSO
       ioctl(2), socket(2), getprotoent(3), protocols(5)

BSD Man Page              22 April 1996                         1