unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



getsockopt(2)							getsockopt(2)



NAME

  getsockopt - Gets socket options

SYNOPSIS

  #include <&lt;sys/socket.h>&gt;
  int getsockopt (
	  int socket,
	  int level,
	  int option_nam,
	  void *option_value,
	  socklen_t *option_len	);

  [XNS4.0]  The	definition of the getsockopt() function	in XNS4.0 uses a
  size_t data type instead of a	socklen_t data type as specified in XNS5.0
  (the previous	definition).

  [Tru64 UNIX]	The following definition of the	getsockopt() function does
  not conform to current standards and is supported only for backward compa-
  tibility (see	standards(5)):

  int getsockopt (
	  int socket,
	  int level,
	  int option_nam,
	  char *option_value,
	  int *option_len );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  getsockopt():	 XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  socket    Specifies the file descriptor for the socket.

  level	    Specifies the protocol level at which the option resides.  To
	    retrieve options at	the socket level, specify the level parameter
	    as SOL_SOCKET.  To retrieve	options	at other levels, supply	the
	    appropriate	protocol number	for the	protocol controlling the
	    option.  For example, to indicate that an option will be inter-
	    preted by the TCP protocol,	set level to the protocol number of
	    TCP, as defined in the netinet/in.h	header file, or	as determined
	    by using the getprotobyname() function.

  option_nam
	    Specifies a	single option to be retrieved.	The socket level
	    options can	be enabled or disabled by the setsockopt() function.
	    The	getsockopt() function retrieves	information about the follow-
	    ing	options:

	    SO_ACCEPTCONN
		      Reports whether socket listening is enabled.  This
		      option returns an	int value.

	    SO_BROADCAST
		      Reports whether transmission of broadcast	messages is
		      supported.  This option returns an int value.

	    SO_CLUA_DEFAULT_SRC
		      [Tru64 UNIX]  In a cluster, reports whether the socket
		      will use the default cluster alias as its	source
		      address.

	    SO_CLUA_IN_NOALIAS
		      [Tru64 UNIX]  In a cluster, reports whether the socket
		      can only receive packets addressed to this cluster
		      member.

	    SO_CLUA_IN_NOLOCAL
		      [Tru64 UNIX]  In a cluster, reports whether the socket
		      must receive packets addressed to	a cluster alias	and
		      will drop	any packets that are not addressed to a	clus-
		      ter alias.

	    SO_DEBUG  Reports whether debugging	information is being
		      recorded.	 This option returns an	int value.

	    SO_DONTROUTE
		      Reports whether outgoing messages	should bypass the
		      standard routing facilities.  The	destination must be
		      on a directly-connected network; messages	are directed
		      to the appropriate network interface.  The protocol in
		      use determines the effect	of this	option.	 (Not recom-
		      mended, for debugging purposes only.)  This option
		      returns an int value.

	    SO_ERROR  Reports information about	error status and clears	it.
		      This option returns an int value.

	    SO_KEEPALIVE
		      Reports whether connections are kept active with
		      periodic transmission of messages.  If the connected
		      socket fails to respond to these messages, the connec-
		      tion is broken and processes using that socket are
		      notified with a SIGPIPE signal.  This option returns an
		      int value.

	    SO_LINGER Reports whether the socket lingers on a close() func-
		      tion if data is present.	If SO_LINGER is	set, the sys-
		      tem blocks the process during the	close()	function
		      until it can transmit the	data or	until the time
		      expires.	If SO_LINGER is	not specified, and a close()
		      function is issued, the system handles the call in a
		      way that allows the process to continue as quickly as
		      possible.	 This option returns an	struct linger value.

	    SO_OOBINLINE
		      Reports whether the socket leaves	received out-of-band
		      data (data marked	urgent)	in line.  This option returns
		      an int value.

	    SO_RCVBUF Reports receive buffer size information.	This option
		      returns an int value.

	    SO_RCVLOWAT
		      Reports the minimum number of bytes (low-water mark)
		      for socket receive operations.  The default value	is 1.
		      If the value is set to a larger value, blocking receive
		      calls wait until they receive either the low water mark
		      value or the requested value (whichever is smaller).
		      The calls	might return less than the water mark if an
		      error occurs, a signal is	received, or type of data in
		      the receive queue	is different than that returned.
		      This option returns an int value.

	    SO_RCVTIMEO
		      Reports receive time-out information.  This option
		      returns a	struct timeval value that specifies the
		      amount of	time to	wait for a receive operation to	com-
		      plete.  If a receive operation has blocked for the
		      specified	amount of time without receiving additional
		      data, it returns with a partial error count or errno
		      set to [EAGAIN] or [EWOULDBLOCK].	 The default is	0
		      (zero), which indicates that a receive operation will
		      not time out.

	    SO_RESVPORT
		      [Tru64 UNIX]   In	a cluster, reports whether an attempt
		      to bind the socket to a port in the reserved range
		      (512-1024) will fail if the port is marked static.

	    SO_REUSEADDR
		      Reports whether the rules	used in	validating addresses
		      supplied by a bind() function should allow reuse of
		      local addresses.	This option returns an int value.

	    SO_REUSEALIASPORT
		      [Tru64 UNIX]  In a cluster, reports whether the socket
		      can reuse	a locked cluster alias port.

	    SO_SNDBUF Reports send buffer size information.  This option
		      returns an int value.

	    SO_SNDLOWAT
		      Reports the minimum number of bytes (low-water mark)
		      for socket transmit operations.  Non-blocking transmit
		      operations process no data if flow control does not
		      allow either the send low	water mark value or the
		      entire request (whichever	is smaller) to be processed.
		      This option returns an int value.

	    SO_SNDTIMEO
		      Reports send time-out information. This option returns
		      a	struct timeval value that specifies the	amount of
		      time a transmit function blocks when flow	control
		      prevents the transmission	of data.  If a transmit
		      operation	blocks for this	amount of time without
		      transmitting data, it returns with a partial error
		      count or errno set to [EAGAIN] or	[EWOULDBLOCK].	The
		      default is 0 (zero), which indicates that	a transmit
		      operation	will not time out.

	    SO_TYPE   Reports the socket type.	This option returns an int
		      value.

	    SO_USELOOPBACK
		      Only valid for routing sockets.  Reports whether the
		      sender receives a	copy of	each message.  This option
		      returns an int value.
  [Tru64 UNIX]	 Options at other protocol levels vary in format and name.
  See the tcp(7) and ip(7) reference pages for more information	on option
  names	relevant for TCP and IP	options	respectively.


					  Note
       [Tru64 UNIX]   The default values for socket level options like
       SO_SENDBUF, SO_RCVBUF, SO_SNDLOWAT, and SO_RCVLOWAT are not constant
       across different	protocols and implementations.	Use the	getsockopt(2)
       routine to obtain the default values programmatically.

  option_value
	    The	address	of a buffer.

  option_len
	    Specifies the length of buffer pointed to by option_value.	The
	    option_len parameter initially contains the	size of	the buffer
	    pointed to by the option_value parameter.  On return, the
	    option_len parameter is modified to	indicate the actual size of
	    the	value returned.	 If no option value is supplied	or returned,
	    the	option_value parameter can be 0	(zero).
	    Options at other protocol levels vary in format and	name.

DESCRIPTION

  The getsockopt() function allows an application program to query socket
  options.  The	calling	program	specifies the name of the socket, the name of
  the option, and a place to store the requested information.  The operating
  system gets the socket option	information from its internal data structures
  and passes the requested information back to the calling program.

  Options may exist at multiple	protocol levels.  They are always present at
  the uppermost	socket level.  When retrieving socket options, specify the
  level	at which the option resides and	the name of the	option.

RETURN VALUES

  Upon successful completion, the getsockopt() function	returns	a value	of 0
  (zero).  Otherwise, a	value of -1 is returned, and errno is set to indicate
  the error.

ERRORS

  If the getsockopt() function fails, errno may	be set to one of the follow-
  ing values:

  [EACCES]  The	calling	process	does not have appropriate permissions.

  [EBADF]   The	socket parameter is not	valid.

  [EDOM]    [POSIX]  The send and receive timeout values are too large to fit
	    in the timeout fields of the socket	structure.

  [EFAULT]  The	address	pointed	to by the option_value parameter is not	in a
	    valid (writable) part of the process space,	or the option_len
	    parameter is not in	a valid	part of	the process address space.

  [EINVAL]  The	option_value or	option_len parameter is	invalid; or the
	    socket is shut down.

  [ENOBUFS] Insufficient resources are available in the	system to complete
	    the	call.

  [ENOPROTOOPT]
	    The	option is unknown.

  [ENOSR]   The	available STREAMS resources were insufficient for the opera-
	    tion to complete.

  [ENOTSOCK]
	    The	socket parameter refers	to a file, not a socket.

  [EOPNOTSUPP]
	    [XNS4.0]  The operation is not supported by	the socket protocol.

RELATED	INFORMATION

  Functions: bind(2), close(2),	endprotoent(3),	getprotobynumber(3), getpro-
  toent(3), setprotoent(3), setsockopt(2), socket(2).

  Network Information: ip(7), tcp(7).

  Standards: standards(5).