SIO_RCVALL Control Code
Description
The SIO_RCVALL control code enables a socket to receive all IPv4 or IPv6 packets passing through a network interface.
To perform this operation, call the WSAIoctl or WSPIoctl function with the following parameters.
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_RCV_ALL, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
NULL, // lpvOutBuffer output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);
Parameters
s
A descriptor identifying a socket.
dwIoControlCode
The control code for the operation. Use SIO_RCVALL for this operation.
lpvInBuffer
A pointer to the input buffer that should contain the option value. The possible values for the SIO_RCVALL IOCTL option are specified in the RCVALL_VALUE enumeration defined in the Mstcpip.h header file.
The possible values for SIO_RCVALL are as follows:
| Value | Meaning |
|---|---|
| RCVALL_OFF | Disable this option so a socket does not receive all IPv4 or IPv6 packets passing through a network interface. |
| RCVALL_ON | Enable this option so a socket receives all IPv4 or IPv6 packets passing through a network interface. This option enables promiscuous mode on the network interface card (NIC), if the NIC supports promiscuous mode. On a LAN segment with a network hub, a NIC that supports promiscuous mode will capture all IPv4 or IPv6 traffic on the LAN, including traffic between other computers on the same LAN segment. All of the captured packets (IPv4 or IPv6, depending on the socket) will be delivered to the raw socket. This option will not capture other packets (ARP, IPX, and NetBEUI packets, for example) on the interface. Netmon uses the same mode for the network interface, but does not use this option to capture traffic. |
| RCVALL_SOCKETLEVELONLY | This feature is not currently implemented, so setting this option does not have any affect. |
| RCVALL_IPLEVEL | Enable this option so an IPv4 or IPv6 socket receives all packets at the IP level passing through a network interface. This option does not enable promiscuous mode on the network interface card. This option only affects packet processing at the IP level. The NIC still receives only packets directed to its configured unicast and multicast addresses. However, a socket with this option enabled will receive not only packets directed to specific IP addresses, but will receive all the IPv4 or IPv6 packets the NIC receives. This option will not capture other packets (ARP, IPX, and NetBEUI packets, for example) received on the interface. |
cbInBuffer
The size, in bytes, of the input buffer. This parameter should be equal to or greater than the size of the RCVALL_VALUE enumeration value pointed to by the lpvInBuffer parameter.
lpvOutBuffer
A pointer to the output buffer. This parameter is unused for this operation.
cbOutBuffer
The size, in bytes, of the output buffer. This parameter is unused for this operation.
lpcbBytesReturned
A pointer to a variable that receives the size, in bytes, of the data stored in the output buffer. This parameter is unused for this operation.
lpvOverlapped
A pointer to a WSAOVERLAPPED structure.
If socket s was created without the overlapped attribute, the lpOverlapped parameter is ignored.
If s was opened with the overlapped attribute and the lpOverlapped parameter is not NULL, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped parameter must point to a valid WSAOVERLAPPED structure.
For overlapped operations, the WSAIoctl or WSPIoctl function returns immediately, and the appropriate completion method is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.
lpCompletionRoutine
Type: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
A pointer to the completion routine called when the operation has been completed (ignored for non-overlapped sockets).
lpThreadId
A pointer to a WSATHREADID structure to be used by the provider in a subsequent call to WPUQueueApc. The provider should store the referenced WSATHREADID structure (not the pointer to same) until after the WPUQueueApc function returns.
Note This parameter applies only to the WSPIoctl function.
lpErrno
A pointer to the error code.
Note This parameter applies only to the WSPIoctl function.
Return value
If the operation completes successfully, the WSAIoctl or WSPIoctl function returns zero.
If the operation fails or is pending, the WSAIoctl or WSPIoctl function returns SOCKET_ERROR. To get extended error information, call WSAGetLastError.
| Error code | Meaning |
|---|---|
| WSA_IO_PENDING | An overlapped operation was successfully initiated and completion will be indicated at a later time. |
| WSA_OPERATION_ABORTED | An overlapped operation was canceled due to the closure of the socket or the execution of the SIO_FLUSH IOCTL command. |
| WSAEFAULT | The lpOverlapped or lpCompletionRoutine parameter is not totally contained in a valid part of the user address space. |
| WSAEINPROGRESS | The function is invoked when a callback is in progress. |
| WSAEINTR | A blocking operation was interrupted. |
| WSAEINVAL | The dwIoControlCode parameter is not a valid command, or a specified input parameter is not acceptable, or the command is not applicable to the type of socket specified. This error is also returned if the cbInBuffer parameter is less than the sizeof(UCHAR) or the lpvInBuffer parameter points to value that is not a RCVALL_VALUE enumeration value. This error can also be returned if the network interface associated with the socket cannot be found. This could occur if the network interface associated with the socket is deleted or removed (a remove PCMCIA or USB network device, for example). |
| WSAENETDOWN | The network subsystem has failed. |
| WSAENOBUFS | No buffer space available. |
| WSAENOPROTOOPT | The socket option is not supported on the specified protocol. |
| WSAENOTSOCK | The descriptor s is not a socket. |
| WSAEOPNOTSUPP | The specified IOCTL command is not supported. This error is returned if the SIO_RCVALL IOCTL is not supported by the transport provider. |
Remarks
The SIO_RCVALL IOCTL is supported on Windows 2000 and later versions of the operating system.
The SIO_RCVALL IOCTL enables a socket to receive all IPv4 or IPv6 packets on a network interface. The socket handle passed to the WSAIoctl or WSPIoctl function must be one of the following:
- An IPv4 socket that was created with the address family set to AF_INET, the socket type set to SOCK_RAW, and the protocol set to IPPROTO_IP.
- An IPv6 socket that was created with the address family set to AF_INET6, the socket type set to SOCK_RAW, and the protocol set to IPPROTO_IPV6.
For more information on raw sockets, see TCP/IP Raw Sockets.
The socket also must be bound to an explicit local IPv4 or IPv6 interface, which means that you cannot bind to INADDR_ANY or in6addr_any.
Once the socket is bound and the IOCTL completes successfully, calls to the WSARecv or recv functions return IPv4 datagrams passing through the given IPv4 interface or return IPv6 datagrams passing through the given IPv6 interface. Note that you must supply a sufficiently large buffer. Setting this IOCTL will only capture IPv4 or IPv6 packets on a given interface. This IOCTL will not capture other packets (ARP, IPX, and NetBEUI packets, for example) on the interface.
A socket bound to a specific local interface with the SIO_RCVALL IOCTL will receive only packets passing through that interface. It will not receive packets received on another interface and getting forwarded out on another interface different from the socket bound with SIO_RCVALL IOCTL.
On Windows Server 2008 and earlier, the SIO_RCVALL IOCTL setting would not capture local packets sent out of a network interface. This included packets received on another interface and forwarded out the network interface specified for the SIO_RCVALL IOCTL.
On Windows 7 and Windows Server 2008 R2 , this was changed so that local packets sent out of a network interface are also captured. This includes packets received on another interface and then forwarded out the network interface bound to the socket with SIO_RCVALL IOCTL.
Setting this IOCTL requires Administrator privilege on the local computer.
This feature is sometimes referred to as promiscuous mode. Any direct change from applying this option on one interface and then to another interface with a single call using this IOCTL is not supported. An application must first use this IOCTL to turn off the behavior on the first interface, and then use this IOCTL to enable the behavior on a new interface.