Windows Sockets API (Winsock) Reference

Comprehensive documentation for networking functions in Windows.

Winsock Functions

This section provides detailed information about the functions available in the Windows Sockets API (Winsock) for network programming.

accept Accepts a connection on a socket.
bind Associates a local address with a socket.
closesocket Closes an existing socket.
connect Establishes a connection to a remote socket.
getaddrinfo Retrieves address structures that contain network address and socket address structure strings.
gethostname Retrieves the standard hostname for the current computer.
getpeername Retrieves the name of the remote station that a socket is connected to.
getsockname Retrieves the name of the local socket.
htonl Converts a 32-bit host long from host byte order to network byte order.
htons Converts a 16-bit host short from host byte order to network byte order.
inet_addr Converts an IPv4 dotted-decimal address string to a 32-bit representation.
inet_ntoa Converts an IPv4 address from host byte order to a dotted-decimal string.
ioctlsocket Controls the I/O mode of a socket.
listen Puts a socket into a listening state.
ntohl Converts a 32-bit network long from network byte order to host byte order.
ntohs Converts a 16-bit network short from network byte order to host byte order.
recv Receives data from a connected socket.
send Sends data on a connected socket.
socket Creates a socket.
WSAStartup Initializes the Winsock DLL.
WSACleanup Shuts down the Winsock DLL.

accept

Prototype: SOCKET accept(SOCKET s, struct sockaddr *addr, int *addrlen);

The accept function retrieves from the queue of pending connections on a socket the first connection, creates a new socket with the same properties of the original socket, and allocates a new file descriptor for that socket.

Parameters

s: A descriptor that identifies an unconnected, listening socket.
addr: A pointer to a buffer that will receive the address of the connecting entity. The structure of the address is determined by the socket's address family (see sockaddr).
addrlen: A pointer to an integer that specifies the size, in bytes, of the structure pointed to by the addr argument. When accept returns, this parameter is updated to indicate the actual size of the address returned.

Return Value

If no error occurs, accept returns a descriptor for a newly created socket that is connected to s by the same path. This returned descriptor is the same as a socket created with the socket function, and it has the same properties as the socket pointed to by the s parameter. If an error occurs, the value INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

bind

Prototype: int bind(SOCKET s, const struct sockaddr *name, int namelen);

The bind function associates a local address with a socket.

Parameters

s: A descriptor that identifies an unbound socket.
name: A pointer to a sockaddr structure that specifies the local address to assign to the socket. The structure should contain the address family, IP address, and port number.
namelen: The size, in bytes, of the sockaddr structure pointed to by the name parameter.

Return Value

If the bind operation completes successfully, bind returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

closesocket

Prototype: int closesocket(SOCKET s);

The closesocket function closes an existing socket.

Parameters

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 by calling WSAGetLastError.

connect

Prototype: int connect(SOCKET s, const struct sockaddr *name, int namelen);

The connect function establishes a connection to a remote socket.

Parameters

s: A descriptor that identifies an unbound socket.
name: A pointer to a sockaddr structure that specifies the remote address to which to connect.
namelen: The size, in bytes, of the sockaddr structure pointed to by the name parameter.

Return Value

If the connection is made successfully, connect returns zero. If the socket is nonblocking and the connection cannot be made immediately, connect returns SOCKET_ERROR and WSAGetLastError returns WSAEWOULDBLOCK. The application can use select to determine when the socket becomes writable, at which point the connection is established. If another error occurs, connect returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

getaddrinfo

Prototype: INT getaddrinfo(PCSTR pNodeName, PCSTR pServiceName, const ADDRINFOA *pHints, PADDRINFOA *ppResult);

The getaddrinfo function provides protocol-independent translation from a host name and a service name to a set of socket address structures.

Parameters

pNodeName: A pointer to a null-terminated string that contains a host name or an IP address string.
pServiceName: A pointer to a null-terminated string that contains a service name or a port number.
pHints: An optional pointer to an ADDRINFOA structure that specifies constraints on the type of socket address to return. NULL can be specified to indicate no constraints.
ppResult: A pointer to a pointer to an ADDRINFOA structure. The getaddrinfo function allocates and initializes a linked list of ADDRINFOA structures for the caller. This parameter receives a pointer to the first ADDRINFOA structure in the linked list.

Return Value

On success, getaddrinfo returns zero. On failure, it returns an appropriate Winsock error code, such as EAI_FAMILY, EAI_SOCKTYPE, EAI_BADFLAGS, EAI_BADHINTS, EAI_FAIL, EAI_AGAIN, or EAI_MEMORY.

gethostname

Prototype: int gethostname(char *name, int namelen);

The gethostname function retrieves the standard hostname for the current computer.

Parameters

name: A buffer that will receive the null-terminated hostname.
namelen: The size, in bytes, of the buffer pointed to by the name parameter.

Return Value

If no error occurs, gethostname returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

getpeername

Prototype: int getpeername(SOCKET s, struct sockaddr *name, int *namelen);

The getpeername function retrieves the name of the remote station that a socket is connected to.

Parameters

s: A descriptor that identifies a connected socket.
name: A pointer to a buffer that will receive the address of the remote station. The structure of the address is determined by the socket's address family.
namelen: A pointer to an integer that specifies the size, in bytes, of the buffer pointed to by the name parameter. When getpeername returns, this parameter is updated to indicate the actual size of the returned address.

Return Value

If no error occurs, getpeername returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

getsockname

Prototype: int getsockname(SOCKET s, struct sockaddr *name, int *namelen);

The getsockname function retrieves the common names associated with a socket.

Parameters

s: A descriptor that identifies the socket.
name: A pointer to a buffer that will receive the name of the local socket. The structure of the address is determined by the socket's address family.
namelen: A pointer to an integer that specifies the size, in bytes, of the buffer pointed to by the name parameter. When getsockname returns, this parameter is updated to indicate the actual size of the returned address.

Return Value

If no error occurs, getsockname returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

htonl

Prototype: unsigned long htonl(unsigned long hostlong);

The htonl function converts a 32-bit unsigned integer from host byte order to network byte order.

Parameters

hostlong: A 32-bit unsigned integer in host byte order.

Return Value

The htonl function returns the value of the 32-bit unsigned integer in network byte order.

htons

Prototype: unsigned short htons(unsigned short hostshort);

The htons function converts a 16-bit unsigned integer from host byte order to network byte order.

Parameters

hostshort: A 16-bit unsigned integer in host byte order.

Return Value

The htons function returns the value of the 16-bit unsigned integer in network byte order.

inet_addr

Prototype: in_addr inet_addr(const char *cp);

The inet_addr function converts an IPv4 address from dotted-decimal string notation to a 32-bit unsigned integer (the Internet host address).

Parameters

cp: A pointer to a null-terminated string that contains an IPv4 address in dot-decimal notation.

Return Value

If the input string is a valid IPv4 address, inet_addr returns the corresponding 32-bit value. If the input string is not a valid IPv4 address, inet_addr returns INADDR_NONE.

inet_ntoa

Prototype: char *inet_ntoa(struct in_addr in);

The inet_ntoa function converts an IPv4 address from network byte order to a string in dotted-decimal notation.

Parameters

in: A structure containing an IPv4 address in network byte order.

Return Value

If no error occurs, inet_ntoa returns a pointer to a static buffer containing the dotted-decimal string representation of the IPv4 address. If an error occurs, inet_ntoa returns NULL.

ioctlsocket

Prototype: int ioctlsocket(SOCKET s, long cmd, u_long *argp);

The ioctlsocket function controls the I/O mode of a socket.

Parameters

s: A descriptor identifying the socket.
cmd: The I/O control code.
argp: A pointer to an argument for the I/O control code.

Return Value

If no error occurs, ioctlsocket returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

listen

Prototype: int listen(SOCKET s, int backlog);

The listen function puts a socket into a listening state. This means that the socket is ready to accept incoming connection requests.

Parameters

s: A descriptor that identifies an unbound socket or a bound socket that is not yet in a listening state.
backlog: The maximum length of the queue of pending connections. If this value is greater than the maximum queue length allowed by the system, the maximum queue length is used.

Return Value

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

ntohl

Prototype: unsigned long ntohl(unsigned long netlong);

The ntohl function converts a 32-bit unsigned integer from network byte order to host byte order.

Parameters

netlong: A 32-bit unsigned integer in network byte order.

Return Value

The ntohl function returns the value of the 32-bit unsigned integer in host byte order.

ntohs

Prototype: unsigned short ntohs(unsigned short netshort);

The ntohs function converts a 16-bit unsigned integer from network byte order to host byte order.

Parameters

netshort: A 16-bit unsigned integer in network byte order.

Return Value

The ntohs function returns the value of the 16-bit unsigned integer in host byte order.

recv

Prototype: int recv(SOCKET s, char *buf, int len, int flags);

The recv function receives data from a connected socket or a listening socket.

Parameters

s: A descriptor identifying the socket.
buf: A pointer to the buffer that will receive the incoming data.
len: The length, in bytes, of the buffer pointed to by the buf parameter.
flags: Flags that influence the way the send operation is performed. See Winsock documentation for details.

Return Value

If no error occurs, recv returns the number of bytes received. If the connected socket is gracefully closed, the return value is zero. If the socket is in nonblocking mode and there is no data available to be received, recv returns SOCKET_ERROR and WSAGetLastError returns WSAEWOULDBLOCK. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

send

Prototype: int send(SOCKET s, const char *buf, int len, int flags);

The send function sends data on a connected socket.

Parameters

s: A descriptor identifying the socket.
buf: A pointer to the buffer containing the data to be sent.
len: The length, in bytes, of the data in the buffer pointed to by the buf parameter.
flags: Flags that influence the way the send operation is performed. See Winsock documentation for details.

Return Value

If no error occurs, send returns the number of bytes sent. If the socket is in nonblocking mode and the data cannot be sent immediately, send returns SOCKET_ERROR and WSAGetLastError returns WSAEWOULDBLOCK. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

socket

Prototype: SOCKET socket(int af, int type, int protocol);

The socket function creates a socket that is bound to a specific transport-service provider.

Parameters

af: The address family specification. Currently, only AF_INET and AF_INET6 are supported.
type: The socket type specification. The supported types are SOCK_STREAM (for connection-oriented protocols like TCP) and SOCK_DGRAM (for connectionless protocols like UDP).
protocol: The particular protocol to be used with the created socket. The specific enumerated protocol values applicable to the specified address family and socket type should be used. Use 0 to indicate that the default protocol for the indicated address family and socket type should be used.

Return Value

If no error occurs, socket returns a descriptor for the newly created socket. This descriptor is a small integer that is used to reference the socket in subsequent function calls. Otherwise, socket returns INVALID_SOCKET, and a specific error code can be retrieved by calling WSAGetLastError.

WSAStartup

Prototype: int WSAStartup(WORD wVersionRequired, LPWSADATA lpWSAData);

The WSAStartup function initiates the use of the Winsock DLL. It is the first Winsock function that an application must call.

Parameters

wVersionRequired: The version of the Winsock DLL that the calling application requests. The high-order byte specifies the minor version number; the low-order byte specifies the major version number.
lpWSAData: A pointer to a WSADATA structure that receives implementation-specific information about the Winsock DLL. The WSADATA structure should not be initialized by the caller.

Return Value

If the call to WSAStartup is successful, the return value is zero. If the call fails, the return value is one of the Winsock error codes listed in the Winsock error code table.

WSACleanup

Prototype: int WSACleanup(void);

The WSACleanup function terminates the use of the Winsock DLL. It is the last Winsock function that an application must call.

Return Value

If the call to WSACleanup is successful, the return value is zero. If the call fails, the return value is SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.