SendIO

Requests asynchronous I/O.

Synopsis

Err SendIO( Item ior, const IOInfo *ioiP )

Description

This procedure sends an I/O request that is to be executed asynchronously. Because the request is asynchronous, control returns to the calling task as soon as the request is sent (unlike synchronous I/O, where control doesn't return until after the request has been completed).

Call this procedure after creating the necessary IOReq item (for the ior argument, created by calling CreateIOReq() ) and an IOInfo structure (for the ioiP argument). The IOReq item specifies the device to which to send the request and the reply port, if any, while the IOInfo structure includes the I/O command to be executed and a variety of other information. For descriptions of the IOReq and IOInfo data structures, see the Data Structures and Variable Type's chapter.

To request quick I/O, set the IO_QUICK flag in the ioi_Flags field of the IOInfo structure. Quick I/O works as follows: The kernel tries to perform the I/O operation immediately; if it is successful, it sends back the resulting IOReq item immediately without setting any signal bits or sending a message. If quick I/O was successful, the IO_QUICK bit in the io_Flags field of the IOReq is set. If quick I/O was not successful, the kernel performs normal asynchronous I/O and notifies the task with a signal or message when the I/O request is complete.

The IOInfo structure must be fully initialized before calling this function. You can use the ioi_User field of the IOInfo structure to contain whatever you want. This is a useful place to store a pointer to contextual data that needs to be associated with the I/O request. If you use message-based notification for your I/O requests, the msg_DataSize field of the notification messages will contain the value of ioi_User from the IOInfo structure.

Arguments

ior
The item number of the IOReq structure for the request. This structure is normally created by calling CreateIOReq().
ioiP
A pointer to an IOInfo structure.

Return Value

The procedure returns 1 if the I/O was completed immediately or 0 if the I/O request is still in progress (the task will be notified with either a signal or message when the request is complete, depending on what you specified when you called CreateIOReq()). It returns an error code (a negative value) if an error occurs. Possible error codes include:

BADITEM
The ior argument does not specify an IOReq.
NOTOWNER
The I/O request specified by the ior argument is not owned by this task.
ER_IONotDone
The I/O request is already in progress.
BADPTR
A pointer is invalid: Either the IOInfo structure specified by the ioiP argument is not entirely within the task's memory, the IOInfo receive buffer (specified by the ioi_Recv field in the IOInfo structure) is not entirely within the task's memory, or the IOInfo send buffer (specified by the ioi_Send field in the IOInfo structure) is not in legal memory.
BADIOARG
One or more reserved I/O flags are set (either reserved flags in the ioi_Flags field of the IOInfo structure or any of the flags in the ioi_Flags2 field of the IOInfo structure).
BADUNIT
The unit specified by the ioi_Unit field of the IOInfo structure is not supported by this device.
If quick I/O occurs, the IO_QUICK flag is set in the io_Flags field of the IOReq structure.

If the ior and ioiP arguments were valid but an error occurred during the I/O operation, an error code is returned in the io_Error field of the IOReq structure. If SendIO() returns 0 and a error occurs during I/O, the IOReq is returned as if it were completed, and it contains the error code in io_Error of the IOReq structure.

Implementation

SWI implemented in kernel folio V20.

Associated Files

io.h
ANSI C Prototype

Caveats

SendIO() returns only BADITEM, NOTOWNER, and ER_IONotDone. All other errors codes are returned in the io_Error field of the IOReq.

See Also

AbortIO(), CheckIO(), DoIO(), WaitIO()