Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

Syntax 

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

The following table shows a list of possible error codes.

Error code Description

WSANOTINITIALISED

A successful WSAStartupcall 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 sis not a socket.

WSAEFAULT

The argpparameter 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 cmdparameter and their semantics are as follows.

FIONBIO

Use FIONBIO with a nonzero argpparameter to enable the nonblocking mode of socket s. The argpparameter is zero if nonblocking is to be disabled. The argpparameter 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 WSAEventSelectfunction automatically sets a socket to nonblocking mode. If WSAEventSelecthas been issued on a socket, then any attempt to use ioctlsocketto set the socket back to blocking mode will fail with WSAEINVAL.

To set the socket back to blocking mode, an application must first disable WSAEventSelectby calling WSAEventSelectwith the lNetworkEventsparameter 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 argpparameter points to an unsigned long value in which ioctlsocketstores the result. If sis stream-oriented (for example, type SOCK_STREAM), FIONREAD returns the amount of data that can be read in a single call to the recvfunction; this might not be the same as the total amount of data queued on the socket. If sis 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 ioctlsocketfunction performs only a subset of functions on a socket when compared to the ioctlfunction found in Berkeley sockets. The ioctlsocketfunction 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 WSAIoctland ioctlsocketfunctions control the mode of a socket. WSAIoctlrequires Winsock 2.2 and allows overlapped or asynchronous operation. The ioctlsocketfunction 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

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

See Also