getsockopt, setsockopt

Purpose

     Gets and sets options on sockets.

Library

     Sockets Library (libsock.a)

Syntax

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

     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

     The  getsockopt  and  setsockopt  subroutines  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,  you must  specify the
     level at  which the  option resides and  the name  of the
     option.   To  manipulate  options at  the  socket  level,
     specify level  as SOL_SOCKET.   To manipulate  options at
     any other  level, supply the appropriate  protocol number
     for the protocol controlling the option.  For example, to
     indicate that  an option will  be interpreted by  the TCP
     protocol, set  level to  the protocol  number of  TCP, as
     defined in the netinet/in.h header file.  For more infor-
     mation, see &ldq.getprotoent&rdq. on page 3-244.

     Use  the parameters  optval and  optlen to  access option
     values for setsockopt.   For setsockopt, these parameters
     identify a  buffer in which  the value for  the requested
     option  or options  are  returned.   For getsockopt,  the
     optlen  parameter  initially  contains the  size  of  the
     buffer pointed  to by  the optval parameter.   On return,
     the optlen  parameter is modified to  indicate the actual
     size of the  value returned.  If no option  value is sup-
     plied or returned, the optval parameter can be 0.

     The  optname  parameter  and any  specified  options  are
     passed uninterpreted  to the appropriate  protocol module
     for  interpretation.  The  sys/socket.h header  file con-
     tains  definitions  for   socket  level  options.   These
     options are:

     SO_DEBUG         Turns on recording of debugging informa-
                      tion.
     SO_ACCEPTCONN    Specifies that socket is listening.
     SO_REUSEADDR     Allows local address reuse.
     SO_KEEPALIVE     Keeps connections active.
     SO_DONTROUTE     Does not apply  routing on outgoing mes-
                      sages.
     SO_LINGER        Lingers on  a close system call  if data
                      is present.
     SO_OOBINLINE     Leaves  received out-of-band  data (data
                      marked urgent) in line.
     SO_SNDBUF        Sends buffer size.
     SO_RCVBUF        Receives buffer size.
     SO_SNDLOWAT      Sends low-water mark.
     SO_RCVLOWAT      Receives low-water mark.
     SO_SNDTIMEO      Sends timeout.
     SO_RCVTIMEO      Receives timeout.
     SO_ERROR         Gets error status.
     SO_TYPE          Gets socket type.

     SO_DEBUG  enables debugging  in  the underlying  protocol
     modules.  SO_REUSEADDR  indicates that the rules  used in
     validating addresses supplied by a bind subroutine should
     allow reuse of local addresses.  SO_KEEPALIVE enables the
     periodic transmission of messages  on a connected socket.
     If the  connected socket fails  to respond to  these mes-
     sages, the connection is  broken and processes using that
     socket are notified with  a SIGPIPE signal.  SO_DONTROUTE
     indicates  that  outgoing   messages  should  bypass  the
     standard  routing  facilities  and 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 a
     socket  and  a  close   system  call  is  performed.   If
     SO_LINGER is  set, the  system blocks the  process during
     the close system  call until it can transmit  the data or
     until the time  expires.  Specify the amount  of time for
     the linger  interval by  using the  setsockopt subroutine
     when requesting SO_LINGER.  If SO_LINGER is not specified
     and a close system call is issued, the system handles the
     call  in a  way that  allows the  process to  continue as
     quickly as possible.

     Options at other protocol levels vary in format and name.

Return Value

     Upon successful completion, a value of 0 is returned.  If
     the getsockopt or setsockopt routine fails, a value of -1
     is returned, and errno is set to indicate the error.

Diagnostics

     The subroutine fails if one  or more of the following are
     true:

     EBADF             The s parameter is not valid.

     ENOTSOCK          The s parameter refers to a file, not a
                       socket.

     ENOPROTOOPT       The option is unknown.

     EFAULT            The addr parameter is not in a writable
                       part of the user address space.

Related Information

     In    this    book:    "getprotoent,    getprotobynumber,
     getprotobyname, setprotoent, endprotoent." and "socket."