ioctlsocket

ioctlsocket function

The ioctlsocket function controls the I/O mode of a socket.ioctlsocket函数控制套接字的I/O模式。

Syntax

C++

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

Parameters

s [in]

A descriptor identifying a socket.套接字。

cmd [in]

A command to perform on the socket s.套接字s要实现的命令。

argp [in, out]

A pointer to a parameter for cmd.cmd所需的参数。

Return value

Upon successful completion, the ioctlsocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by callingWSAGetLastError.成功返回0。否则，返回SOCKET_ERROR，通过调用WSAGetLastError可以得到指定的错误码。

Error code	Meaning
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.

 

Remarks

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:ioctlsocket函数可以用在任何套接字的任何状态下。可以用来设置或者取得套接字的操作参数，这些与通信协议和通信子系统无关。下面是支持的命令参数和具体的语义。

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指向一个无符号long。如果要用非阻塞模式，argp要设置为非零，否则设置为0。默认创建的套接字都是阻塞模式。下面是BSD套接字用的常量。

*argp value	Nonblocking mode
0	Disabled
nonzero	Enabled

 

The WSAAsyncSelect and WSAEventSelect functions automatically set a socket to nonblocking mode. IfWSAAsyncSelect or WSAEventSelect has been issued on a socket, then any attempt to useioctlsocket to set the socket back to blocking mode will fail withWSAEINVAL.

To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with thelEvent parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect with thelNetworkEvents parameter equal to zero.WSAAsyncSelect和WSAEventSelect函数自动设置套接字为非阻塞模式。如果WSAAsyncSelect和WSAEventSelect已经设置过一个套接字，那么之后任何试图使用ioctlsocket将其设置回阻塞模式都会失败，并且返回WSAEINVAL。

FIONREAD

Use to determine the amount of data pending in the network's input buffer that can be read from sockets. The argp parameter points to an unsigned long value in whichioctlsocket stores the result. FIONREAD returns the amount of data that can be read in a single call to therecv function, which may not be the same as the total amount of data queued on the socket. Ifs 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 therecv function is limited to the data size written in the send or sendto function call.用来设置从网络输入缓冲中读取套接字s的数据数量。argp参数指向一个无符号long值，ioctlsocket将结果保存在这个参数里。FIONREAD（这个地方应该是argp，或者说应该是FIONREAD的使用）返回了单次调用recv可以返回的数据数量，这可能跟已在套接字队列里的数据数量不一样。如果套接字s是基于消息的（例如SOCK_DGRAM），FIONREAD（同上）会返回在网络缓冲中挂起的数据的数量，但是，单次recv调用可以得到的数据量被限制为send或者sendto中指定的大小。（原谅我吧，英语老师X的早……）

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.用来决定是否所有的外带数据已读。这个参数仅用于已配置为在线接收任何外带数据（SO_OOBINLINE）的流式套接字（例如SOCK_STREM）。

The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem.TheWSAIoctl function is more powerful than the ioctlsocket function and supports a large number of possible values for the operating parameters to set or retrieve.WSAIoctl函数用来设置或者取得套接字、传输协议或者通信子系统的操作参数。这个函数比ioctlsocket更NB支持更多的参数。

Example Code

The following example demonstrates the use of the ioctlsocket function.

C++

#include <winsock2.h>
#include <stdio.h>

#pragma comment(lib, "Ws2_32.lib")

void main()
{
//-------------------------
// Initialize Winsock
WSADATA wsaData;
int iResult;
u_long iMode = 0;

iResult = WSAStartup(MAKEWORD(2,2), &wsaData);
if (iResult != NO_ERROR)
  printf("Error at WSAStartup()\n");

//-------------------------
// Create a SOCKET object.
SOCKET m_socket;
m_socket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
if (m_socket == INVALID_SOCKET) {
  printf("Error at socket(): %ld\n", WSAGetLastError());
  WSACleanup();
  return;
}

//-------------------------
// Set the socket I/O mode: In this case FIONBIO
// enables or disables the blocking mode for the 
// socket based on the numerical value of iMode.
// If iMode = 0, blocking is enabled; 
// If iMode != 0, non-blocking mode is enabled.

iResult = ioctlsocket(m_socket, FIONBIO, &iMode);
if (iResult != NO_ERROR)
  printf("ioctlsocket failed with error: %ld\n", iResult);
  

}

Compatibility

This ioctlsocket function performs only a subset of functions on a socket when compared to theioctl function found in Berkeley sockets. The ioctlsocket function has no command parameter equivalent to the FIOASYNC ofioctl, and SIOCATMARK is the only socket-level command that is supported byioctlsocket.

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Minimum supported client	Windows 8.1, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Minimum supported phone	Windows Phone 8
Header	Winsock2.h
Library	Ws2_32.lib
DLL	Ws2_32.dll

See also

Winsock Reference

Winsock Functions

getsockopt

setsockopt

socket

WSAAsyncSelect

WSAEventSelect

WSAIoctl