GETSOCKOPT(2)                    System Calls                    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 *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 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  pro-
       tocol  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  sup-
       plied 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;  con-
       sult 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 <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 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_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_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 sup-
       plied in  a  bind(2)  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 per-
       mits  multiple  instances of a program to each receive UDP/IP multicast
       or broadcast datagrams  destined  for  the  bound  port.   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 noti-
       fied 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_LINGERisset, 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 the setsockopt 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 ver-
       sions 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 limit on these
       values.

       SO_SNDLOWAT  is  an  option  to set the minimum count for output opera-
       tions.  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 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 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 than
       that returned.

       SO_SNDTIMEO is an option to set a timeout value for output  operations.
       It  accepts  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 par-
       tial 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 set a timeout value
       for  input  operations.  It accepts a struct timeval parameter with the
       number of seconds and microseconds used to limit waits for input opera-
       tions  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 opera-
       tion 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, 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 use-
       ful 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 VALUES

       A 0 is returned if the call succeeds, -1 if it fails.


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.


SEE ALSO

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


BUGS

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


HISTORY

       The setsockopt system call appeared in 4.2BSD.



GNO                             16 January 1997                  GETSOCKOPT(2)

Man(1) output converted with man2html