GETSOCKOPT(2)                        BSD                         GETSOCKOPT(2)



NAME
     getsockopt, setsockopt - get and set options on sockets

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

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

     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
     protocol 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) is 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 supplied as 0.

     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 (4P).

     Most socket-level options take an int parameter for optval.  For
     setsockopt, the parameter should nonzero to enable a Boolean option, or 0
     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).

     The following options are recognized at the socket level.  Except as
     noted, each may be examined with getsockopt and set with setsockopt.

     SO_DEBUG         Toggle recording of debugging information.

     SO_REUSEADDR     Toggle local address reuse.  Allows socket to bind to
                      the same local port number as another socket, provided
                      that the socket is of type SOCK_DGRAM or is the active
                      side of a SOCK_STREAM connection.  The full address
                      (that is, the local address, local port, foreign
                      address, and foreign port) must still be unique.

     SO_KEEPALIVE     Toggle keep connections alive.  This option is not
                      supported by Domain/OS TCP.  (For more information, see
                      the Notes section below.)

     SO_DONTROUTE     Toggle routing bypass for outgoing messages.  This
                      option is not supported by Domain/OS TCP or UDP.

     SO_LINGER        Linger on close if data present.  By default, Domain/OS
                      TCP sockets linger on close.  This default behavior
                      cannot be changed by turning off the linger option.

     SO_BROADCAST     Toggle permission to transmit broadcast messages.  By
                      default, Domain/OS allows client programs to send or
                      connect to the broadcast address.  UDP sockets can bind
                      to the broadcast address, but cannot then send or
                      connect.

     SO_OOBINLINE     Toggle reception of out-of-band data in band.  Domain/OS
                      TCP supports only in-line out-of-band data and thus does
                      not support this socket option. Datagram sockets do not
                      support any form of out-of-band data.

     SO_SNDBUF        Set buffer size for output.  This option is not
                      supported by Domain/OS TCP or UDP.

     SO_RCVBUF        Set buffer size for input.  This option is not supported
                      by Domain/OS TCP or UDP.

     SO_TYPE          Get the type of the socket (get only).

     SO_ERROR         Get and clear error on the socket (get only).  This
                      option is not supported by Domain/OS TCP or UDP.

     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 connection is considered broken and processes using the socket are
     notified via a SIGPIPE signal.  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 time-out 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 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.  SO_SNDBUF and SO_RCVBUF are
     options to adjust the normal buffer sizes allocated for output and input
     buffers, respectively.  The buffer size can be increased for high-volume
     connections or 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 setsockopt.  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 can be used to check for
     asynchronous errors on connected datagram sockets or for other
     asynchronous errors.

ERRORS
     The call succeeds unless any of the following are true:

     [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.

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

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

NOTES
     Domain/OS TCP does not support the SO_KEEPALIVE socket option.  Keepalive
     messages consume network bandwidth to maintain otherwise idle
     connections.  Without these messages, the regular TCP procedures discover
     that the connection is lost when unable to fulfill a client request.
     Datagram protocols cannot support keepalive messages.

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