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

  man pages->IRIX man pages -> standard/getsockopt (2)              



NAME    [Toc]    [Back]

     getsockopt, setsockopt - get and set options on sockets

C SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #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);

DESCRIPTION    [Toc]    [Back]

     Getsockopt	and setsockopt manipulate options associated with a socket.
     Options may exist at multiple protocol levels; they are always present at
     the uppermost ``socket'' level.

     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(3N).

     The parameters optval and optlen are used to access option	values for
     setsockopt.  For getsockopt they identify a buffer	in which the value for
     the requested option(s) are to be returned.  For getsockopt, optlen is a
     value-result parameter, initially containing the size in bytes of the
     buffer pointed to by optval, and modified on return to indicate the
     actual size of the	value returned.	 If the	size of	the option value is
     greater than the value of optlen, then the	option will be truncated
     silently to optlen	bytes.

     If	no option value	is to be supplied or returned, optval may be supplied
     as	0.

     Optname and any specified options are passed uninterpreted	to the
     appropriate protocol module for interpretation.  The include file
     <sys/socket.h> contains definitions for ``socket''	level options,
     described below.  Options at other	protocol levels	vary in	format and
     name; consult the appropriate entries in section (7P).

     Most socket-level options listed in the table below take an int parameter
     for optval.  For setsockopt, the parameter	should 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 <sys/socket.h>, which specifies the
     desired state of the option and the linger	interval (see below).

									Page 1


     The following options are recognized at the socket	level.	Except as
     noted, each may be	examined with getsockopt and set with setsockopt.

     SO_DEBUG	    toggle recording of	debugging information
     SO_REUSEADDR   toggle local address reuse
     SO_KEEPALIVE   toggle keep	connections alive
     SO_DONTROUTE   toggle routing bypass for outgoing messages
     SO_LINGER	    linger on close if data present
     SO_BROADCAST   toggle permission to transmit broadcast messages
     SO_OOBINLINE   toggle reception of	out-of-band data in band
     SO_REUSEPORT   toggle local port reuse for	multicast programs
     SO_SNDBUF	    set	buffer size for	output
     SO_RCVBUF	    set	buffer size for	input
     SO_TYPE	    get	the type of the	socket (get only)
     SO_ERROR	    get	and clear error	on the socket (get only)

     SO_DEBUG enables debugging	in the underlying protocol modules.
     SO_REUSEADDR indicates that the rules used	in validating addresses
     supplied in a bind(2) call	should allow reuse of local addresses.
     SO_REUSEPORT indicates that the rules used	in validating ports supplied
     in	a bind(2) call should allow reuse of local ports. It allows multiple
     programs to receive UDP multicast/broadcast datagrams on the same port if
     they all set SO_REUSEPORT before binding the port.	 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 via a
     SIGPIPE signal.  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_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 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 call when SO_LINGER
     is	requested). If SO_LINGER is disabled and a close is issued, the	system
     will process the close in a manner	that allows the	process	to continue as
     quickly as	possible.

     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
     or	read calls without the MSG_OOB flag.  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

									Page 2


     incoming data.  The system	places an absolute limit on these values.
     Finally, SO_TYPE and SO_ERROR are options used only with getsockopt.

     SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is	useful
     for servers that inherit sockets on startup.  SO_ERROR returns any
     pending error status on the socket	and clears the error status. It	may be
     used to check for asynchronous errors on connected	datagram sockets or
     for other asynchronous errors.  The error status is an errno value	as
     described in intro(2).

RETURN VALUE    [Toc]    [Back]

     A 0 is returned if	the call succeeds, -1 if it fails.

ERRORS    [Toc]    [Back]

     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,
			 this error may	also be	returned if optlen is not in a
			 valid part of the process address space.

     [EINVAL]		 The option length is too small. Most socket-level
			 options expect	optlen to be sizeof(int).

SEE ALSO    [Toc]    [Back]

     ioctl(2), socket(2), getprotoent(3N), ip(7P), tcp(7P), udp(7P)

NOTE    [Toc]    [Back]

     ABI-compliant versions of the above calls can be obtained from

BUGS    [Toc]    [Back]

     Several of	the socket options should be handled at	lower levels of	the

									PPPPaaaaggggeeee 3333
[ 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