unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 getsockopt(2)						       getsockopt(2)




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

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

      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)
      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 Release 11i: November 2000






 getsockopt(2)							getsockopt(2)




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

 DESCRIPTION
      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 tcp(7P) and ip(7P).

      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 Release 11i: November 2000






 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 Release 11i: November 2000






 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 protocol-
				    dependent; see individual protocol
				    manual entries, such as tcp(7P) (default



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 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 Release 11i: November 2000






 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 Release 11i: November 2000






 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
      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
      getsockopt() and setsockopt() return the following values:

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

 ERRORS
      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
      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 Release 11i: November 2000






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

 MULTITHREAD USAGE
      The getsockopt() and setsockopt() system calls are thread-safe.  They
      each have a cancellation point; and they are async-cancel safe,
      async-signal safe, and fork-safe.

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

 SEE ALSO
      socket(2), getprotoent(3N), af_ccitt(7F), tcp(7P), udp(7P), unix(7P),
      xopen_networking(7).

 STANDARDS CONFORMANCE
      getsockopt(): XPG4


























 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000