*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> getsockopt (2)              
Title
Content
Arch
Section
 

p(7P)

Contents


 getsockopt(2)                                                 getsockopt(2)




 NAME    [Toc]    [Back]
      getsockopt(), setsockopt() - get and set options on sockets

 SYNOPSIS    [Toc]    [Back]
      #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
      );

    _XOPEN_SOURCE_EXTENDED Only (UNIX 98)
      int getsockopt(
          int         s,
          int         level,
          int         optname,
          void       *optval,
          socklen_t  *optlen
      );

      int setsockopt(
          int         s,
          int         level,
          int         optname,
          const void *optval,
          socklen_t   optlen
      );

    Obsolescent _XOPEN_SOURCE_EXTENDED Only (UNIX 95)    [Toc]    [Back]
      int getsockopt(
          int         s,
          int         level,
          int         optname,
          void       *optval,
          size_t     *optlen
      );

      int setsockopt(
          int         s,
          int         level,



 Hewlett-Packard Company            - 1 -    HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                  getsockopt(2)




          int         optname,
          const void *optval,
          size_t      optlen
      );

 DESCRIPTION    [Toc]    [Back]
      The getsockopt() and setsockopt() system calls manipulate options
      associated with a socket.  The socket is identified by the socket
      descriptor s.  Options can exist at multiple protocol levels, and they
      are always present at the uppermost "socket" level (see socket(2)).

      When manipulating socket options, the level at which the option
      resides (level) and the name of the option (optname) must be
      specified.  To manipulate options at the "socket" level, level is
      specified as SOL_SOCKET.  To specify options at another level, level
      should be the protocol number specified in <netinet/in.h> (for
      example, IPPROTO_TCP).

      The parameters optval and optlen specify the value of the option.
      optval is the address of the data structure that contains the option
      value, and optlen is the length of the data structure.  The type and
      value of the data structure that optval points to depends on the
      option.  For "boolean" options, the value may be zero (not set) or
      non-zero (set).  The value of other options depends on the purpose of
      the option.  Usually, neither optval nor optlen may be the NULL
      address or zero; see individual protocol manual entries for any
      exceptions, such as tc
.

      For setsockopt(), optval and optlen are used to pass information from
      the application to the system.  optval is the address of a location in
      memory that contains the option information to be passed to the
      system.  The parameter optlen is an integer value that specifies the
      size, in bytes, of the data structure pointed to by optval.

      For getsockopt(), optval and optlen are used to pass information from
      the system to the application.  The parameter optlen is the address of
      a variable.  Before calling getsockopt(), the application should set
      the value of the variable to the maximum size, in bytes, of the data
      structure pointed to by optval.  Normally, upon return, the variable
      pointed to by optlen is set to the actual size the data returned in
      the structure pointed to by optval, if getsockopt() returns without
      error.

      The following ``socket'' level option names (optname) are defined in
      <sys/socket.h>.  The type of the variable pointed to by optval is
      indicated in parentheses.  Options for other protocol levels are
      described in the individual protocol manual pages, such as tcp(7P) and
      ip(7P).

           SO_ACCEPTCONN            (int; boolean ) Returns a non-zero value
                                    if socket listening is enabled,



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                 getsockopt(2)




                                    otherwise returns a zero value.

           SO_BROADCAST             (int; boolean; SOCK_DGRAM sockets only)
                                    Allows the application to send messages
                                    to a broadcast address.  Default:
                                    disallowed.

                                    Note, the actual effect of this option
                                    is communication domain dependent.  In
                                    AF_INET domain, broadcasts are always
                                    allowed regardless of the value set for
                                    this option.  In AF_UNIX domain,
                                    broadcasts are not supported.  For
                                    validity in other domains, see
                                    individual product manual.

           SO_DEBUG                 (int; boolean; AF_INET SOCK_STREAM
                                    sockets only) Enables or disables the
                                    recording of internal debug information.
                                    Default: disabled.

           SO_DONTROUTE             (int; boolean; AF_INET sockets only)
                                    Causes outbound messages to bypass
                                    normal routing facilities.  Instead,
                                    messages are sent through the
                                    appropriate network interface based on
                                    the network portion of the destination
                                    address.  Default: disabled.

           SO_ERROR                 (int) Returns any pending error on the
                                    socket, and clears the error status.
                                    The value returned by SO_ERROR would be
                                    the value of errno after the next socket
                                    data transfer system call.

           SO_KEEPALIVE             (int; boolean; AF_INET SOCK_STREAM
                                    sockets only) If enabled, keeps an
                                    otherwise idle TCP connection active.
                                    Default: disabled.

           SO_LINGER                (struct linger; AF_INET SOCK_STREAM
                                    sockets only) Controls whether or not an
                                    application "lingers" (waits) if there
                                    are untransmitted data in the send
                                    socket buffer when the socket is closed.
                                    The data type struct linger is defined
                                    in <sys/socket.h>.  Default: disabled,
                                    as if l_onoff had been set to zero.
                                    (See details below.)





 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                 getsockopt(2)




           SO_OOBINLINE             (int; boolean; AF_INET SOCK_STREAM
                                    sockets only) If enabled, specifies that
                                    out-of-band data (TCP "urgent data")
                                    should be left "in-line" among the
                                    normal data stream.  Otherwise, one byte
                                    of out-of-band data is pulled out of the
                                    data stream, and it is accessible only
                                    by setting MSG_OOB in the flags
                                    parameter when the application reads the
                                    data (see recv(2)).  Default: disabled.

           SO_RCVBUF                (int) Specifies the maximum size, in
                                    bytes, of the receive socket buffer.
                                    For SOCK_DGRAM sockets, the receive
                                    buffer size may limit the maximum size
                                    of messages that the socket can receive.
                                    Default and maximum values are
                                    protocol-dependent; see individual
                                    protocol manual entries, such as tcp(7P)
                                    (default buffer size: 32768 bytes;
                                    maximum buffer size: 1073725440 bytes;
                                    maximum buffer size can be lowered using
                                    the ndd variable tcp_recv_hiwater_max)
                                    and udp(7P) (default buffer size:
                                    2147483647 bytes; maximum buffer size:
                                    2147483647 bytes; udp maximum receive
                                    buffer size can be lowered using the ndd
                                    parameter udp_recv_hiwater_max).

           SO_REUSEADDR             (int; boolean; AF_INET sockets only) If
                                    enabled, allows a local address to be
                                    reused in subsequent calls to bind().
                                    Default: disallowed.

           SO_REUSEPORT             (int; boolean; AF_INET sockets only) If
                                    enabled, allows a local address and port
                                    to be reused in subsequent calls to
                                    bind().  Default: disallowed.

           SO_SNDBUF                (int) Specifies the maximum size, in
                                    bytes, of the send socket buffer.  For
                                    SOCK_STREAM sockets, the send buffer
                                    size limits how much data can be queued
                                    for transmission before the application
                                    is blocked.  For SOCK_DGRAM sockets, the
                                    send buffer size may limit the maximum
                                    size of messages that the application
                                    can send through the socket.  Default
                                    and maximum values are protocoldependent;
 see individual protocol
                                    manual entries, such as tcp(7P) (default



 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                 getsockopt(2)




                                    send buffer size: 32768 bytes; maximum
                                    send buffer size: 2147483647 bytes;
                                    maximum buffer size can be lowered using
                                    the ndd variable tcp_xmit_hiwater_max)
                                    and udp(7P) (default send buffer size:
                                    65535 bytes; maximum send buffer size:
                                    2147483647 bytes).

           SO_TYPE                  (int) Returns the socket type.

           SO_USELOOPBACK           (int; boolean) Not used internally;
                                    provided only for compatibility.

      Setting the SO_BROADCAST option allows the application to send
      messages through the SOCK_DGRAM socket to a broadcast destination
      address.

      If SO_DONTROUTE is set, the system does not use the network routing
      tables when determining which interface to use to send an outbound
      message.  Instead, the system sends the message through the interface
      whose network address matches the network portion of the destination
      address.  If SO_DONTROUTE is not set (default), the system uses the
      network routing tables.

      If SO_KEEPALIVE is disabled (default), a TCP connection may remain
      idle until the connection is released at the protocol layer.  If
      SO_KEEPALIVE is enabled and the connection has been idle for two
      hours, TCP sends a packet to the remote socket, expecting the remote
      TCP to acknowledge that the connection is still active.  If the remote
      TCP does not respond in a timely manner, TCP continues to send
      keepalive packets according to the normal retransmission algorithm. If
      the remote TCP does not respond within a particular time limit, TCP
      drops the connection. The next socket system call (for example,
      recv()) returns an error, and errno is set to ETIMEDOUT.

      SO_LINGER controls the actions to be taken when there are
      untransmitted data in a SOCK_STREAM send socket buffer when the socket
      is closed, either due to an explicit call to close() or because the
      application terminates normally or abnormally.  The action is
      determined by the values of members of the struct linger data
      structure pointed to by optval in a call to setsockopt().  The data
      type struct linger is defined in <sys/socket.h>.  If l_onoff is zero
      (the default action), close() returns immediately, but the system
      tries to transmit any unsent data and release the protocol connection
      gracefully.  If l_onoff is non-zero and l_linger is zero, close()
      returns immediately, any unsent data is discarded, and the protocol
      connection is aborted.  If both l_onoff and l_linger are non-zero,
      close() does not return until the system has tried to transmit all
      unsent data and release the connection gracefully.  In that case,
      close() can return an error, and errno may be set to ETIMEDOUT, if the
      system is unable to transmit the data after a protocol-defined time



 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                 getsockopt(2)




      limit.  Note that the value of l_linger is treated simply as a
      boolean; a non-zero value is not interpreted as a time limit( see
      _XOPEN_SOURCE_EXTENDED Only below).  SO_LINGER does not affect the
      actions taken when the function shutdown() is called.

      If SO_OOBINLINE is set, out-of-band data (TCP "urgent data") is left
      "in-line" among the normal data stream.  In that case, the SIOCATMARK
      ioctl() request must be used to determine if the inbound data stream
      has been read up to the point where the out-of-band data begins.  If
      multiple transmissions of out-of-band data are received before the
      application reads them, all of the data is left in-line; however,
      SIOCATMARK indicates the location of only the last transmission of
      out-of-band data.  If SO_OOBINLINE is not set (default), only one byte
      of out-of-band is saved.  This byte is pulled out of the normal data
      stream, and it is accessible only by setting MSG_OOB in the flags
      parameter when the application reads the data (see recv(2)).  In that
      case, if multiple transmissions of out-of-band data are received
      before the application reads them, previous bytes of out-of-band data
      are lost.

      Setting the SO_REUSEADDR option allows the local socket address to be
      reused in subsequent calls to bind().  This permits multiple
      SOCK_STREAM sockets to be bound to the same local address, as long as
      all existing sockets with the desired local address are in a connected
      state before bind() is called for a new socket.  For SOCK_DGRAM
      sockets, SO_REUSEADDR allows multiple sockets to receive UDP multicast
      datagrams addressed to the bound port number.  For all SOCK_DGRAM
      sockets bound to the same local address, SO_REUSEADDR must be set
      before calling bind().

      Setting the SO_REUSEPORT option allows multiple SOCK_DGRAM sockets to
      share the same address and port.  Each one of those sockets, including
      the first one to use that port, must specify this option before
      calling bind().

      SO_RCVBUF and SO_SNDBUF specify the maximum number of bytes that the
      system may allocate, as needed, for the receive and send buffers,
      respectively.  These limits are merely approximate because of the way
      in which memory is allocated.  For example, a large number of small
      transmissions may require more memory than the sum of the number of
      data bytes sent.  The default receive and send buffer sizes are
      protocol-specific.  For more information, see the appropriate manual
      entries, such as tcp(7P) and udp(7P).

      For SOCK_STREAM sockets, larger buffer sizes can improve performance.
      An application can increase the size of the receive buffer at any
      time; however, it can decrease the receive buffer size only prior to
      calling connect() or listen().  An application can increase or
      decrease the send buffer at any time.





 Hewlett-Packard Company            - 6 -   HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                 getsockopt(2)




      For SOCK_DGRAM sockets, the size of the receive and send buffers
      limits the size of the maximum datagram that can be received and sent,
      respectively.  These limits include socket buffer space that is also
      used to save the sender's socket address (struct sockaddr) which is
      associated with each datagram transmission.  The sender's socket
      address can be returned in the from parameter when recvfrom() is
      called (see recv(2)).

    AF_CCITT    [Toc]    [Back]
      SO_SNDBUF and SO_RCVBUF are the only options supported for sockets of
      the AF_CCITT address family.

    _XOPEN_SOURCE_EXTENDED Only
      The value of l_linger in the linger structure is interpreted as a time
      limit in seconds.

 RETURN VALUE    [Toc]    [Back]
      getsockopt() and setsockopt() return the following values:

            0   Successful completion.
           -1   Failure.  errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      If getsockopt() or setsockopt() fails, errno is set to one of the
      following values:

      [EBADF]             The argument s is not a valid descriptor.

      [EFAULT]            The optval or optlen address is not valid.

      [EINVAL]            The level or optlen value is not valid; or optval
                          is the NULL address; or the protocol connection
                          has been released.

      [ENOBUFS]           Insufficient memory is available for internal
                          system data structures.

      [ENOPROTOOPT]       The option is not recognized at the specified
                          option level.

      [ENOTSOCK]          The argument s is not a socket descriptor.

      [EOPNOTSUPP]        The option is not supported by the socket family
                          or socket type.

 OBSOLESCENCE    [Toc]    [Back]
      Currently, the socklen_t and size_t types are the same size.  This is
      compatible with both the UNIX 95 and UNIX 98 profiles.  However, in a
      future release, socklen_t might be a different size.  In that case,
      passing a size_t pointer will evoke compile-time warnings, which must
      be corrected in order for the application to behave correctly.



 Hewlett-Packard Company            - 7 -   HP-UX 11i Version 2: August 2003






 getsockopt(2)                                                 getsockopt(2)




      Applications that use socklen_t now, where appropriate, will avoid
      such migration problems.  On the other hand, applications that need to
      be portable to the UNIX 95 profile should follow the X/Open
      specification (see xopen_networking(7)).

 FUTURE DIRECTION    [Toc]    [Back]
      Currently, the default behavior is the HP-UX BSD Sockets; however, it
      might be changed to X/Open Sockets in a future release.  At that time,
      any HP-UX BSD Sockets behavior that is incompatible with X/Open
      Sockets might be obsoleted.  Applications that conform to the X/Open
      specification now will avoid migration problems (see
      xopen_networking(7)).

 AUTHOR    [Toc]    [Back]
      getsockopt() and setsockopt() were developed by HP and the University
      of California, Berkeley.

 SEE ALSO    [Toc]    [Back]
      socket(2), getprotoent(3N), thread_safety(5), tcp(7P), udp(7P),
      unix(7P), xopen_networking(7).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      getsockopt(): XPG4


 Hewlett-Packard Company            - 8 -   HP-UX 11i Version 2: August 2003
[ Back ]
      
      
 Similar pages
Name OS Title
connect Tru64 Connect two sockets
sockstat FreeBSD list open sockets
raw Linux Linux IPv4 raw sockets
ng_btsocket FreeBSD Bluetooth sockets layer
recvfrom Tru64 Receive messages from sockets
socketpair FreeBSD create a pair of connected sockets
socketpair Tru64 Create a pair of connected sockets
socketpair HP-UX create a pair of connected sockets
recv Tru64 Receive messages from connected sockets
fuser Linux identify processes using files or sockets
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service