unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

GETSOCKOPT(2)                 System Calls Manual                GETSOCKOPT(2)



NAME
       getsockopt, setsockopt - get and set options on sockets

SYNOPSIS
       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/socket.h>&gt;

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

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

DESCRIPTION
       getsockopt()  and  setsockopt()  manipulate  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(3N).

       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 getsock-
       opt(), 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 supplied as 0.

       optname  and  any  specified  options  are  passed uninterpreted to the
       appropriate protocol  module  for  interpretation.   The  include  file
       <&lt;sys/socket.h>&gt;  contains  definitions  for  ``socket''  level  options,
       described below.  Options at other protocol levels vary in  format  and
       name; consult the appropriate entries in section (4P).

       Most  socket-level  options take an int parameter for optval.  For set-
       sockopt(), 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  <&lt;sys/socket.h>&gt;,  which  specifies  the
       desired state of the option and the linger interval (see below).

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

              SO_DEBUG            toggle recording of debugging information
              SO_REUSEADDR        toggle local address reuse
              SO_KEEPALIVE        toggle keep connections alive
              SO_DONTROUTE        toggle routing bypass for outgoing messages
              SO_LINGER           linger on close if data present
              SO_BROADCAST        toggle permission to transmit broadcast mes-
                                  sages
              SO_OOBINLINE        toggle reception of out-of-band data in band
              SO_SNDBUF           set buffer size for output
              SO_RCVBUF           set buffer size 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_KEEPALIVE  enables  the  periodic transmission of messages on a con-
       nected socket.  Should the connected party fail  to  respond  to  these
       messages, the connection is considered broken.  A process attempting to
       write to the socket receives a SIGPIPE signal and the  write  operation
       returns  an  error.   By default, a process exits when it receives SIG-
       PIPE.  A read operation on the socket returns an  error  but  does  not
       generate SIGPIPE.  If the process is waiting in select(2) when the con-
       nection is broken, select() returns true for any read or  write  events
       selected for the socket.  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 messags are  queued  on
       socket  and  a close(2V) 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 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()  or  read()  calls  without  the  MSG_OOB  flag.   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.  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 asynchronous errors.

RETURN VALUES
       getsockopt() and setsockopt() return:

       0      on success.

       -1     on failure and set errno to indicate the error.

ERRORS
       EBADF               s is not a valid descriptor.

       EFAULT              The  address pointed to by optval is not in a valid
                           part of the process address space.

       ENOPROTOOPT         The option is unknown at the level indicated.

       ENOTSOCK            s is a file, not a socket.

       In addition to the above, getsockopt() may set errno to:

       EFAULT              optlen is not  in  a  valid  part  of  the  process
                           address space.

SEE ALSO
       ioctl(2), socket(2), getprotoent(3N)

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



                                21 January 1990                  GETSOCKOPT(2)