Manpages - mio_open.3

The

library allows user processes to access

hardware and

MIDI thru boxes and control ports in a uniform way.

First the application must call the

function to obtain a handle representing the newly created stream; later it will be passed as the

argument of most other functions. The

parameter gives the device string discussed in

If the program is using a single device and is providing no device chooser, it should be set to MIO_PORTANY to allow the user to select it using the

environment variable.

The

parameter gives the direction of the stream. The following are supported:

The stream is output-only; data written to the stream will be sent to the hardware or other programs.

The stream is input-only; received data from the hardware or other programs must be read from the stream.

The stream sends and receives data. This mode should be used rather than calling

twice.

If the

argument is true (i.e. non-zero), then the

and

functions (see below) will be non-blocking.

The

function closes the stream and frees all allocated resources associated with the

handle.

When input mode is selected, the

function must be called to retrieve received data; it must be called often enough to ensure that internal buffers will not overrun. It will store at most

bytes at the

location. Unless the

flag is set, it will block until data becomes available and will return zero only on error.

When output mode is selected, the

function can be called to provide data to transmit. Unless the

is set,

will block until the requested amount of data is written.

If the

is set on

then the

and

functions will never block; if no data is available, they will return zero immediately.

To avoid busy loops when non-blocking mode is used, the

system call can be used to check if data can be read from or written to the stream. The

function prepares the array

of

structures for use with

The optimal size of the

array, which the caller must pre-allocate, is provided by the

function.

will sleep until any of the

requested with

have occurred. Events are represented as a bit-mask of

and

constants. The events which woke up

can be obtained with the

function. If

is set,

can be called without blocking. If

is set,

can be called without blocking. POLLHUP may be set if an error occurs, even if it is not requested with

Errors related to the MIDI subsystem (like hardware errors or dropped connections) and programming errors (such as a call to

on a play-only stream) are considered fatal. Once an error occurs, all functions which take a

argument, except

and

stop working (i.e. always return 0).

The

function returns the newly created handle on success or NULL on failure.

The

function returns the number of

structures filled. The

function returns the number of

structures the caller must preallocate in order to be sure that

will never overrun.

The

function returns the bit-mask set by

in the

array of

structures.

The

and

functions return the number of bytes transferred.

The

function returns 0 if there’s no pending error, and a non-zero value if there’s an error.

The debug level: may be a value between 0 and 2.

These functions first appeared in