setsockopt()

The socket call sets options associated with a socket.

Syntax

#include <types.h>
#include <sys\socket.h>
int setsockopt(s, level, optname, optval, optlen)
int s;
int level;
int optname;
char *optval;
int optlen;

Parameters

s

Socket descriptor.

Specifies which option level is being set.

Name of a specified socket option.

Pointer to the option data.

Length of the option data.

Description

This call provides an application program with the means to control a socket communication. The setsockopt() call can be used to set options associated with a socket, such as enabling debugging at the socket or protocol level, controlling timeouts, or permitting socket data broadcasts. Options can exist at the socket or the protocol level; options are always present at the highest socket level. When setting socket options, the level of the option and the name of the option must be specified. The following table lists the supported levels:

Supported Levels

┌─────────────────────────────────────────────────────────────────┐│Supported Level               #define in                         │
├─────────────────────────────────────────────────────────────────┤
│SOL_SOCKET                    <SYS\SOCKET.H>                     │
├─────────────────────────────────────────────────────────────────┤
│IPPROTO_IP                    <NETINET\IN.H>                     │
├─────────────────────────────────────────────────────────────────┤
│IPPROTO_TCP                   <NETINET\IN.H>                     │
├─────────────────────────────────────────────────────────────────┤
│NBPROTO_NB                    <NETNB\NB.H>                       │
└─────────────────────────────────────────────────────────────────┘

The optval and optlen parameters are used to pass data used by the particular set command. The optval parameter points to a buffer containing the data needed by the set command. The optval parameter is optional and if data is not needed by the command, can be set to the NULL pointer. The optlen parameter must be set to the size of the data or data type pointed to by optval. For socket options that are toggles, the option is enabled if optval is nonzero and disabled if optval is 0.

The following tables list the supported options for setsockopt() at each level (SOL_SOCKET, IPPROTO_IP, IPPROTO_TCP). Detailed descriptions of the options follow each table.

Supported setsockopt() Socket Options for SOL_SOCKET

┌─────────────────────────────────────────────────────────────────────┐
│Option Name     Description             Domains(*)  Data     Boolean │
│                                                    Type     or Value│
├─────────────────────────────────────────────────────────────────────┤
│SO_BROADCAST    Allow sending of        I, N        int      Boolean │
│                broadcast messages                                   │
├─────────────────────────────────────────────────────────────────────┤
│SO_DEBUG        Turn on recording of    I, L        int      Boolean │
│                debugging information                                │
├─────────────────────────────────────────────────────────────────────┤
│SO_DONTROUTE    Bypass routing tables   I           int      Boolean │
├─────────────────────────────────────────────────────────────────────┤
│SO_KEEPALIVE    Keep connections alive  I           int      Boolean │
├─────────────────────────────────────────────────────────────────────┤
│SO_LINGER       Linger on close if data I           struct   Value   │
│                present                             linger           │
├─────────────────────────────────────────────────────────────────────┤
│SO_L_BROADCAST  Limited broadcast sent  I           int      Boolean │
│                on all interfaces                                    │
├─────────────────────────────────────────────────────────────────────┤
│SO_OOBINLINE    Leave received OOB data I           int      Boolean │
│                in-line                                              │
├─────────────────────────────────────────────────────────────────────┤
│SO_RCVBUF       Receive buffer size     I, L, N     int      Value   │
├─────────────────────────────────────────────────────────────────────┤
│SO_RCVLOWAT     Receive low watermark   I, L        int      Value   │
├─────────────────────────────────────────────────────────────────────┤
│SO_RCVTIMEO     Receive timeout         I, L        struct   Value   │
│                                                    timeval          │
├─────────────────────────────────────────────────────────────────────┤
│SO_REUSEADDR    Allow local address     I, N        int      Boolean │
│                reuse                                                │
├─────────────────────────────────────────────────────────────────────┤
│SO_REUSEPORT    Allow local address and I           int      Boolean │
│                port reuse                                           │
├─────────────────────────────────────────────────────────────────────┤
│SO_SNDBUF       Send buffer size        I, L, N     int      Value   │
├─────────────────────────────────────────────────────────────────────┤
│SO_SNDLOWAT     Send low watermark      I, L        int      Value   │
├─────────────────────────────────────────────────────────────────────┤
│SO_SNDTIMEO     Send timeout            I, L        struct   Value   │
│                                                    timeval          │
├─────────────────────────────────────────────────────────────────────┤
│SO_USELOOPBACK  Bypass hardware when    I           int      Value   │
│                possible                                             │
└─────────────────────────────────────────────────────────────────────┘

Table Note (*) This column specifies the communication domains to which this option applies: I for internet, L for Local IPC, and N for NetBIOS.

The following options are recognized for SOL_SOCKET:

Option

Description

( Datagramsocketsonly . )Enablesbroadcastingofmessages .Whenthisoptionisenabled ,theapplicationcansendbroadcastmessagesovers ,iftheinterfacespecifiedinthedestinationsupportsbroadcastingofpackets .

Enablesrecordingofdebuginformationforasocket .ThisoptionsisaprerequisitefortracingTCPdebuginformationthroughtheinetdbgutility .Formoreinformationenterinetcfg- ? .

Enablesthesockettobypasstheroutingofoutgoingmessages .Whenthisoptionisenabled ,itcausesoutgoingmessagestobypassthestandardroutingalgorithmandbedirectedtotheappropriatenetworkinterfaceaccordingtothenetworkportionofthedestinationaddress .Whenthisoptionisenabled ,packetscanbesentonlytodirectlyconnectednetworks( networksforwhichthishosthasaninterface ) .

( Streamsocketsonly . )Enablesthesockettosendkeepalivepacketsthatwillkeeptheconnectionalive .TCPusesatimercalledthekeepalivetimer .Thistimerisusedtomonitoridleconnectionsthatmighthavebeendisconnectedbecauseofapeercrashortimeout .Whenthisoptionisenabled ,akeepalivepacketisperiodicallysenttothepeer .Thisismainlyusedtoallowserverstocloseconnectionsthatarenolongeractiveasaresultofclientsgoingawaywithoutproperlyclosingconnections .

( Streamsocketsonly . )Enablesthesockettolingeroncloseifdataispresent .Whenthisoptionisenabledandthereisunsentdatapresentwhensoclose ( )iscalled ,thecallingapplicationisblockedduringthesoclose ( )calluntilthedataistransmittedortheconnectionhastimedout .Whenthisoptionisdisabled ,thesoclose ( )callreturnswithoutblockingthecaller ,andTCPwaitstotrytosendthedata .Althoughthedatatransferisusuallysuccessful ,itcannotbeguaranteedbecauseTCPwaitsonlyafiniteamountoftimetosendthedata .

The optval parameter points to a linger structure, defined in <SYS\SOCKET.H>:

Field

Description
l _ onoff
Optionon / off
l _ linger
Lingertime
Thel _ onofffieldissettozeroiftheSO _ LINGERoptionisbeingdisabled .Anonzerovalueenablestheoption .

The l_linger field specifies the amount of time in seconds to linger on close. A value of zero will cause soclose() to wait until the disconnect completes.

SO_L_BROADCAST
Sets limited broadcast sent on all interfaces.
SO_OOBINLINE
(Stream sockets only.) Enables the socket to receive out-of-band data. Out-of-band data is a logically separate data path using the same connection as the normal data path.

When this option is enabled, it causes out-of-band data to be placed in the normal data input queue as it is received, making it available to recv(), and recvfrom(), without having to specify the MSG_OOB flag in those calls. When this option is disabled, it causes out-of-band data to be placed in the priority data input queue as it is received, making it available to recv() and recvfrom() only by specifying the MSG_OOB flag in those calls.

SO_RCVBUF
Sets buffer size for input. This option sets the size of the receive buffer to the value contained in the buffer pointed to by optval. This allows the buffer size to be tailored for specific application needs, such as increasing the buffer size for high-volume connections.

Use inetcfg -g tcprwinsize to see the default and maximum receive socket buffer sizes for stream (TCP) sockets or raw sockets. Use inetcfg -g udprwinsize to see the default and maximum receive socket buffer sizes for UDP sockets.

SO_RCVLOWAT
Sets the receive low watemark.
SO_RCVTIMEO
Sets the receive timeout. The optval parameter is a pointer to a timeval structure, which is defined in <SYS\TIME.H>. See Example of recvmsg() Call for an example of setting the socket timeout option.
SO_REUSEADDR
(Stream and datagram sockets only.) Enables a socket to reuse a local address. When this option is enabled, local addresses that are already in use can be bound. This alters the normal algorithm used in the bind() call. The system checks at connect time to be sure that no local address and port have the same foreign address and port. The error SOCEADDRINUSE is returned if the association already exists.

Multicast applications must set this socket option if they want to join the same Class D IP address and port for sending and receiving multicast packets.

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_SNDBUF
Sets the send buffer size. This option sets the size of the send buffer to the value contained in the buffer pointed to by optval. This allows the send buffer size to be tailored for specific application needs, such as increasing the buffer size for high-volume connections.

Use inetcfg -g tcpswinsize to see the default and maximum send socket buffer sizes for stream (TCP) sockets or raw sockets. Use inetcfg -g udpswinsize to see the default and maximum send socket buffer sizes for UDP sockets.

SO_SNDLOWAT
Sets the send low watermark.
SO_SNDTIMEO
Sets the send timeout. The optval parameter is a pointer to a timeval structure, which is defined in <SYS\TIME.H>. See Example of recvmsg() Call for an example of setting the socket timeout option.
SO_USELOOPBACK
Bypasses hardware when possible.

Supported setsockopt() Socket Options for IPPROTO_IP

┌───────────────────────────────────────────────────────────────────┐│Option Name         Description              Data Type     Boolean │
│                                                           or Value│
├───────────────────────────────────────────────────────────────────┤
│IP_ADD_MEMBERSHIP   Join a multicast group   struct        Value   │
│                                             ip_mreq               │
├───────────────────────────────────────────────────────────────────┤
│IP_DROP_MEMBERSHIP  Leave a multicast group  struct        Value   │
│                                             ip_mreq               │
├───────────────────────────────────────────────────────────────────┤
│IP_HDRINCL          Header is included with  int           Boolean │
│                    data                                           │
├───────────────────────────────────────────────────────────────────┤
│IP_MULTICAST_IF     Default interface for    struct        Value   │
│                    outgoing multicasts      in_addr               │
├───────────────────────────────────────────────────────────────────┤
│IP_MULTICAST_LOOP   Loopback of outgoing     uchar         Boolean │
│                    multicast                                      │
├───────────────────────────────────────────────────────────────────┤
│IP_MULTICAST_TTL    Default TTL for outgoing uchar         Value   │
│                    multicast                                      │
├───────────────────────────────────────────────────────────────────┤
│IP_OPTIONS          IP options               char *        Value   │
├───────────────────────────────────────────────────────────────────┤
│IP_RECVDSTADDR      Queueing IP destination  int           Boolean │
│                    address                                        │
├───────────────────────────────────────────────────────────────────┤
│IP_RECVTRRI         Queueing token ring      int           Boolean │
│                    routing information                            │
├───────────────────────────────────────────────────────────────────┤
│IP_RETOPTS          IP options to be         char *        Value   │
│                    included in outgoing                           │
│                    datagrams                                      │
├───────────────────────────────────────────────────────────────────┤
│IP_TOS              IP type of service for   int           Value   │
│                    outgoing datagrams                             │
├───────────────────────────────────────────────────────────────────┤
│IP_TTL              IP time to live for      int           Value   │
│                    outgoing datagrams                             │
└───────────────────────────────────────────────────────────────────┘

The following options are recognized for IPPROTO_IP:

Option

Description
IP _ ADD _ MEMBERSHIP
Usedtojoinamulticastgroup . Therecanbe20groupspersocket ,andthemaximumnumberofgroupsfortheentireOS / 2TCP / IPsystemis320 .Amulticastpacketisdeliveredtoasocketifithasjoinedthesamegrouponthesameinterfaceonwhichthepacketarrived . Morethanonesocketcanbind ( )onamulticast( ClassDIP )addressandacommonport ,suchaswhentwoclientswanttoreceivethesamemulticastpacket . ThesesocketsmustsettheSO _ REUSEADDRsocketoption .
IP _ DROP _ MEMBERSHIP
Usedtoleaveamulticastgroup .
IP _ HDRINCL
( Rawsocketsonly . )Whenset ,theIPheaderisincludedwiththedatareceivedonthesocket .
IP _ MULTICAST _ IF
Setsthedefaultinterfaceforoutgoingmulticasts .
IP _ MULTICAST _ LOOP
Thisoptionisusedforsendingmulticastpackets .Itenablesordisablesloopbackofoutgoingmulticastpacketsandisenabledbydefault . Ifloopbackisdisabled ,outgoingmulticastpacketswillnotloopbackinthissystem ;thismeansthatotherapplicationsrunninginthissystemwillnotreceiveoutgoingmulticastpacketseveniftheyhavejoinedthesamemulticastgroup .
IP _ MULTICAST _ TTL
SetsthedefaultTTLforoutgoingmulticastpackets .
IP _ OPTIONS
SetsIPoptions . SameasIP _ RETOPTS .SeeExampleofIP _ RETOPTSSocketCallforhowtouseIP _ RETOPS .
IP _ RECVDSTADDR
( UDPonly )SetsthequeueingIPdestinationaddress .SeeExampleofrecvmsg ( )Callforthewaytogetthisinformationthroughrecvmsg ( )call .
IP _ RECVTRRI
( UDPpacketsontokenringonly . )Setsqueueingtokenringroutinginformation .SeeExampleofrecvmsg ( )Callforthewaytogetthisinformationthroughrecvmsg ( )call .
IP _ RETOPTS
SetstheIPoptionstobeincludedinoutgoingdatagrams .SeeExampleofIP _ RETOPTSSocketCallforhowtouseIP _ RETOPS .
IP _ TOS
SetstheIPtypeofserviceforoutgoingdatagrams .
IP _ TTL
SetstheIPtimetolivevalueforoutgoingdatagrams .

Supported setsockopt() Socket Options for IPPROTO_TCP

┌───────────────────────────────────────────────────────────────────┐│Option Name       Description               Data Type     Boolean  │
│                                                          or Value │
├───────────────────────────────────────────────────────────────────┤
│TCP_CC            Connection count flag     int           Boolean  │
├───────────────────────────────────────────────────────────────────┤
│TCP_MAXSEG        Maximum segment size      int           Value    │
├───────────────────────────────────────────────────────────────────┤
│TCP_MSL           TCP MSL value             int           Value    │
├───────────────────────────────────────────────────────────────────┤
│TCP_NODELAY       Do not delay sending to   int           Boolean  │
│                  coalesce packets                                 │
├───────────────────────────────────────────────────────────────────┤
│TCP_TIMESTMP      TCP timestamp flag        int           Boolean  │
├───────────────────────────────────────────────────────────────────┤
│TCP_WINSCALE      Window scale flag         int           Boolean  │
└───────────────────────────────────────────────────────────────────┘

The following options are recognized for IPPROTO_TCP:

Option

Description
TCP _ CC
( T / TCPonly . )Enablesordisablestheconnectioncountfunctionstatusflag( RFC1644 ) .
TCP _ MAXSEG
Setsthemaximumsegmentsize .
TCP _ MSL
SetstheTCPMaximumSegmentLifetime( MSL )value .
TCP _ NODELAY
( Streamsocketsonly . )Settingondisablesthebufferingalgorithmsothattheclient ' sTCPsendssmallpacketsassoonaspossible . ThisoftenhasnoperformanceeffectsonLANs ,butcandegradeperformanceonWANs .
TCP _ TIMESTMP
( T / TCPonly . )Enablesordisablesthetimestampfunctionstatusflag( RFC1323 ) .Formoreinformationabouthighperformance ,seeTCPExtensionsforHighPerformance( RFC1323 ) .
TCP _ WINSCALE
( T / TCPonly . )Enablesordisablesthewindowscalefunctionstatusflag( RFC1323 ) .Formoreinformationabouthighperformance ,seeTCPExtensionsforHighPerformance( RFC1323 ) .

Supported setsockopt() Socket Options for NBPROTO_NB

┌───────────────────────────────────────────────────────────────────┐│Option Name       Description               Data Type     Boolean  │
│                                                          or Value │
├───────────────────────────────────────────────────────────────────┤
│NB_DGRAM_TYPE     Type of datagrams to      int           Value    │
│                  receive                                          │
└───────────────────────────────────────────────────────────────────┘

The following option is recognized for NBPROTO_NB:

Option

Description
NB _ DGRAM _ TYPE
( Datagramsocketsonly . )Setstypeofdatagramstobereceivedonthesocket . Thepossiblevaluesare :

NB_DGRAM

The socket is to receive normal (unicast) datagrams only.
NB_BROADCAST
The socket is to receive broadcast datagrams only.
NB_DGRAM_ANY
The socket can receive both normal or broadcast datagrams.
This option can be changed at any time.

Return Values

The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling sock_errno() or psock_errno().

sock_errno() Value

Description
SOCEADDRINUSE
Theaddressisalreadyinuse .
SOCENOTSOCK
Thesparameterisnotavalidsocketdescriptor .
SOCEFAULT
Usingoptvalandoptlenparameterswouldresultinanattempttoaccessmemoryoutsidethecaller ' saddressspace .
SOCENOPROTOOPT
Theoptnameparameterisunrecognized .
SOCEINVAL
Invalidargument .
SOCENOBUFS
Nobufferspaceisavailable .

Examples

The following are examples of the setsockopt() call. See getsockopt() for examples of how the options are queried.

int rc;int s;
int optval;
struct linger lstruct;
/* extracted from sys/socket.h */
int setsockopt(int s, int level, int optname, char *optval, int optlen);
...
/* I want out of band data in the normal input queue */
optval = 1;
rc = setsockopt(s, SOL_SOCKET, SO_OOBINLINE, (char *) &optval, sizeof(int));
...
/* I want to linger on close */
lstruct.l_onoff  = 1;
lstruct.l_linger = 100;
rc = setsockopt(s, SOL_SOCKET, SO_LINGER, (char *) &lstruct, sizeof(lstruct));

Related Calls

bind()
endprotoent()
getprotobyname()
getprotobynumber()
getprotoent()
getsockopt()
ioctl()
setprotoent()
sock_errno()
socket()

---

[Back: sendto()]
[Next: shutdown()]