MSDN > Windows > API Reference > Networking & Internet > Sockets > Socket Functions

Socket Functions

This section provides detailed documentation for the various socket functions available in the Windows API. These functions are the building blocks for network communication, enabling applications to create, configure, send data, and receive data over networks.

Core Socket Operations

  • socket - Creates a socket.
  • bind - Associates a local address with a socket.
  • connect - Establishes a connection to a remote host.
  • listen - Puts a socket into a listening state for incoming connections.
  • accept - Accepts an incoming connection request.
  • send - Sends data over a connected socket.
  • recv - Receives data from a connected socket.
  • sendto - Sends data to a specific address without a prior connection.
  • recvfrom - Receives data from a specific address.
  • closesocket - Closes a socket.

Address Information and Resolution

  • gethostbyname - Resolves a hostname to an IP address (legacy).
  • gethostbyaddr - Resolves an IP address to a hostname (legacy).
  • getaddrinfo - Provides protocol-independent translation of hostnames and service names.
  • freeaddrinfo - Frees address information structures allocated by getaddrinfo.

socket

C++
SOCKET socket(int af, int type, int protocol);

The socket function creates a socket endpoint for communication. It returns a descriptor for the new socket, or an invalid value if an error occurs.

Parameters

Parameter Description
af The address family. For example, AF_INET for IPv4 or AF_INET6 for IPv6.
type The socket type. Common values include SOCK_STREAM (for reliable, connection-oriented communication, e.g., TCP) and SOCK_DGRAM (for connectionless datagrams, e.g., UDP).
protocol The protocol to be used with the socket. Often set to 0 to infer the protocol from the type and address family (e.g., IPPROTO_TCP for SOCK_STREAM, IPPROTO_UDP for SOCK_DGRAM).

Return Value

If successful, socket returns a descriptor for the newly created socket. Otherwise, it returns INVALID_SOCKET, and a specific error code can be retrieved using WSAGetLastError.

bind

C++
int bind(SOCKET s, const struct sockaddr FAR * name, int namelen);

The bind function associates a local address with a socket. This is typically used by a server to bind to a specific IP address and port before listening for connections.

Parameters

Parameter Description
s A descriptor identifying an unbound socket.
name A pointer to a sockaddr structure that specifies the address to bind to. For AF_INET, this is a sockaddr_in structure.
namelen The length, in bytes, of the name structure.

Return Value

If no error occurs, bind returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

connect

C++
int connect(SOCKET s, const struct sockaddr FAR * name, int namelen);

The connect function establishes a connection to a remote host. This is typically used by a client application to initiate communication with a server.

Parameters

Parameter Description
s A descriptor identifying an unconnected socket.
name A pointer to a sockaddr structure that specifies the remote address to connect to. For AF_INET, this is a sockaddr_in structure.
namelen The length, in bytes, of the name structure.

Return Value

If the connection is immediately established, connect returns zero. If the connection attempt is in progress (for non-blocking sockets), it returns WSAEINPROGRESS. On failure, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

listen

C++
int listen(SOCKET s, int backlog);

The listen function places a socket in a state where it is ready to accept incoming connection requests. This function is used by server applications.

Parameters

Parameter Description
s A descriptor identifying a bound and connection-ready socket.
backlog The maximum length of the queue of pending connections. If this parameter is SOMAXCONN, the implementation will choose a reasonable default.

Return Value

If no error occurs, listen returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

accept

C++
SOCKET accept(SOCKET s, struct sockaddr FAR * addr, int FAR * addrlen);

The accept function extracts the first connection on the queue of pending connections for the listening socket s. It creates a new socket for the communication and returns its descriptor.

Parameters

Parameter Description
s A descriptor identifying a socket that is listening for connections.
addr (Optional) A pointer to a buffer that will receive the address of the connecting entity, as known to the communications service.
addrlen (Optional) A pointer to a variable that specifies the size of the structure pointed to by the addr argument.

Return Value

If no error occurs, accept returns a descriptor for the newly created socket. Otherwise, it returns INVALID_SOCKET, and a specific error code can be retrieved using WSAGetLastError.

send

C++
int send(SOCKET s, const char FAR * buf, int len, int flags);

The send function sends data on a connected socket. The type of socket (connection-oriented or connectionless) determines the semantics of this function.

Parameters

Parameter Description
s A descriptor identifying a socket.
buf A pointer to a buffer containing the data to be transmitted.
len The length, in bytes, of the data in buf.
flags Flags that influence the transmission. Common flags include MSG_PEEK to view data without removing it from the queue.

Return Value

If no error occurs, send returns the number of bytes sent. For sockets that are connection oriented, it may return a value less than len if not all data could be sent at once. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

recv

C++
int recv(SOCKET s, char FAR * buf, int len, int flags);

The recv function receives data from a connected socket. The type of socket (connection-oriented or connectionless) determines the semantics of this function.

Parameters

Parameter Description
s A descriptor identifying a socket.
buf A pointer to a buffer that will receive the incoming data.
len The maximum number of bytes to receive.
flags Flags that influence the reception. Common flags include MSG_PEEK to view data without removing it from the queue.

Return Value

If no error occurs, recv returns the number of bytes received. If the connection has been gracefully closed, a return value of zero indicates that the entire data for this session has been received. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

sendto

C++
int sendto(SOCKET s, const char FAR * buf, int len, int flags, const struct sockaddr FAR * to, int tolen);

The sendto function sends datagrams over a connectionless socket. It allows specifying the destination address for each send operation.

Parameters

Parameter Description
s A descriptor identifying a socket.
buf A pointer to a buffer containing the data to be transmitted.
len The length, in bytes, of the data in buf.
flags Flags that influence the transmission.
to A pointer to a sockaddr structure that specifies the destination address.
tolen The length, in bytes, of the sockaddr structure pointed to by to.

Return Value

If no error occurs, sendto returns the number of bytes sent. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

recvfrom

C++
int recvfrom(SOCKET s, char FAR * buf, int len, int flags, struct sockaddr FAR * from, int FAR * fromlen);

The recvfrom function receives datagrams from a connectionless socket. It also retrieves the address of the sender.

Parameters

Parameter Description
s A descriptor identifying a socket.
buf A pointer to a buffer that will receive the incoming data.
len The maximum number of bytes to receive.
flags Flags that influence the reception.
from (Optional) A pointer to a sockaddr structure that will receive the address of the sender.
fromlen (Optional) A pointer to a variable that specifies the size of the structure pointed to by from.

Return Value

If no error occurs, recvfrom returns the number of bytes received. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

closesocket

C++
int closesocket(SOCKET s);

The closesocket function closes an existing socket. After a socket is closed, no further operations can be performed on it.

Parameters

Parameter Description
s A descriptor identifying the socket to be closed.

Return Value

If no error occurs, closesocket returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved using WSAGetLastError.

gethostbyname

C++
struct hostent FAR* gethostbyname(const char FAR* name);

The gethostbyname function retrieves the IP address and other information for a given host name. This is a legacy function and getaddrinfo is recommended for modern applications.

Parameters

Parameter Description
name The name of the host to resolve.

Return Value

On success, gethostbyname returns a pointer to a hostent structure. On failure, it returns NULL and sets h_errno.

gethostbyaddr

C++
struct hostent FAR* gethostbyaddr(const char FAR* addr, int len, int af);

The gethostbyaddr function retrieves the host name and address information for a given IP address. This is a legacy function and getaddrinfo is recommended for modern applications.

Parameters

Parameter Description
addr A pointer to a buffer containing the IP address.
len The length, in bytes, of the address.
af The address family (e.g., AF_INET).

Return Value

On success, gethostbyaddr returns a pointer to a hostent structure. On failure, it returns NULL and sets h_errno.

getaddrinfo

C++
int getaddrinfo(const char FAR* nodename, const char FAR* servname, const struct addrinfo FAR* hints, struct addrinfo FAR* FAR* ppResult);

The getaddrinfo function provides protocol-independent translation of hostnames and service names to socket address structures. It is the recommended function for name resolution and address lookup.

Parameters

Parameter Description
nodename A pointer to a null-terminated string that contains a hostname or a numeric host address.
servname A pointer to a null-terminated string that contains a service name or a numeric port number.
hints A pointer to an addrinfo structure that specifies criteria for the algorithm to select the socket address structures. If NULL, no hints are provided.
ppResult A pointer to a pointer to an addrinfo structure. The getaddrinfo function allocates and fills in a linked list of addrinfo structures.

Return Value

If the function succeeds, it returns zero. If the function fails, it returns a non-zero error code.

freeaddrinfo

C++
void freeaddrinfo(struct addrinfo FAR* pAddrInfo);

The freeaddrinfo function frees the memory that was allocated by a previous call to getaddrinfo.

Parameters

Parameter Description
pAddrInfo A pointer to the first addrinfo structure in the linked list to be freed.

Return Value

This function does not return a value.