setsockopt(2)                                             setsockopt(2)

  getsockopt()

  NAME

    getsockopt(), setsockopt() - get and set options on sockets

  SYNOPSIS

    #include 
    #include 

    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

    The getsockopt(2) and setsockopt(2) functions manipulate the options
    associated with a socket. Options are always present at the uppermost
    socket level and they may also exist at other protocol levels.

    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(2) .

    The parameters optval and optlen are used to access option values for
    setsockopt(2). For getsockopt(2) they identify a buffer in which the value
    for the requested option(s) are to be returned. For getsockopt(2), 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  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(2), 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 , 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(2) and set with setsockopt(2).
    Option                  Default     Description

    SO_ACCEPTCONN           0 (off)     socket is listen()ing

    SO_BROADCAST            0 (off)     enables permission to transmit
                                        broadcast messages

    SO_DEBUG                0 (off)     enables recording of debugging
                                        information

    SO_DONTROUTE            0 (off)     enables routing bypass for outgoing
                                        messages

    SO_ERROR                N/A         get and clear error on the socket
                                        (get only)

    SO_EXCLUSIVEADDRUSE     0 (off)     enables a socket to be bound for
                                        exclusive access

    SO_KEEPALIVE            0 (off)     enables keep connections alive

    SO_LINGER               0 (off)     linger on close if data present

    SO_OOBINLINE            0 (off)     enables reception of out-of-band
                                        data in band

    SO_RCVBUF               ?           set buffer size for input

    SO_REUSEADDR            0 (off)     enables local address reuse

    SO_SNDBUF               ?           set buffer size for output

    SO_TYPE                 N/A         get the type of the socket (get
                                        only)

    TCP_NODELAY             0 (off)     disables the Nagle algorithm

    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(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_DEBUG enables debugging in the underlying protocol modules.

    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_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 through a SIGPIPE signal when attempting to send data.

    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(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(2) 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.

    SO_REUSEADDR indicates that the rules used in validating addresses
    supplied in a bind(2) call should allow reuse of local addresses.

    The TCP_NODELAY option disables the Nagle algorithm for minimizing network
    congestion. Briefly, the algorithm requires that TCP segments not be sent
    until all outstanding data is acknowledged, or there's a maximum segment
    size packet to send. The stack is allowed to condense data into multibyte
    segments. Most applications are not affected by the Nagle algorithm and
    therefore should not set TCP_NODELAY. Some applications are affected:
    *     Applications that do two or more small data sends and that expect
          immediate responses from each.
    *     Applications that need a steady flow of data.

    A mouse- or pointer-using application such as an X Server is an
    application that should disable the Nagle algorithm; it needs to track and
    respond to the mouse movements.

  RETURN VALUES

    Both getsockopt(2) and setsockopt(2) return 0 if they succeed. If they
    fail, they return -1 and set errno to indicate the error.

  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(2), 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)

  USAGE NOTES

    All of these functions are thread safe.

    All of these functions are async-signal safe.