ioctlsocket function
The ioctlsocket function controls the I/O mode of a socket.ioctlsocket函數控制套接字的I/O模式。
Syntax
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 |
|---|---|
|
A successful WSAStartup call must occur before using this function. |
|
|
The network subsystem has failed. |
|
|
A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function. |
|
|
The descriptor s is not a socket. |
|
|
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.
#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 |
|
|
Library |
|
|
DLL |
|