WSAIoctl

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function allows for miscellaneous control of a socket.

Syntax

int WSAIoctl(
  SOCKET s,
  DWORD dwIoControlCode,
  LPVOID lpvInBuffer,
  DWORD cbInBuffer,
  LPVOID lpvOutBuffer,
  DWORD cbOutBuffer,
  LPDWORD lpcbBytesReturned,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameters

s
[in] Descriptor identifying a socket.

dwIoControlCode
[in] Control code of the operation to perform.

lpvInBuffer
[in] Pointer to the input buffer.

cbInBuffer
[in] Size of the input buffer.

lpvOutBuffer
[out] Pointer to the output buffer.

cbOutBuffer
[in] Size of the output buffer.

lpcbBytesReturned
[out] Pointer to the actual number of bytes of output.

lpOverlapped
[in] Pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).

lpCompletionRoutine
[in] Pointer to the completion routine called when the operation has been completed (ignored for nonoverlapped sockets).

Return Value

If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling the WSAGetLastError function.

The following table shows a list of possible error codes.

Error code	Description
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The lpvInBuffer, lpvOutBuffer lpcbBytesReturned, lpOverlapped, or lpCompletionRoutine argument is not totally contained in a valid part of the user address space, or the cbInBuffer or cbOutBuffer argument is too small.
WSAEINVAL	The dwIoControlCode parameter is not a valid command, a supplied input parameter is not acceptable, or the command is not applicable to the type of socket supplied.
WSAEINPROGRESS	The function is invoked when a callback is in progress.
WSAENOTSOCK	The descriptor s is not a socket.
WSAEOPNOTSUPP	The specified ioctl command cannot be realized.
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.

Remarks

This function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem.

If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket. For a nonoverlapped socket, lpOverlapped and lpCompletionRoutine parameters are ignored, which cause the function to behave like the standard ioctlsocket function except that WSAIoctl can block if socket s is in blocking mode.

If socket s is in nonblocking mode, this function can return WSAEWOULDBLOCK when the specified operation cannot be finished immediately. In this case, the application may change the socket to blocking mode and reissue the request or wait for the corresponding network event (such as FD_ROUTING_INTERFACE_CHANGE or FD_ADDRESS_LIST_CHANGE in the case of SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE) using an event-based notification mechanism (using WSAEventSelect).

The overlapped structures are updated with the receive results, and the associated event is signalled.

For overlapped sockets, operations that cannot be completed immediately will be initiated and completion will be indicated at a later time. In Windows Embedded CE, the completion routine will not be called. Only the event mechanism can be used. The lpcbBytesReturned parameter is ignored.

Any IOCTL may block indefinitely, depending on the service provider's implementation. If the application cannot tolerate blocking in a WSAIoctl call, overlapped I/O would be advised for the following IOCTLs that are especially likely to block SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE.

Some protocol-specific IOCTLs may also be especially likely to block. Check the relevant protocol-specific annex for any available information.

It is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket operation codes while providing a convenient way to partition the operation code identifier space in as much as the dwIoControlCode parameter is now a 32-bit entity. The dwIoControlCode parameter is built to allow for protocol and vendor independence when adding new control codes, while retaining backward compatibility with the Winsock 1.1 and Unix control codes. The following table shows the form for the dwIoControlCode parameter.

I	O	V	T	Vendor/address family	Code
3	3	2	2 2	2 2 2 2 2 2 2 1 1 1 1	1 1 1 1 1 1
1	0	9	8 7	6 5 4 3 2 1 0 9 8 7 6	5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

I is set if the input buffer is valid for the code, as with IOC_IN.

O is set if the output buffer is valid for the code, as with IOC_OUT. Codes with both input and output parameters set both I and O.

V is set if there are no parameters for the code, as with IOC_VOID.

T is a 2-bit quantity that defines the type of IOCTL.

The following values are defined for T:

0 – The IOCTL is a standard Unix IOCTL code, as with FIONREAD and FIONBIO.
1 – The IOCTL is a generic Winsock IOCTL code. New IOCTL codes defined for Winsock will have T == 1.
2 – The IOCTL applies only to a specific address family.
3 – The IOCTL applies only to a specific vendor's provider. This type allows companies to be assigned a vendor number that appears in the Vendor/Address family field. Then, the vendor can define new IOCTLs specific to that vendor without having to register the IOCTL with a clearinghouse, thereby providing vendor flexibility and privacy.
Vendor/Address family – An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the address family to which the code applies (if T == 2). If this is a Unix IOCTL code (T == 0), then this field has the same value as the code on Unix. If this is a generic Winsock IOCTL (T == 1), then this field can be used as an extension of the code parameter to provide additional code values.
Code – The 16-bit quantity that contains the specific IOCTL code for the operation.

The following Unix IOCTL codes (commands) are supported.

FIONBIO

FIONBIO enables or disables nonblocking mode on socket s. lpvInBuffer points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.

The WSAEventSelect routines automatically set a socket to nonblocking mode. If WSAEventSelect has been issued on a socket, then any attempt to use WSAIoctl 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 WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.

FIONREAD

FIONREAD determines the amount of data that can be read atomically from socket s. lpvOutBuffer points at an unsigned long in which WSAIoctl stores the result. If s is stream-oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of data that can be read in a single receive operation; this is typically the same as the total amount of data queued on the socket (because the data stream is byte-oriented, this is not guaranteed). If socket s is message-oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.

The Windows Embedded CE service provider does not support the SIO_FLUSH command. If an overlapped operation completes immediately, WSAIoctl returns a value of zero and the lpcbBytesReturned parameter is updated with the number of bytes in the output buffer. If the overlapped operation is successfully initiated and will complete later, this function returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpcbBytesReturned is not updated. When the overlapped operation completes, the amount of data in the output buffer is indicated either through the cbTransferred parameter in the completion routine (if specified) or through the lpcbTransfer parameter in WSAGetOverlappedResult.

When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation. The lpOverlapped parameter contains the address of a WSAOVERLAPPED structure.

If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can use WSAGetOverlappedResult to wait or poll on the event object.

If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context information to the completion routine. A caller that passes a non-NULL lpCompletionRoutine and later calls WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case, the usage of the hEvent parameter is undefined and attempting to wait on the hEvent parameter would produce unpredictable results.

The prototype of the callback function is as follows:

        
        
        dwError
        
        
        cbTransferred
        
        
        lpOverlapped
        
        
        dwFlags

CompletionRoutine is a placeholder for an application-defined or library-defined function. The dwError parameter specifies the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred parameter specifies the number of bytes returned. Currently, there are no flag values defined and dwFlags will be zero. The CompletionRoutine function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. The completion routines can be called in any order, not necessarily in the same order the overlapped operations are completed.

Compatibility

The IOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley sockets. In particular, there is no command that is equivalent to FIOASYNC.

Notes for Bluetooth

The WSAIoctl and ioctlsocket functions control the mode of a socket. WSAIoctl requires Winsock 2.2 and allows overlapped or asynchronous operation. The ioctlsocket function can be used with Winsock 1.1 or later. The following Bluetooth-specific IOCTL codes are available:

SIO_RFCOMM_COMM_PARAMETERS sets or queries modem attributes. The structures used and calling semantics are the same as TDI_ACTION RFCOMM_COMM_PARAMETERS.
SIO_RFCOMM_WAIT_MODEM_STATUS gets the current status of the modem. The semantics are the same as TDI_ACTION RFCOMM_MODEM_STATUS.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later