sndio interface to MIDI
struct mio_hdl *
char *name, unsigned int
mio_hdl *hdl, void
mio_hdl *hdl, const void
mio_hdl *hdl, struct
pollfd *pfd, int
mio_hdl *hdl, struct
sndio library allows user processes to
hardware and sndiod(8) MIDI thru boxes and control ports in a uniform way.
Opening and closing a MIDI stream
First the application must call the
function to obtain a handle representing the newly created stream; later it
will be passed as the hdl argument of most other
functions. The name parameter gives the device string
discussed in sndio(7). 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
MIDIDEVICE environment variable.
The mode 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.
- MIO_IN | MIO_OUT
- The stream sends and receives data. This mode should be used rather than
If the nbio_flag argument is
true (i.e. non-zero), then the
mio_write() functions (see below) will be
function closes the stream and frees all allocated resources associated with
Sending and receiving data
When input mode is selected, the
mio_read() 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 nbytes
bytes at the addr location. Unless the
nbio_flag 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
nbio_flag is set,
will block until the requested amount of data is written.
Non-blocking mode operation
If the nbio_flag is set on
mio_open(), then the
functions will never block; if no data is available, they will return zero
To avoid busy loops when non-blocking mode is
used, the poll(2) system call can be used to check if data can be read from or
written to the stream. The
function prepares the array pfd of
pollfd structures for use with
optimal size of the pfd array, which the caller must
pre-allocate, is provided by the
poll(2) will sleep until any of the
events requested with
have occurred. Events are represented as a bit-mask of
POLLIN and POLLOUT constants.
The events which woke up poll(2) can be obtained with the
function. If POLLIN is set,
mio_read() can be called without blocking. If
POLLOUT 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
mio_read() on a play-only stream) are considered
fatal. Once an error occurs, all functions which take a
mio_hdl argument, except
stop working (i.e. always return 0).
mio_open() function returns the newly
created handle on success or NULL on failure.
mio_pollfd() function returns the
number of pollfd structures filled. The
mio_nfds() function returns the number of
pollfd structures the caller must preallocate in order
to be sure that
mio_pollfd() will never overrun.
mio_revents() function returns the
bit-mask set by poll(2) in the pfd array of
mio_write() functions return the number of bytes
mio_eof() 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.
poll(2), midi(4), sndio(7), sndiod(8)
These functions first appeared in OpenBSD 4.7.
Alexandre Ratchov <firstname.lastname@example.org>