[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 2
getsockopt Subroutine
Purpose
Gets options on sockets
Library
Standard C Library (libc.a)
Syntax
#include <sys/socket.h>
int getsockopt (Socket, Level, OptionName, OptionValue, OptionLength)
int Socket, Level, OptionName;
void * OptionValue;
socklen_t * OptionLength;
Description
The getsockopt subroutine 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 can exist at multiple protocol levels. They
are always present at the uppermost socket level. When retrieving socket options,
specify the level where the option resides and the name of the option.
All applications containing the getsockopt subroutine must be compiled with _BSD
set to a specific value. Acceptable values are 43 and 44. In addition, all
socket applications must include the BSD libbsd.a library.
Parameters
Socket |
Specifies the unique socket name. |
Level |
Specifies the protocol level where the option resides. Options can
be retrieved at the following levels:
- Socket level
- Specifies the Level parameter as the SOL_SOCKET option.
- Other levels
- Supplies 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 the Level parameter to the protocol
number of TCP, as defined in the netinet/in.h file.
|
OptionName |
Specifies a single option. The OptionName
parameter and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation. The sys/socket.h
file contains definitions for socket level options. The netinet/tcp.h file contains definitions for TCP protocol level options.
Socket-level options can be enabled or disabled; they operate in a toggle
fashion. The sys/atmsock.h file contains definitions
for ATM protocol level options.
The following list
defines socket protocol level options found in the sys/socket.h file:
- SO_DEBUG
- Specifies the recording of debugging information. This option enables
or disables debugging in the underlying protocol modules.
- SO_BROADCAST
- Specifies whether transmission of broadcast messages is supported.
The option enables or disables broadcast support.
- SO_CKSUMREV
- Enables performance enhancements in the protocol layers. If the protocol
supports this option, enabling causes the protocol to defer checksum verification
until the user's data is moved into the user's buffer (on recv, recvfrom, read, or recvmsg thread). This can cause applications to be awakened
when no data is available, in the case of a checksum error. In this case,
EAGAIN is returned. Applications that set this option must handle the EAGAIN
error code returned from a receive call.
- SO_REUSEADDR
- Specifies that the rules used in validating addresses supplied by
a bind subroutine should
allow reuse of a local port. A particular IP address can only be bound once
to the same port. This option enables or disables reuse of local ports.
SO_REUSEADDR allows an application
to explicitly deny subsequent bind subroutine to the port/address of the socket with SO_REUSEADDR set. This allows an application to block other applications
from binding with the bind
subroutine.
- SO_REUSEPORT
- Specifies that the rules used in validating addresses supplied by
a bind subroutine should
allow reuse of a local port/address combination. Each binding of the port/address
combination must specify the SO_REUSEPORT socket option.
This option enables or disables the reuse of local port/address combinations.
- SO_KEEPALIVE
- Monitors the activity of a connection by enabling or disabling the
periodic transmission of ACK messages on a connected socket. The idle interval
time can be designated using the TCP/IP no command. Broken connections are discussed in "Understanding Socket Types and Protocols" in AIX 5L Version 5.2 Communications Programming Concepts.
|
|
- SO_DONTROUTE
- Indicates outgoing messages should bypass the standard routing facilities.
Does not apply routing on outgoing messages. Directs messages to the appropriate
network interface according to the network portion of the destination address.
This option enables or disables routing of outgoing messages.
- SO_LINGER
- Lingers on a close
subroutine if data is present. This option controls the action taken when
an unsent messages queue exists for a socket, and a process performs a close subroutine on the socket.
If the SO_LINGER option is set, the system blocks the
process during the close subroutine until it can transmit
the data or until the time expires. If the SO_LINGER
option is not specified, and a close subroutine is issued,
the system handles the call in a way that allows the process to continue as
quickly as possible.
The sys/socket.h file defines
the linger structure that contains the l_linger value
for specifying linger time interval. If linger time is set to anything but
0, the system tries to send any messages queued on the socket. The maximum
value that l_linger can be set to is 65535.
- SO_OOBINLINE
- Leaves received out-of-band data (data marked urgent) in line. This
option enables or disables the receipt of out-of-band data.
- SO_SNDBUF
- Retrieves buffer size information.
- SO_RCVBUF
- Retrieves buffer size information.
- SO_SNDLOWAT
- Retrieves send buffer low-water mark information.
- SO_RCVLOWAT
- Retrieves receive buffer low-water mark information.
|
|
- SO_SNDTIMEO
- Retrieves time-out information. This option is settable, but currently
not used.
- SO_RCVTIMEO
- Retrieves time-out information. This option is settable, but currently
not used.
- SO_ERROR
- Retrieves information about error status and clears.
The following list defines TCP protocol level
options found in the netinet/tcp.h file:
- TCP_RFC1323
- Indicates whether RFC 1323 is enabled or disabled on the specified
socket. A non-zero OptionValue returned by the getsockopt subroutine indicates the RFC is enabled.
- TCP_NODELAY
- Specifies whether TCP should follow the Nagle algorithm for deciding
when to send data. By default TCP will follow the Nagle algorithm. To disable
this behavior, applications can enable TCP_NODELAY to
force TCP to always send data immediately. A non-zero OptionValue returned by the getsockopt subroutine
indicates TCP_NODELAY is enabled. For example, TCP_NODELAY should be used when there is an appliciation using TCP for
a request/response.
|
|
The following list defines ATM protocol level
options found in the sys/atmsock.h file:
- SO_ATM_PARM
- Retrieves all ATM parameters. This socket option can be used instead
of using individual sockets options described below. It uses the connect_ie structure defined in sys/call_ie.h file.
- SO_ATM_AAL_PARM
- Retrieves ATM AAL (Adaptation Layer) parameters. It uses the aal_parm structure defined in sys/call_ie.h file.
- SO_ATM_TRAFFIC_DES
- Retrieves ATM Traffic Descriptor values. It uses the traffic_desc structure defined in sys/call_ie.h
file.
- SO_ATM_BEARER
- Retrieves ATM Bearer capability information. It uses the bearer structure defined in sys/call_ie.h file.
- SO_ATM_BHLI
- Retrieves ATM Broadband High Layer Information. It uses the bhli structure defined in sys/call_ie.h file.
- SO_ATM_BLLI
- Retrieves ATM Broadband Low Layer Information. It uses the blli structure defined in sys/call_ie.h file.
- SO_ATM_QoS
- Retrieves ATM Ouality Of Service values. It uses the qos_parm structure defined in sys/call_ie.h file.
- SO_ATM_TRANSIT_SEL
- Retrieves ATM Transit Selector Carrier. It uses the transit_sel structure defined in sys/call_ie.h
file.
- SO_ATM_MAX_PEND
- Retrieves the number of outstanding transmit buffers that are permitted
before an error indication is returned to applications as a result of a transmit
operation. This option is only valid for non best effort types of virtual
circuits.
- SO_ATM_CAUSE
- Retrieves cause for the connection failure. It uses the cause_t structure defined in the sys/call_ie.h
file.
|
OptionValue |
Specifies a pointer to the address of a buffer. The OptionValue parameter takes an integer parameter. The OptionValue parameter should be set to a nonzero value to enable a Boolean
option or to a value of 0 to disable the option. The following options enable
and disable in the same manner:
- SO_DEBUG
- SO_REUSEADDR
- SO_KEEPALIVE
- SO_DONTROUTE
- SO_BROADCAST
- SO_OOBINLINE
- TCP_RFC1323
|
OptionLength |
Specifies the length of the OptionValue parameter.
The OptionLength parameter initially contains the
size of the buffer pointed to by the OptionValue parameter.
On return, the OptionLength parameter is modified
to indicate the actual size of the value returned. If no option value is supplied
or returned, the OptionValue parameter can be 0. |
Options at other protocol levels vary in format and
name.
IP level (IPPROTO_IP level)
options are defined as follows:
IP_DONTFRAG |
Get current IP_DONTFRAG option value. |
IP_FINDPMTU |
Get current PMTU value. |
IP_PMTUAGE |
Get current PMTU time out value. |
In the case of TCP protocol sockets:
IP_DONTGRAG |
Not supported. |
IP_FINDPMTU |
Get current PMTU value. |
IP_PMTUAGE |
Not supported. |
IPV6 level (IPPROTO_IPV6 level) options
are defined as follows:
IPV6_V6ONLY |
Determines whether the socket is restricted
to IPV6 communications only. |
Option Type: |
int (boolean interpretation) |
IPV6_UNICAST_HOPS |
Allows the user to determine the outgoing
hop limit value for unicast IPV6 packets. |
Option Type: |
int |
IPV6_MULTICAST_HOPS |
Allows the user to determine the outgoing
hop limit value for multicast IPV6 packets. |
Option Type: |
int |
IPV6_MULTICAST_IF |
Allows the user to determine the interface
being used for outgoing multicast packets. |
Option Type: |
unsigned int |
IPV6_MULTICAST_LOOP |
If a multicast datagram is sent to
a group that the sending host belongs, a copy of the datagram is looped back
by the IP layer for local delivery (if the option is set to 1). If the option
is set to 0, a copy is not looped back. |
Option Type: |
unsigned int |
ICMPV6 level (IPPROTO_ICMPV6 level)
options are defined as follows:
ICMP6_FILTER |
Allows the user to filter ICMPV6 messages
by the ICMPV6 type field. If no filter was set, the default kernel filter
will be returned. |
Option Type: |
The icmp6_filter structure defined
in the netinet/icmp6.h file. |
Return Values
Upon successful completion, the getsockopt subroutine returns a value of 0.
If the getsockopt subroutine
is unsuccessful, the subroutine handler performs the following actions:
- Returns a value of -1 to the calling program.
- Moves an error code, indicating the specific error, into the errno global variable.
Upon successful completion of the IPPROTO_IP option IP_PMTUAGE the returns are:
- OptionValue 0 if PMTU discovery is not enabled.
- OptionValue -1 if PMTU discovery is not complete.
- Positive non-zero OptionValue if PMTU is available.
Upon successful completion of TCP protocol sockets
option IP_FINDPMTU the returns are:
- OptionValue 0 if PMTU discovery (tcp_pmtu_discover) is not enabled.
- OptionValue -1 if PMTU discovery is not complete/not available.
- Positive non-zero OptionValue if PMTU is available.
Error Codes
The getsockopt subroutine is
unsuccessful if any of the following errors occurs:
EBADF |
The Socket parameter is not valid. |
ENOTSOCK |
The Socket parameter refers to a file, not
a socket. |
ENOPROTOOPT |
The option is unknown. |
EFAULT |
The address pointed to by the OptionValue
parameter is not in a valid (writable) part of the process space, or the OptionLength parameter is not in a valid part of the process
address space. |
Examples
The following program fragment illustrates the use
of the getsockopt subroutine to determine an existing
socket type:
#include <sys/types.h>
#include <sys/socket.h>
int type, size;
size = sizeof(int);
if(getsockopt(s, SOL_SOCKET, SO_TYPE, (char*)&type,&size)<0){
.
.
.
}
Related Information
The no
command.
The bind
subroutine, close subroutine, endprotoent subroutine, getprotobynumber subroutine, getprotoent subroutine, setprotoent subroutine, setsockopt subroutine, socket subroutine.
Sockets Overview, Understanding Socket Options, and Understanding Socket Types and Protocols in AIX 5L Version 5.2 Communications Programming Concepts.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]