# CreateIOReq

Creates an I/O request.

### Synopsis

`Item CreateIOReq( const char *name, uint8 pri, Item dev, Item mp )`

### Description

This convenience procedure creates an I/O request item.

When you create an I/O request, you must decide how the device will notify you when an I/O operation completes. There are two choices:

- Notification by signal
- Notification by message

With notification by signal, the device will send your task the SIGF_IODONE signal whenever an I/O operation completes. This is a low-overhead mechanism, which is also low on information. When you get the signal, all you know is that an I/O operation has completed. You do not know which operation has completed. This has to be determined by looking at the state of all outstanding I/O requests.

Notification by message involves slightly more overhead, but provides much more information. When you create the I/O request, you indicate a message port. Whenever an I/O operation completes, the device will send a message to that message port. The message will contain the following information:

- msg_Result Contains the io_Error value from the I/O request. This indicates the state of the I/O operation, whether it worked or failed.
- msg_DataPtr Contains the item number of the I/O request that completed.
- msg_DataSize Contains the value of the ioi_User field taken from the IOInfo structure used when initiating the I/O operation.

### Arguments

name
  The name of the I/O request (see "Notes").

pri
  The priority of the I/O request. For some device drivers, this value determines the order in which I/O requests are processed. When in doubt about what value to use, use 0.

dev
  The item number of the device to which to send the I/O request.

mp
  If a task wants to receive a message when an I/O request is finished, this argument must be the item number of the message port to receive the message. If the task wants to receive a signal when an I/O request is finished instead of a message, this argument must be 0.

### Return Value

The procedure returns the item number of the new I/O request or one of the following error codes if an error occurs:

BADITEM
  The mp argument was not zero but did not specify a valid message port.

ER_Kr_ItemNotOpen
  The device specified by the dev argument is not open.

NOMEM
  There was not enough memory to complete the operation.

### Implementation

Convenience call implemented in clib.lib V20.

### Associated Files

io.h
  ANSI C Prototype

clib.lib
  ARM Link Library

### Notes

When you no longer need an I/O request, use `DeleteIOReq()` to delete it.

You can use `FindNamedItem()` to find a I/O request by name. When creating I/O requests, you should assign unique names whenever possible.

The kernel may change the priority of an I/O request to help optimize throughput.

### See Also

``DeleteIOReq`()`

#