ioctlsocket

The Windows Sockets ioctlsocket function controls the I/O mode of a socket.

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

Parameters

s

[in] A descriptor identifying a socket.

cmd

[in] The command to perform on the socket s.

argp

[in/out] A pointer to a parameter for cmd.

Remarks

The ioctlsocket 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. Here are the supported commands to use in the cmd parameter and their semantics:

FIONBIO

Use 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 WSAAsyncSelect and WSAEventSelect functions automatically set a socket to nonblocking mode. If WSAAsyncSelect or 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 WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.

FIONREAD

Use 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

Use to determine whether or not all out-of-band data has been read. (See section Windows Sockets 1.1 Blocking Routines & EINPROGRESS for a discussion on Out of Band (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 out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next recv or recvfrom performed on the socket will retrieve some or all of the data preceding the "mark." The application should use the SIOCATMARK operation to determine whether any data remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (A recv or recvfrom will never mix out-of-band and normal data in the same call.) The argp parameter points to an unsigned long value in which ioctlsocket stores the boolean result.

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.

Return Values

Upon successful completion, the ioctlsocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Use version 1.0 and later.
  Header: Declared in winsock2.h.
  Import Library: Link with ws2_32.lib.

See Also

getsockopt, setsockopt, socket, WSAAsyncSelect, WSAEventSelect, WSAIoctl