unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



setsockopt(2)							setsockopt(2)



NAME
  setsockopt - Sets socket options

SYNOPSIS

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

  int setsockopt (
	  int socket,
	  int level,
	  int option_name,
	  const	void *option_value,
	  socklen_t option_len );

  [XNS4.0]   The definition of the setsockopt()	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	setsockopt() function does
  not conform to current standards and is supported only for backward compa-
  tibility (see	standards(5)):

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

  int setsockopt (
	  int socket,
	  int level,
	  int option_name,
	  char *option_value,
	  int option_len );

STANDARDS

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

  setsockopt():	 [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 set
	    options at the socket level, specify the level parameter as
	    SOL_SOCKET.	 To set	options	at other levels, supply	the appropri-
	    ate	protocol number	for the	protocol controlling the option.  For
	    example, to	indicate that an option	will be	interpreted by the
	    TCP	protocol, set level to the protocol number of TCP, as defined
	    in the netinet/in.h	file or	as determined by using the getproto-
	    byname() function.

  option_name
	    Specifies the option to set.  The option_name parameter and	any
	    specified options are passed uninterpreted to the appropriate
	    protocol module for	interpretation.	 The sys/socket.h header file
	    defines the	socket level options.  The socket level	options	can
	    be enabled or disabled.  The options are:

	    SO_BROADCAST
		Permits	sending	of broadcast messages.	This option takes an
		int value.

	    SO_CLUA_DEFAULT_SRC
		[Tru64 UNIX]  In a cluster, specifies that if the local
		address	has not	already	been set through a call	to bind(),
		the socket will	use the	default	cluster	alias as its source
		address.

	    SO_CLUA_IN_NOALIAS
		[Tru64 UNIX]  In a cluster, specifies that the socket can
		only receive packets addressed to this cluster member.
		Attempts to bind the socket to a cluster alias address will
		fail.  A bind to an dynamic port (greater than or equal	to
		IPPORT_RESERVED	and less than IPPORT_USERRESERVED) will	not
		result in that port being dedicated (or	"locked") for use by
		a single node in the cluster.  A bind to a privileged
		reserved port with a wildcard address (INADDR_ANY or
		in6addr_any) will not result in	that port being	locked.	 The
		source address for outgoing UDP	sends or TCP connection
		requests will be a local host address (never a cluster alias
		address).  The SO_CLUA_IN_NOLOCAL and SO_CLUA_IN_NOALIAS
		options	are mutually exclusive.

	    SO_CLUA_IN_NOLOCAL
		[Tru64 UNIX]  In a cluster, specifies that the socket must
		receive	packets	addressed to a cluster alias and will drop
		any packets that are not addressed to a	cluster	alias.	The
		SO_CLUA_IN_NOLOCAL and SO_CLUA_IN_NOALIAS options are mutu-
		ally exclusive.

	    SO_DEBUG
		Turns on recording of debugging	information.  This option
		enables	or disables debugging in the underlying	protocol
		modules.  This option takes an int value.

	    SO_DONTROUTE
		Indicates that outgoing	messages should	bypass the standard
		routing	facilities.  Instead, they are directed	to the
		appropriate network interface according	to the network por-
		tion of	the destination	address.

	    SO_KEEPALIVE
		Keeps connections active.  Enables the periodic	transmission
		of messages on a connected socket.  If the connected socket
		fails to respond to these messages, the	connection is broken
		and processes using that socket	are notified with a SIGPIPE
		signal.

	    SO_LINGER
		Lingers	on a close() function if data is present.  This
		option controls	the action taken when unsent messages queue
		on a socket and	a close() function is performed.  If
		SO_LINGER is set, the system 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 takes a struct linger value, defined in the
		sys/socket.h header file, to specify the state of the option
		and linger interval.

	    SO_OOBINLINE
		Leaves received	out-of-band data (data marked urgent) in
		line.  This option takes an int	value.

	    SO_RCVBUF
		Sets receive buffer size.  This	option takes an	int value.

	    SO_RCVLOWAT
		Reports	the minimum number of bytes (low-water mark) for
		socket receive operations.  The	default	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 takes an	int value.

	    SO_RCVTIMEO
		Sets receive time out.	This option takes a struct timeval
		value, defined in the sys/time.h header	file, to specify the
		amount of time towait for a receive operation to complete.
		If a receive operation has blocke for the specified amount of
		time without receiving additional data,	it returns with	a
		partial	error count or errno set to [EAGAIN] or	[EWOULD-
		BLOCK].	 The default is	0 (zero), which	indicates that a
		receive	operation will not time	out.

	    SO_RESVPORT
		[Tru64 UNIX]   In a cluster, an	attempt	to bind	the socket to
		a port in the reserved range (512-1024)	will fail if the port
		is marked static, either by a static entry for the port	in
		/etc/clua_services or through a	call to
		clua_registerservice() with the	CLUASRV_STATIC option.	The
		call to	bind() will return EADDRINUSE.

	    SO_REUSEADDR
		Specifies that the rules used in validating addresses sup-
		plied by a bind() function should allow	reuse of local
		addresses.  This option	takes an int value.

	    SO_REUSEALIASPORT
		[Tru64 UNIX]  In a cluster, specifies that the socket can
		reuse a	locked cluster alias port.  When this option is	set,
		a bind() is distributed	clusterwide.  A	distributed applica-
		tion can use this side-effect to determine whether or not a
		port is	in use.

	    SO_REUSEPORT
		[Tru64 UNIX]   Allows more than	one process to receive UDP
		datagrams destined for the same	port.  The bind	system call
		binding	a process to that port must be preceded	by a set-
		sockopt	system call specifying this option.

	    SO_SNDBUF
		Sets send buffer size.	This option takes an int value.

	    SO_SNDLOWAT
		Sets the minimum number	of bytes (low-water mark) for socket
		transmit operations.  Non-blocking transmit operations pro-
		cess 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 takes an	int value.

	    SO_SNDTIMEO
		Sets send time out.  This option takes a struct	timeval
		value, defined in the sys/time.h header	file, to specify 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_USELOOPBACK
		[Tru64 UNIX]   Valid only for routing sockets.	Determines if
		a sending socket receives a copy of its	own message.

	    [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 maximum values for socket level options like
       SO_SENDBUF, SO_RCVBUF, SO_SNDLOWAT, and SO_RCVLOWAT are governed	by
       the protocol limits, as well as its implementation.  Use	the get-
       sockopt(2) routine to verify the	values for these options after the
       socket connection has been established.

  option_value
	    To enable a	Boolean	option or integer value, set the option_value
	    parameter to a nonzero value.  To disable an option, set the
	    option_value parameter to 0	(zero).

  option_len
	    The	option_len parameter contains the size of the buffer pointed
	    to by the option_value parameter.

DESCRIPTION

  The setsockopt() function sets options associated with a socket.  Options
  may exist at multiple	protocol levels.  The SO_ options are always present
  at the uppermost socket level.

  The setsockopt() function provides an	application program with the means to
  control a socket communication.  An application program can use the set-
  sockopt() function to	enable debugging at the	protocol level,	allocate
  buffer space,	control	timeouts, or permit socket data	broadcasts.  The
  sys/socket.h file defines all	the options available to the setsockopt()
  function.

  When setting socket options, specify the protocol level at which the option
  resides and the name of the option.

  Use the option_value and option_len parameters to access option values for
  the setsockopt() function.  These parameters identify	a buffer in which the
  value	for the	requested option or options is returned.

RETURN VALUES

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




ERRORS

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

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

  [EBADF]   The	socket parameter is not	valid.

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

  [EINVAL]  The	option_len parameter is	not valid.

  [EISCONN] The	socket is already connected; the specified option cannot be
	    set	when the socket	is in the connected state.

  [EFAULT]  The	option_value parameter is not in a readable part of the	user
	    address space.

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

  [ENOMEM]  The	system did not have sufficient memory to fulfill the request.

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

RELATED	INFORMATION

  Functions: bind(2), endprotoent(3), getsockopt(2), getprotobynumber(3),
  getprotoent(3), setprotoent(3), socket(2).

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

  Standards: standards(5).