getsockopt()

The getsockopt() socket call gets the socket options associated with a socket.

Syntax

#include <types.h>
#include <sys\socket.h>
int getsockopt(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 queried for the specified optname.

Name of a specified socket option. Only one option can be specified on a call.

Pointer to buffer to receive the option data requested.

Pointer to the size of the buffer.

Description

This call returns the value of a socket option at the socket or protocol level. It can be called for sockets of all domain types. Some options are supported only for specific socket types. You must specify the level of the option and the name of the option to retrieve option values. 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 parameter is a pointer to the buffer where the option values are returned. The optlen parameter must be initially set to the size of the buffer before calling getsockopt(). On return, the optlen parameter is set to the actual size of the data returned. For socket options that are Boolean, the option is enabled if optval is nonzero and disabled if optval is 0.

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

Supported getsockopt() Socket Options for SOL_SOCKET

┌────────────────────────────────────────────────────────────────────┐
│Option Name     Description             Domains(*) Data     Boolean │
│                                                   Type     or Value│
├────────────────────────────────────────────────────────────────────┤
│SO_ACCEPTCONN   Listen status           I, L       int      Boolean │
├────────────────────────────────────────────────────────────────────┤
│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, L       int      Boolean │
├────────────────────────────────────────────────────────────────────┤
│SO_ERROR        Return any pending      I, L       int      Value   │
│                error and clear                                     │
├────────────────────────────────────────────────────────────────────┤
│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_OPTIONS      Retrieve socket options I          int      Flags   │
│                (flags)                                             │
├────────────────────────────────────────────────────────────────────┤
│SO_OOBINLINE    Leave received OOB data I          int      Boolean │
│                in-line                                             │
├────────────────────────────────────────────────────────────────────┤
│SO_RCVBUF       Receive buffer size     I, L, N    int      Value   │
├────────────────────────────────────────────────────────────────────┤
│SO_RCV_SHUTDOWN If shutdown called for  I, L       int      Boolean │
│                receive                                             │
├────────────────────────────────────────────────────────────────────┤
│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 port reuse  I          int      Boolean │
├────────────────────────────────────────────────────────────────────┤
│SO_SNDBUF       Send buffer size        I, L, N    int      Value   │
├────────────────────────────────────────────────────────────────────┤
│SO_SND_SHUTDOWN If shutdown called for  I, L       int      Boolean │
│                send                                                │
├────────────────────────────────────────────────────────────────────┤
│SO_SNDLOWAT     Send low watermark      I, L       int      Value   │
├────────────────────────────────────────────────────────────────────┤
│SO_SNDTIMEO     Send timeout            I, L       struct   Value   │
│                                                   timeval          │
├────────────────────────────────────────────────────────────────────┤
│SO_TYPE         Socket type             I, L, N    int      Value   │
├────────────────────────────────────────────────────────────────────┤
│SO_USELOOPBACK  Bypass hardware when    I, L       int      Boolean │
│                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

Returnstrueifthesocketisinthelistenstate .

( Datagramsocketsonly . )RetrievesthecurrentstatusoftheSO _ BROADCASToption .Whenthisoptionisenabled ,theapplicationcansendbroadcastmessagesovers ,iftheinterfacespecifiedinthedestinationsupportsbroadcastingofpackets .

RetrievesthecurrentstatusoftheSO _ DEBUGoption .

RetrievesthecurrentstatusoftheSO _ DONTROUTEoption .Whenthisoptionisenabled ,itcausesoutgoingmessagestobypassthestandardroutingalgorithmandbedirectedtotheappropriatenetworkinterface ,accordingtothenetworkportionofthedestinationaddress .Whenenabled ,packetscanbesentonlytodirectlyconnectednetworks( networksforwhichthishosthasaninterface ) .

Returnsanypendingerroronthesocketandclearstheerrorstatus . Itcanbeusedtocheckforasynchronouserrorsonconnecteddatagramsocketsorforotherasynchronouserrors( errorsthatarenotreturnedexplicitlybyoneofthesocketcalls ) .

( Streamsocketsonly . )RetrievesthecurrentstatusoftheSO _ KEEPALIVEoption .TCPusesatimercalledthekeepalivetimer . Thistimerisusedtomonitoridleconnectionsthatmighthavebeendisconnectedbecauseofapeercrashortimeout .Whenthisoptionisenabled ,akeepalivepacketisperiodicallysenttothepeer . Thisismainlyusedtoallowserverstocloseconnectionsthatarenolongeractiveasaresultofclientsgoingawaywithoutproperlyclosingconnections .

( Streamsocketsonly . )RetrievesthecurrentstatusoftheSO _ LINGERoption . Whenthisoptionisenabledandthereisunsentdatapresentwhensoclose ( )iscalled ,thecallingapplicationisblockedduringthesoclose ( )calluntilthedataistransmittedortheconnectionhastimedout .Whenthisoptionisdisabled ,thesoclose ( )callreturnswithoutblockingthecaller ,andTCPwaitstotrytosendthedata .Althoughthedatatransferisusuallysuccessful ,itcannotbeguaranteed ,becauseTCPwaitsonlyafiniteamountoftimetosendthedata .

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
Gets limited broadcast sent on all interfaces.
SO_OPTIONS
Gets the current socket options from the stack. The socket option flags are returned as a 32-bit variable. The so_xxx socket option flags are defined in <SYS\SOCKET.H>.
SO_OOBINLINE
(Stream sockets only.) Retrieves the current status of the SO_OOBINLINE option. 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
Retrieves buffer size for input. This value tailors the receive buffer size for specific application needs, such as increasing the buffer size for high-volume connections.
SO_RCV_SHUTDOWN
Returns true if shutdown was called for receive.
SO_RCVLOWAT
Retrieves the receive low watermark.
SO_RCVTIMEO
Retrieves the receive timeout. The optval parameter is a pointer to a timeval structure, which is defined in <SYS\TIME.H>.
SO_REUSEADDR
(Stream and datagram sockets only.) Retrieves the current status of the SO_REUSEADDR option. 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. At connect time, the system checks 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.
SO_REUSEPORT
(Stream and datagram sockets only.) Retrieves the current status of the SO_REUSEPORT option. This option specifies that the rules used in validating ports supplied by a subroutine of the bind() call should allow reuse of a local port/address combination. Each binding of the port/address combination must specify the socket option. This option enables or disables the reuse of local port/address combinations.
SO_SNDBUF
Retrieves the send buffer size. This value tailors the send buffer size for specific application needs, such as increasing the buffer size for high-volume connections.
SO_SND_SHUTDOWN
Returns true if the shutdown function was called as part of the send() call.
SO_SNDLOWAT
Retrieves the send low watermark.
SO_SNDTIMEO
Retrieves the send timeout. optval is a pointer to a timeval structure, which is defined in <SYS\TIME.H>.
SO_TYPE
Retrieves the socket type. On return, the integer pointed to by optval is set to one of the following: SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.
SO_USELOOPBACK
Bypasses hardware when possible.

Supported getsockopt() Socket Options for IPPROTO_IP

┌───────────────────────────────────────────────────────────────────┐│Option Name         Description              Data Type     Boolean │
│                                                           or Value│
├───────────────────────────────────────────────────────────────────┤
│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               char *        Value   │
├───────────────────────────────────────────────────────────────────┤
│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 _ HDRINCL
( Rawsocketsonly . )SpecifieswhethertheIPheaderisincludedwithdata .
IP _ MULTICAST _ IF
Retrievesthedefaultinterfaceforoutgoingmulticasts .
IP _ MULTICAST _ LOOP
Retrievesthevalueoftheloopbacksettingforoutgoingmulticast .
IP _ MULTICAST _ TTL
Retrievesthedefaulttimetoliveforoutgoingmulticastpackets .
IP _ OPTIONS
RetrievesIPoptions .SameasIP _ RETOPTS .

The data type is char * ip_retopts[4], such as

ip_retopts[0]=IPOPT_OPTVAL
ip_retopts[1]=IPOPT_OLEN
ip_retopts[2]=IPOPT_OFFSET
ip_retopts[3]=IPOPT_MINOFF

For an example that uses IP_RETOPTS, see Example of IP_RETOPTS Socket Call.
IP_RECVDSTADDR
(UDP only.) Retrieves queueing IP destination address. This option must get this information through a recvmsg() call. For more information, see Example of recvmsg() Call.
IP_RECVTRRI
(UDP packets on token ring only.) Retrieves the flag that indicates whether queueing of token ring routing information is enabled. This TTRI information must be received as control data through a recvmsg() call. For more information , see Example of recvmsg() Call.
IP_RETOPTS
Retrieves IP options to be included in outgoing datagrams.

The data type is char * ip_retopts[4], such as

ip_retopts[0]=IPOPT_OPTVAL
ip_retopts[1]=IPOPT_OLEN
ip_retopts[2]=IPOPT_OFFSET
ip_retopts[3]=IPOPT_MINOFF

For an example that uses IP_RETOPTS, see Example of IP_RETOPTS Socket Call.
IP_TOS
Retrieves IP type of service for outgoing datagrams.
IP_TTL
Retrieves IP time to live value for outgoing datagrams.

Supported getsockopt() Socket Options for IPPROTO_TCP

┌───────────────────────────────────────────────────────────────────┐│Option Name       Description               Data Type     Boolean  │
│                                                          or Value │
├───────────────────────────────────────────────────────────────────┤
│TCP_CC            Connection count function int           Boolean  │
├───────────────────────────────────────────────────────────────────┤
│TCP_MAXSEG        Maximum segment size      int           Value    │
├───────────────────────────────────────────────────────────────────┤
│TCP_MSL           TCP MSL value             int           Value    │
├───────────────────────────────────────────────────────────────────┤
│TCP_NODELAY       Don't delay send to       int           Boolean  │
│                  coalesce packets                                 │
├───────────────────────────────────────────────────────────────────┤
│TCP_TIMESTMP      Time stamp function       int           Boolean  │
├───────────────────────────────────────────────────────────────────┤
│TCP_WINSCALE      Window scale function     int           Boolean  │
└───────────────────────────────────────────────────────────────────┘

The following options are recognized for IPPROTO_TCP:

Option

Description
TCP _ CC
( T / TCPonly . )Retrievestheconnectioncountfunctionenabled / disabledstatusflag( RFC1644 ) .FormoreinformationaboutT / TCP ,seeTCPExtensionsforTransactions( T / TCP ) .
TCP _ MAXSEG
Retrievesthemaximumsegmentsize .
TCP _ MSL
RetrievestheTCPMaximumSegmentLifetime( MSL )value .
TCP _ NODELAY
( Streamsocketsonly . )RetrievesthecurrentstatusoftheTCP _ NODELAYoption .Disablesthebufferingalgorithmsothattheclient ' sTCPsendssmallpacketsassoonaspossible . ThisoftenhasnoperformanceeffectsonLANs ,butcandegradeperformanceonWANs .
TCP _ TIMESTMP
( T / TCPonly . )RetrievestheTCPtimestampfunctionenabled / disabledstatusflag( RFC1323 ) .Formoreinformationabouthighperformance ,seeTCPExtensionsforHighPerformance( RFC1323 ) .
TCP _ WINSCALE
( T / TCPonly )Retrievesthewindowscalefunctionenabled / disabledstatusflag( RFC1323 ) .Formoreinformationabouthighperformance ,seeTCPExtensionsforHighPerformance( RFC1323 ) .

Supported getsockopt() 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 . )Retrievesthetypeofdatagramstobereceivedonthesocket . 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.

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
Theoptnameparameterorlevelparameterisnotrecognized .

Examples

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

int rc;int s;
int optval;
int optlen;
struct linger lstruct;
int getsockopt(int s, int level, int optname, char *optval, int *optlen);
/* extracted from sys/socket.h */
...
/* Is out of band data in the normal input queue? */
optlen = sizeof(int);
rc = getsockopt( s, SOL_SOCKET, SO_OOBINLINE, (char *) &optval, &optlen);
if (rc == 0)
{
    if (optlen == sizeof(int))
    {
         if (optval)
            /* yes it is in the normal queue */
         else
            /* no it is not                  */
    }
}
...
/* Do I linger on close? */
optlen = sizeof(lstruct);
rc = getsockopt( s, SOL_SOCKET, SO_LINGER, (char *) &lstruct, &optlen);
if (rc == 0)
{
    if (optlen == sizeof(lstruct))
    {
        if (lstruct.l_onoff)
           /* yes I linger */
        else
           /* no I do not  */
    }
}

The following is an example of the ip_retopts socket option.


Example of IP_RETOPTS Socket Call


/* [0]:IPOPT_OPTVAL, [1]:IPOPT_OLEN, [2]:IPOPT_OFFSET, [3]:IPOPT_MINOFF */
char ip_retopts[8];

main()
{
    int optlen, sraw, i;


    if ((sraw = socket(AF_INET, SOCK_RAW, IPPROTO_RAW)) < 0)
        psock_errno("Socket()");

    printf("IP_RETOPTS or OP_OPTIONS will get/set the IP options \n");
    ip_retopts[IPOPT_OPTVAL] = IPOPT_TS ;    /* TimeStamp IP options to set */
    ip_retopts[IPOPT_OLEN]   = 8;
    ip_retopts[IPOPT_OFFSET] = 4;
    ip_retopts[IPOPT_MINOFF] = 4;

    printf("Setting the IP_RETOPTS to TimeStamp option (%d) \n",
                          ip_retopts[IPOPT_OPTVAL]);
    if (setsockopt(sraw,IPPROTO_IP,IP_RETOPTS,(char *)&ip_retopts[0] ,
                          sizeof(ip_retopts)) < 0)
        psock_errno("setsockopt() IP_RETOPTS");

    /* NOTE ::: when the getsockopt returns it will stick in the first hop    */
    /*          destination in the first 4 bytes by shifting all data right.  */
    memset(ip_retopts, 0, sizeof(ip_retopts));
    printf("Get the ip_retopts value set for this socket\n");
    optlen = sizeof(ip_retopts);
    if (getsockopt(sraw,IPPROTO_IP,IP_OPTIONS,(char *)ip_retopts,&optlen) < 0) {
        psock_errno("getsockopt() IP_RETOPTS ");
    }
    else {
       if  (ip_retopts[4+IPOPT_OPTVAL] == IPOPT_TS)
         printf ("IP_RETOPTS now set to TimeStamp option(%d) \n",
                    ip_retopts[4+IPOPT_OPTVAL]);
       else
         printf ("IP_RETOPTS now set to ??? (%d) \n",
                    ip_retopts[4+IPOPT_OPTVAL]);
    }

    soclose(sraw);
}

Related Calls

bind()
endprotoent()
getprotobyname()
getprotobynumber()
getprotoent()
setprotoent()
setsockopt()
sock_errno()
socket()

---

[Back: getsockname()]
[Next: ioctl()]