Contents | Prev | Next

Description

The ioctlsocket function sends commands to sockets. See the description of the function arguments below, for information about the commands that can be sent.

Declaration

The system include file WinSock2.inc contains the following declaration for the ioctlsocket function:

function ioctlsocket(s : SOCKET; cmd : integer; var argp : u_long) : integer;
  external dll='ws2_32.dll';

Arguments

The First Argument

The first argument passed to the ioctlsocket function is the socket that you want to send a command to.

The Second Argument

The second argument passed to the ioctlsocket function is the command that you want to send to the socket. The Windows Sockets API supports three commands, and these commands are:

1. FIONBIO - Enables or disables the socket's non-blocking mode. The value of the third argument specifies whether non-blocking mode is enabled or disabled. Use a non-zero value for the third argument to enable non-blocking mode, and zero to disable non-blocking mode. NOTE: When a socket is created, it's non-blocking mode is disabled.
2. FIONREAD - Returns the amount of data that can be read from the socket in a single call. This is not necessarily the same as the total amount of data waiting to be read from the socket. For datagram sockets the value returned by this command is the size of the first datagram waiting to be read. NOTE: The value returned by this command is placed in the third argument to this function.
3. SIOCATMARK - Returns whether or not all Out Of Band (OOB) data has been read. This command returns a non-zero value if there is no OOB data waiting to be read, and zero if there is OOB data waiting to be read. A full description of OOB data is outside the scope of this manual, however OOB data is basically data that is sent with high priority. OOB data can jump the queue and be read at the other end before normal data that was sent previously. NOTE: OOB data and normal data are never read together in the same call. NOTE: The value returned by this command is placed in the third argument to this function.

The Third Argument

The third argument passed to the ioctlsocket function is of type u_long and is passed by reference. You use this argument to further specify what the command should do or to retrieve values returned by the command.

Return Values

The ioctlsocket function returns a value of integer type that indicates whether the call was successful. A value of zero means that the call succeeded. A value of SOCKET_ERROR indicates that the called failed, and in this case you can use the WSAGetLastError function to retrieve a code that identifies the error that caused the call to fail. NOTE: The constant SOCKET_ERROR is declared in the system include file WinSock2.inc.

Example

The following code fragments illustrates how to enable socket's non-blocking mode.

 ulNonBlockingMode := 1;
 iRet := ioctlsocket(s, FIONBIO, ulNonBlockingMode);

The code fragment above assumes that s is a socket that has already been created, ulNonBlockingMode is a variable of type u_long, and iRet is a variable of integer type. NOTE: The type u_long is declared in the system include file WinSock2.inc.

Reference Information

The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.

Contents | Prev | Next