The ioctlsocket function controls the I/O mode of a socket.
int ioctlsocket(
SOCKET s,
long cmd,
u_long *argp
)
s
Type: SOCKET
[in]
A descriptor identifying a socket.
cmd
Type: long
[in]
A command to perform on the socket s.
argp
Type: u_long *
[in, out]
A pointer to a parameter for cmd.
Type: int
Upon successful completion, the ioctlsocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.
| Return code | Description |
|---|---|
| WSANOTINITIALISED | A successful WSAStartup call must occur before using this function. |
| WSAENETDOWN | The network subsystem has failed. |
| WSAEINPROGRESS | A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function. |
| WSAENOTSOCK | The descriptor s is not a socket. |
| WSAEFAULT | The argp parameter is not a valid part of the user address space. |
The ioctlsocket function can be used on any socket in any state. It is used to set or retrieve some operating parameters associated with the socket, independent of the protocol and communications subsystem. Here are the supported commands to use in the cmd parameter and their semantics:
FIONBIO
The *argp parameter is a pointer to an unsigned long value. Set *argp to a nonzero value if the nonblocking mode should be enabled, or zero if the nonblocking mode should be disabled. When a socket is created, it operates in blocking mode by default (nonblocking mode is disabled). This is consistent with BSD sockets.
| *argp value | Nonblocking mode |
|---|---|
| 0 | Disabled |
| nonzero | Enabled |
The WSAAsyncSelect and WSAEventSelect functions automatically set a socket to nonblocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a socket, then any attempt to use ioctlsocket to set the socket back to blocking mode will fail with WSAEINVAL.
To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.
FIONREAD
Use to determine the amount of data pending in the network’s input buffer that can be read from socket s. The argp parameter points to an unsigned long value in which ioctlsocket stores the result. FIONREAD returns the amount of data that can be read in a single call to the recv function, which may not be the same as the total amount of data queued on the socket. If s is message oriented (for example, type SOCK_DGRAM), FIONREAD still returns the amount of pending data in the network buffer, however, the amount that can actually be read in a single call to the recv function is limited to the data size written in the send or sendto function call.
SIOCATMARK
Use to determine if all out of band (OOB) data has been read. (See Windows Sockets 1.1 Blocking Routines and EINPROGRESS for a discussion on OOB data.) This applies only to a stream oriented socket (for example, type SOCK_STREAM) that has been configured for in-line reception of any OOB data (SO_OOBINLINE). On sockets with the SO_OOBINLINE socket option set, SIOCATMARK always returns TRUE and the OOB data is returned to the user as normal data.
The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem. The WSAIoctl function is more powerful than the ioctlsocket function and supports a large number of possible values for the operating parameters to set or retrieve.
The following example demonstrates the use of the ioctlsocket function.
This ioctlsocket function performs only a subset of functions on a socket when compared to the ioctl function found in Berkeley sockets. The ioctlsocket function has no command parameter equivalent to the FIOASYNC of ioctl, and SIOCATMARK is the only socket-level command that is supported by ioctlsocket.
Windows Phone 8: This API is supported.
Header: Declared in winsock2.h.
Library: Use ws2_32.lib.