[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 2
Sets socket options.
Standard C Library
(libc.a)
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/socketvar.h>
#include <sys/atmsock.h> /*Needed for SOCK_CONN_DGRAM socket type
only*/
int setsockopt
(Socket, Level, OptionName, OptionValue, OptionLength)
int Socket, Level, OptionName;
const void * OptionValue;
size_t OptionLength;
The setsockopt subroutine sets
options associated with a socket. Options can exist at multiple
protocol levels. The options are always present at the uppermost socket
level.
The setsockopt subroutine
provides an application program with the means to control a socket
communication. An application program can use the setsockopt
subroutine to enable debugging at the protocol level, allocate buffer space,
control time outs, or permit socket data broadcasts. The
/usr/include/sys/socket.h file defines all the options available
to the setsockopt subroutine.
When setting socket options,
specify the protocol level at which the option resides and the name of the
option.
Use the parameters
OptionValue and OptionLength to access option values for
the setsockopt subroutine. These parameters identify a
buffer in which the value for the requested option or options is
returned.
| Socket
| Specifies the unique socket name.
|
| Level
| Specifies the protocol level at which the option resides. To set
options at:
- Socket level
- Specifies the Level parameter as SOL_SOCKET.
- 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. Similarly,
to indicate that an option will be interpreted by ATM protocol, set the
Level parameter to NDDPROTO_ATM, as defined in
sys/atmsock.h.
|
| OptionName
| Specifies the option to set. The OptionName parameter
and any specified options are passed uninterpreted to the appropriate protocol
module for interpretation. The sys/socket.h file
defines the socket protocol level options. The
netinet/tcp.h file defines the TCP protocol level
options. The socket level options can be enabled or disabled; they
operate in a toggle fashion.
The following list defines socket
protocol level options found in the sys/socket.h file:
- SO_DEBUG
- Turns on recording of debugging information. This option enables or
disables debugging in the underlying protocol modules.
- SO_REUSEADDR
- Specifies that the rules used in validating addresses supplied by a bind subroutine should allow reuse of a local
port.
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
- 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_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.1 Communications Programming
Concepts.
- SO_DONTROUTE
- Does not apply routing on outgoing messages. Indicates that
outgoing messages should bypass the standard routing facilities.
Instead, they are directed to the appropriate network interface according to
the network portion of the destination address.
|
|
- SO_BROADCAST
- Permits sending of broadcast 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 SO_LINGER is set,
the system blocks the process during the close subroutine until it
can transmit the data or until the time expires. If
SO_LINGER 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.
- SO_SNDBUF
- Sets send buffer size.
- SO_RCVBUF
- Sets receive buffer size.
- SO_SNDLOWAT
- Sets send low-water mark.
- SO_RCVLOWAT
- Sets receive low-water mark.
- SO_SNDTIMEO
- Sets send time out. This option is setable, but currently not
used.
- SO_RCVTIMEO
- Sets receive time out. This option is setable, but currently not
used.
- SO_ERROR
- Sets the retrieval of error status and clear.
- SO_TYPE
- Sets the retrieval of a socket type.
|
|
The following list defines TCP
protocol level options found in the netinet/tcp.h
file:
- TCP_RFC1323
- Enables or disables RFC 1323 enhancements on the specified TCP
socket. An application might contain the following lines to enable RFC
1323:
int on=1;
setsockopt(s,IPPROTO_TCP,TCP_RFC1323,&on,sizeof(on));
- 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. For example,
TCP_NODELAY should be used when there is an application using TCP
for a request/response.
- TCP_STDURG
- Enables or disables RFC 1122 compliant urgent point handling. By
default, TCP implements urgent pointer behavior compliant with the 4.2
BSD operating system, i.e., this option defaults to 0.
|
|
Beginning at AIX 4.3.2, TCP protocol level socket options are
inherited from listening sockets to new sockets. Prior to
4.3.2, only the TCP_RFC1323 option was inherited.
The following list defines ATM
protocol level options found in the sys/atmsock.h
file:
- SO_ATM_PARAM
- Sets 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
- Sets ATM AAL(Adaptation Layer) parameters. It uses the
aal_parm structure defined in sys/call_ie.h
file.
- SO_ATM_TRAFFIC_DES
- Sets ATM Traffic Descriptor values. It uses the traffic
structure defined in sys/call_ie.h file.
- SO_ATM_BEARER
- Sets ATM Bearer capability. It uses the bearer structure
defined in sys/call_ie.h file.
- SO_ATM_BHLI
- Sets ATM Broadband High Layer Information. It uses the
bhli structure defined in sys/call_ie.h
file.
- SO_ATM_BLLI
- Sets ATM Broadband Low Layer Information. It uses the
blli structure defined in sys/call_ie.h
file.
- SO_ATM_QOS
- Sets ATM Quality Of Service values. It uses the qos_parm
structure defined in sys/call_ie.h file.
- SO_ATM_TRANSIT_SEL
- Sets ATM Transit Selector Carrier. It uses the
transit_sel structure defined in sys/call_ie.h
file.
- SO_ATM_ACCEPT
- Indicates acceptance of an incoming ATM call, which was indicated to the
application via ACCEPT system call. This must be issues for
the incoming connection to be fully established. This allows
negotiation of ATM parameters.
- SO_ATM_MAX_PEND
- Sets 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. OptionValue/OptionLength point to a byte which
contains the value that this parameter will be set to.
|
| OptionValue
| The OptionValue parameter takes an Int
parameter. To enable a Boolean option, set the OptionValue
parameter to a nonzero value. To disable an option, set the
OptionValue parameter to 0.
The following options enable and
disable in the same manner:
- SO_DEBUG
- SO_REUSEADDR
- SO_KEEPALIVE
- SO_DONTROUTE
- SO_BROADCAST
- SO_OOBINLINE
- SO_LINGER
- TCP_RFC1323
|
| OptionLength
| The OptionLength parameter contains the size of the buffer pointed to by
the OptionValue parameter.
|
Options at other protocol levels
vary in format and name.
IP level (IPPROTO_IP
level) options are defined as follows:
| IP_DONTFRAG
| Sets DF bit from now on for every packet in the IP header.
|
| IP_FINDPMTU
| Sets enable/disable PMTU discovery for this path. Protocol level
path MTU discovery should be enabled for the discovery to happen.
|
| IP_PMTUAGE
| Sets the age of PMTU. Specifies the frequency of PMT reductions
discovery for the session. Setting it to 0 (zero) implies infinite age
and PMTU reduction discovery will not be attempted. This will replace
the previously set PMTU age. The new PMTU age will become effective
after the currently set timer expires.
|
Upon successful completion, a
value of 0 is returned.
If the setsockopt
subroutine is unsuccessful, the subroutine handler performs the following
functions:
- Returns a value of -1 to the calling program.
- Moves an error code, indicating the specific error, into
the errno global variable. For further explanation of the
errno variable see Error Notification Object
Class in AIX 5L Version 5.1 General Programming
Concepts: Writing and Debugging Programs.
The setsockopt
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 parameter is not in a writable part of the user
address space.
|
To mark a socket for
broadcasting:
int on=1;
setsockopt(s, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on));
The setsockopt
subroutine is part of Base Operating System (BOS) Runtime.
All applications containing the
setsockopt 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.
The no command.
The bind subroutine, endprotoent subroutine, getprotobynumber subroutine, getprotoent subroutine, getsockopt subroutine, setprotoent subroutine, socket subroutine.
Sockets
Overview, Understanding Socket Options, Understanding Socket Types and Protocols in AIX 5L
Version 5.1 Communications Programming Concepts.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]