 |
Index for
Section 2 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getsockopt(2)
NAME
getsockopt - Get socket options
SYNOPSIS
#include <sys/socket.h>
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
compatibility (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(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry 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 interpreted 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 following 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 cluster 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 recommended, 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 connection 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() function if data is
present. 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 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 complete. 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
following 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 operation 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.
SEE ALSO
Functions: bind(2), close(2), endprotoent(3), getprotobynumber(3),
getprotoent(3), setprotoent(3), setsockopt(2), socket(2).
NetworkInformation: ip(7), tcp(7).
Standards: standards(5).
Network Programmer's Guide
|
Index for
Section 2 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|