CreateIoCompletionPort Subroutine

Purpose

Creates an I/O completion port with no associated file descriptor or associates an opened socket or file with an existing or newly created I/O completion port.

Syntax

#include <iocp.h>
int CreateIoCompletionPort (FileDescriptor, CompletionPort, CompletionKey, ConcurrentThreads)
HANDLE FileDescriptor, CompletionPort;
DWORD CompletionKey, ConcurrentThreads;

Description

The CreateIoCompletionPort subroutine creates an I/O completion port or associates an open file descriptor with an existing or newly created I/O completion port. When creating a new I/O completion port, the CompletionPort parameter is set to NULL, the FileDescriptor parameter is set to INVALID_HANDLE_VALUE (-1), and the CompletionKey parameter is ignored.

The CreateIoCompletionPort subroutine returns a descriptor (an integer) to the I/O completion port created or modified.

The CreateIoCompletionPort subroutine is part of the I/O Completion Port (IOCP) kernel extension.

Note: This subroutine only works with file descriptors of sockets, or regular files for use with the Asynchronous I/O (AIO) subsystem. It does not work with file descriptors of other types.

Parameters

Item	Description
FileDescriptor	Specifies a valid file descriptor obtained from a call to the socket or accept subroutines.
CompletionPort	Specifies a valid I/O completion port descriptor. Specifying a CompletionPort parameter value of NULL causes the CreateIoCompletionPort subroutine to create a new I/O completion port.
CompletionKey	Specifies an integer to serve as the identifier for completion packets generated from a particular file-completion port set.
ConcurrentThreads	This parameter is not implemented and is present only for compatibility purposes.

Return Values

Upon successful completion, the CreateIoCompletionPort subroutine returns an integer (the I/O completion port descriptor).

If the CreateIoCompletionPort is unsuccessful, the subroutine handler performs the following functions:

Returns a value of NULL to the calling program.
Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable, see the link in the Related Information section of this document.

Error Codes

The CreateIoCompletionPort subroutine is unsuccessful if either of the following errors occur:

Item	Description
EBADF	The I/O completion port descriptor is invalid.
EINVAL	The file descriptor is invalid.
EALREADY	The file descriptor is already associated.

Examples

The following program fragment illustrates the use of the CreateIoCompletionPort subroutine to create a new I/O completion port with no associated file descriptor:

c = CreateIoCompletionPort (INVALID_HANDLE_VALUE, NULL, 0, 0);

The following program fragment illustrates the use of the CreateIoCompletionPort subroutine to associate file descriptor 34 (which has a newly created I/O completion port) with completion key 25:

c = CreateIoCompletionPort (34, NULL, 25, 0);

The following program fragment illustrates the use of the CreateIoCompletionPort subroutine to associate file descriptor 54 (which has an existing I/O completion port) with completion key 15:

c = CreateIoCompletionPort (54, 12, 15, 0);