[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]
AIX Version 4.3 Communications Technical Reference, Volume 2
setsockopt Subroutine
Purpose
Sets socket options.
Library
Standard C Library (libc.a)
Syntax
#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;
Description
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.
Parameters
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 Version 4.3 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. Although a linger interval can be
specified in seconds, the system ignores the specified time and makes repeated
attempts to send unsent messages. |
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. |
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. |
Return Values
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 Version 4.3 General Programming Concepts: Writing and Debugging Programs.
Error Codes
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. |
Examples
To mark a socket for broadcasting:
int on=1;
setsockopt(s, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on));
Implementation Specifics
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.
Related Information
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 Version 4.3 Communications Programming Concepts.
[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]