MSDN Documentation

Documentation / Windows / API Reference / Win32 / Functions / getsockopt

getsockopt

The getsockopt function retrieves an option from a socket.

Syntax

int getsockopt(
  <a href="/windows/desktop/WinSock/nf-winsock-SOCKET-define">SOCKET</a> s,
  int level,
  int optname,
  <a href="/windows/desktop/WinSock/nf-winsock-char-define">char*</a> optval,
  <a href="/windows/desktop/WinSock/nf-winsock-int-define">int*</a> optlen
);

Parameters

s

A descriptor identifying a socket.

level

The level at which the option is defined (for example, SOL_SOCKET). See Remarks for more information.

optname

The name of the option to retrieve. For a list of supported options, see Socket Options.

optval

A pointer to a buffer that receives the value of the requested option. The structure and size of this buffer depend on the option specified in the optname parameter.

optlen

A pointer to a variable that specifies the size of the buffer pointed to by optval, and receives the actual size of the data returned in optval. You must initialize this to the size of the buffer pointed to by optval. If the call returns successfully, the size of the data written to optval is returned in this parameter.

Return Value

If the call completes successfully, getsockopt returns zero. Otherwise, it returns a value of SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

Remarks

The getsockopt function is used to examine the current options on a socket. Options can exist at the socket level, or at a protocol-specific level.

Options can be used to access or modify parameters that affect the operation of the underlying protocols. For example, you can use getsockopt to obtain the value of the SO_RCVBUF option, which specifies the size of the buffer used for receiving data.

Socket Options

The following options are supported at the socket level (level is set to SOL_SOCKET):

  • SO_ACCEPTCONN: If the listening socket is accepting connections.
  • SO_BROADCAST: Whether the socket is permitted to send broadcast datagrams.
  • SO_DEBUG: Whether debugging is enabled.
  • SO_DONTLINGER: Whether the socket has SO_LINGER disabled.
  • SO_ERROR: Any error that has been queued for the socket.
  • SO_KEEPALIVE: Whether the keep-alive socket option is enabled.
  • SO_LINGER: The linger options for the socket.
  • SO_RCVBUF: The size of the receive buffer.
  • SO_RCVTIMEO: The receive timeout for the socket.
  • SO_REUSEADDR: Whether the address is reusable.
  • SO_SNDBUF: The size of the send buffer.
  • SO_SNDTIMEO: The send timeout for the socket.
  • SO_TYPE: The type of the socket (SOCK_STREAM or SOCK_DGRAM).

For a complete list of socket options and their associated structures, refer to the Socket Options documentation.

Code Example

// Sample code to get the receive buffer size.
#include <winsock2.h>
#include <ws2tcpip.h>

// Link with Ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main() {
    WSADATA wsaData;
    SOCKET sockfd;
    int recvBufSize;
    int optlen = sizeof(recvBufSize);
    int result;

    result = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (result != 0) {
        printf("WSAStartup failed: %d\n", result);
        return 1;
    }

    sockfd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (sockfd == INVALID_SOCKET) {
        printf("socket failed: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    result = getsockopt(sockfd, SOL_SOCKET, SO_RCVBUF, (char*)&recvBufSize, &optlen);
    if (result == SOCKET_ERROR) {
        printf("getsockopt (SO_RCVBUF) failed: %ld\n", WSAGetLastError());
    } else {
        printf("Receive buffer size: %d bytes\n", recvBufSize);
    }

    closesocket(sockfd);
    WSACleanup();
    return 0;
}

See Also