ioctlsocket

Article
06/30/2006

This function controls the I/O mode of a socket.

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

Parameters

s
[in] Descriptor identifying a socket.
cmd
[in] Command to perform on socket s.
argp
[in, out] Pointer to a parameter for cmd.

Return Values

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

The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEINPROGRESS	A blocking Winsock 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.
WSAEINVAL	An unsupported or invalid parameter.

Remarks

This function can be used on any socket in any state. It is used to set or retrieve operating parameters associated with the socket, independent of the protocol and communications subsystem. The supported commands to use in the cmd parameter and their semantics are as follows.

FIONBIO

Use FIONBIO with a nonzero argp parameter to enable the nonblocking mode of socket s. The argp parameter is zero if nonblocking is to be disabled. The argp parameter points to an unsigned long value. When a socket is created, it operates in blocking mode by default (nonblocking mode is disabled). This is consistent with BSD sockets.

The WSAEventSelect function automatically sets a socket to nonblocking mode. If 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 WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.

FIONREAD

Use FIONREAD 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. If s is stream-oriented (for example, type SOCK_STREAM), FIONREAD returns the amount of data that can be read in a single call to the recv function; this might 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 returns the size of the first datagram (message) queued on the socket.

SIOCATMARK

SIOCATMARK is not supported and returns WSAEINVAL.

Compatibility

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.

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 list shows the Bluetooth-specific IOCTL codes that exist:

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

OS Versions: Windows CE 1.0 and later.
Header: Winsock2.h.
Link Library: Ws2.lib.