Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GETSOCKOPT(2)		  FreeBSD System Calls Manual		 GETSOCKOPT(2)

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

SYNOPSIS
     #include <sys/socket.h>

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

DESCRIPTION
     getsockopt() and setsockopt() manipulate the 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	op-
     tions at any other	level the protocol number of the appropriate protocol
     controlling the option is supplied.  For example, to indicate that	an op-
     tion is to	be interpreted by the TCP protocol, level should be set	to the
     protocol number of	TCP; see getprotoent(3).

     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	of the buffer
     pointed to	by optval, and modified	on return to indicate the actual size
     of	the value returned.  If	no option value	is to be supplied or returned,
     optval may	be NULL.

     optname and any specified options are passed uninterpreted	to the appro-
     priate 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	4 of the manual.

     Most socket-level options utilize an int parameter	for optval.  For
     setsockopt(), the parameter should	be non-zero to enable a	boolean	op-
     tion, 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).  SO_SNDTIMEO and
     SO_RCVTIMEO use a struct timeval parameter, defined in <sys/time.h>.

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

	   SO_DEBUG	 enables recording of debugging	information
	   SO_REUSEADDR	 enables local address reuse
	   SO_REUSEPORT	 enables duplicate address and port bindings
	   SO_KEEPALIVE	 enables keep connections alive
	   SO_DONTROUTE	 enables routing bypass; not supported
	   SO_LINGER	 linger	on close if data present
	   SO_BROADCAST	 enables permission to transmit	broadcast messages
	   SO_OOBINLINE	 enables reception of out-of-band data in band
	   SO_BINDANY	 enables binding to any	address
	   SO_SNDBUF	 set buffer size for output
	   SO_RCVBUF	 set buffer size for input
	   SO_SNDLOWAT	 set minimum count for output
	   SO_RCVLOWAT	 set minimum count for input
	   SO_SNDTIMEO	 set timeout value for output
	   SO_RCVTIMEO	 set timeout value for input
	   SO_TIMESTAMP	 enables reception of a	timestamp with datagrams
	   SO_PEERCRED	 get the credentials from other	side of	connection
	   SO_RTABLE	 set the routing table used for	route lookups
	   SO_SPLICE	 splice	two sockets together or	get data length
	   SO_ZEROIZE	 clear all memory containing user supplied data
	   SO_TYPE	 get the type of the socket (get only)
	   SO_ERROR	 get and clear error on	the socket (get	only)
	   SO_DOMAIN	 get the domain	of the socket (get only)
	   SO_PROTOCOL	 get the protocol of the socket	(get only)

     SO_DEBUG enables debugging	in the underlying protocol modules.  Translit-
     erate the protocol	trace with trpt(8).  SO_REUSEADDR indicates that the
     rules used	in validating addresses	supplied in a bind(2) call should al-
     low reuse of local	addresses by callers with the same user	ID (or the su-
     peruser).	SO_REUSEPORT allows completely duplicate bindings by multiple
     processes if they all set SO_REUSEPORT before binding the port.  This op-
     tion permits multiple instances of	a program to each receive UDP/IP mul-
     ticast or broadcast datagrams destined for	the bound port.	 SO_KEEPALIVE
     enables the periodic transmission of messages on a	connected socket.
     Should the	connected party	fail to	respond	to these messages, the connec-
     tion is considered	broken and processes using the socket are notified via
     a SIGPIPE signal when attempting to send data.

     SO_LINGER controls	the action taken when unsent messages are queued on
     socket and	a close(2) is performed.  If the socket	promises reliable de-
     livery of data and	SO_LINGER is set, the system will block	the process on
     the close(2) attempt until	it is able to transmit the data	or until it
     decides it	is unable to deliver the information (a	timeout	period mea-
     sured in seconds, termed the linger interval, is specified	in the
     setsockopt() call when SO_LINGER is requested).  If SO_LINGER is disabled
     and a close(2) 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 nor-
     mal data input queue as received; it will then be accessible with recv(2)
     or	read(2)	calls without the MSG_OOB flag.	 Some protocols	always behave
     as	if this	option is set.

     SO_BINDANY	allows the socket to be	bound to addresses which are not local
     to	the machine, so	it can be used to make a transparent proxy.  Note that
     this option is limited to the superuser.  In order	to receive packets for
     these addresses, SO_BINDANY needs to be combined with matching outgoing
     pf(4) rules with the divert-reply parameter.  For example,	with the fol-
     lowing rule the socket receives packets for 192.168.0.10 even if it is
     not a local address:

	   pass	out inet from 192.168.0.10 divert-reply

     SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes al-
     located 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 incoming data.  The system	places an absolute
     limit on these values.

     SO_SNDLOWAT is an option to set the minimum count for output operations.
     Most output operations process all	of the data supplied by	the call, de-
     livering data to the protocol for transmission and	blocking as necessary
     for flow control.	Nonblocking output operations will process as much
     data as permitted subject to flow control without blocking, but will
     process no	data if	flow control does not allow the	smaller	of the low wa-
     ter mark value or the entire request to be	processed.  A select(2)	or
     poll(2) operation testing the ability to write to a socket	will return
     true only if the low water	mark amount could be processed.	 The default
     value for SO_SNDLOWAT is set to a convenient size for network efficiency,
     often 1024.  SO_RCVLOWAT is an option to set the minimum count for	input
     operations.  In general, receive calls will block until any (non-zero)
     amount of data is received, then return with the smaller of the amount
     available or the amount requested.	 The default value for SO_RCVLOWAT is
     1.	 If SO_RCVLOWAT	is set to a larger value, blocking receive calls nor-
     mally wait	until they have	received the smaller of	the low	water mark
     value or the requested amount.  Receive calls may still return less than
     the low water mark	if an error occurs, a signal is	caught,	or the type of
     data next in the receive queue is different than that returned.

     SO_SNDTIMEO is an option to set a timeout value for output	operations.
     It	accepts	a struct timeval parameter with	the number of seconds and mi-
     croseconds	used to	limit waits for	output operations to complete.	If a
     send operation has	blocked	for this much time, it returns with a partial
     count or with the error EWOULDBLOCK if no data was	sent.  In the current
     implementation, this timer	is restarted each time additional data are de-
     livered to	the protocol, implying that the	limit applies to output	por-
     tions ranging in size from	the low	water mark to the high water mark for
     output.  SO_RCVTIMEO is an	option to set a	timeout	value for input	opera-
     tions.  It	accepts	a struct timeval parameter with	the number of seconds
     and microseconds used to limit waits for input operations to complete.
     In	the current implementation, this timer is restarted each time addi-
     tional data are received by the protocol, and thus	the limit is in	effect
     an	inactivity timer.  If a	receive	operation has been blocked for this
     much time without receiving additional data, it returns with a short
     count or with the error EWOULDBLOCK if no data were received.

     If	the SO_TIMESTAMP option	is enabled on a	SOCK_DGRAM socket, the
     recvmsg(2)	call will return a timestamp corresponding to when the data-
     gram was received.	 The msg_control field in the msghdr structure points
     to	a buffer that contains a cmsghdr structure followed by a struct
     timeval.  The cmsghdr fields have the following values:

	   cmsg_len = CMSG_LEN(sizeof(struct timeval))
	   cmsg_level =	SOL_SOCKET
	   cmsg_type = SCM_TIMESTAMP

     SO_PEERCRED fetches the struct sockpeercred credentials from the other
     side of the connection (currently only possible on	AF_UNIX	sockets).
     These credentials are from	the time that bind(2), connect(2) or
     socketpair(2) were	called.

     The SO_RTABLE option gets or sets the routing table which will be used by
     the socket	for address lookups.  If a protocol family of the socket
     doesn't support switching routing tables, the ENOPROTOOPT error is	re-
     turned.  Only the superuser is allowed to change the routing table	if it
     is	already	set to a non-zero value.  A socket's chosen routing table is
     initialized from the process's configuration, previously selected using
     setrtable(2).

     SO_SPLICE can splice together two TCP or UDP sockets for unidirectional
     zero-copy data transfers.	Splice also the	other way around to get	bidi-
     rectional data flow.  Both	sockets	must be	of the same type.  In the
     first form, setsockopt() is called	with the source	socket s and the drain
     socket's int file descriptor as optval.  In the second form, optval is a
     struct splice with	the drain socket in sp_fd, a positive maximum number
     of	bytes or 0 in sp_max and an idle timeout sp_idle in the	form of	a
     struct timeval.  If -1 is given as	drain socket, the source socket	s gets
     unspliced.	 Otherwise the spliced data transfer continues within the ker-
     nel until the optional maximum is reached,	one of the connections termi-
     nates, idle timeout expires or an error occurs.  A	successful select(2),
     poll(2), or kqueue(2) operation testing the ability to read from the
     source socket indicates that the splicing has terminated.	When one of
     the sockets gets closed, splicing ends.  The error	status can be examined
     with SO_ERROR at the source socket.  The ELOOP error is set if userland
     created a loop by splicing	sockets	connected to localhost.	 The ETIMEDOUT
     error is set if there was no data transferred between two sockets during
     the sp_idle period	of time.  The EFBIG error is set after exactly sp_max
     bytes have	been transferred.  Note	that if	a maximum is given, it is only
     guaranteed	that no	more bytes are transferred.  A short splice can	hap-
     pen, but then a second call to splice will	transfer the remaining data
     immediately.  The SO_SPLICE option	with getsockopt() and an off_t value
     as	optval can be used to retrieve the number of bytes transferred so far
     from the source socket s.	A successful new splice	resets this number.

     Userland may write	sensitive data into a socket.  If SO_ZEROIZE is	set,
     overwrite kernel memory after sending data.

     Finally, SO_TYPE, SO_DOMAIN, SO_PROTOCOL 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_DOMAIN returns the domain of the socket, such as AF_INET.  SO_PROTOCOL
     returns the protocol of the socket	such as	IPPROTO_TCP.  SO_ERROR returns
     any pending error 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.

RETURN VALUES
     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the
     error.

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

     [EOPNOTSUPP]	The option is unsupported.

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

SEE ALSO
     connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2),
     getprotoent(3), divert(4),	pf.conf(5), protocols(5), sosplice(9)

STANDARDS
     The getsockopt() and setsockopt() functions conform to IEEE Std
     1003.1-2008 ("POSIX.1").

HISTORY
     The getsockopt() system call appeared in 4.1cBSD.

BUGS
     Several of	the socket options should be handled at	lower levels of	the
     system.

FreeBSD	13.0		       February	4, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getsockopt&sektion=2&manpath=OpenBSD+6.9>

home | help