MIO_OPEN
Section: C Library Functions (3)
Index
Return to Main Contents
BSD mandoc
NAME
mio_open
mio_close
mio_read
mio_write
mio_nfds
mio_pollfd
mio_revents
mio_eof
- sndio interface to MIDI streams
SYNOPSIS
In sndio.h
Ft struct mio_hdl *
Fn mio_open const char *name unsigned int mode int nbio_flag
Ft void
Fn mio_close struct mio_hdl *hdl
Ft size_t
Fn mio_read struct mio_hdl *hdl void *addr size_t nbytes
Ft size_t
Fn mio_write struct mio_hdl *hdl const void *addr size_t nbytes
Ft int
Fn mio_nfds struct mio_hdl *hdl
Ft int
Fn mio_pollfd struct mio_hdl *hdl struct pollfd *pfd int events
Ft int
Fn mio_revents struct mio_hdl *hdl struct pollfd *pfd
Ft int
Fn mio_eof struct mio_hdl *hdl
DESCRIPTION
The
sndio
library allows user processes to access
midi(4)
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
Fn mio_open
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:
- MIO_OUT
-
The stream is output-only; data written to the stream will be sent
to the hardware or other programs.
- MIO_IN
-
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 calling
Fn mio_open
twice.
If the
nbio_flag
argument is true (i.e. non-zero), then the
Fn mio_read
and
Fn mio_write
functions (see below) will be non-blocking.
The
Fn mio_close
function closes the stream and frees all allocated resources
associated with the
libsndio
handle.
Sending and receiving data
When input mode is selected, the
Fn 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
Fn mio_write
function can be called to provide data to transmit.
Unless the
nbio_flag
is set,
Fn mio_write
will block until the requested amount of data is written.
Non-blocking mode operation
If the
nbio_flag
is set on
Fn mio_open ,
then the
Fn mio_read
and
Fn mio_write
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
poll(2)
system call can be used to check if data can be
read from or written to the stream.
The
Fn mio_pollfd
function prepares the array
pfd
of
pollfd
structures for use with
poll(2).
The optimal size of the
pfd
array, which the caller must pre-allocate, is provided by the
Fn mio_nfds
function.
poll(2)
will sleep until any of the
events
requested with
Fn mio_pollfd
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
Fn mio_revents
function.
If
POLLIN
is set,
Fn mio_read
can be called without blocking.
If
POLLOUT
is set,
Fn mio_write
can be called without blocking.
POLLHUP may be set if an error occurs, even if
it is not requested with
Fn mio_pollfd .
Error handling
Errors related to the MIDI subsystem
(like hardware errors or dropped connections) and
programming errors (such as a call to
Fn mio_read
on a play-only stream) are considered fatal.
Once an error occurs, all functions which take a
mio_hdl
argument, except
Fn mio_close
and
Fn mio_eof ,
stop working (i.e. always return 0).
RETURN VALUES
The
Fn mio_open
function returns the newly created handle on success or NULL
on failure.
The
Fn mio_pollfd
function returns the number of
pollfd
structures filled.
The
Fn mio_nfds
function returns the number of
pollfd
structures the caller must preallocate in order to be sure
that
Fn mio_pollfd
will never overrun.
The
Fn mio_revents
function returns the bit-mask set by
poll(2)
in the
pfd
array of
pollfd
structures.
The
Fn mio_read
and
Fn mio_write
functions return the number of bytes transferred.
The
Fn mio_eof
function returns 0 if there's no pending error, and a non-zero
value if there's an error.
ENVIRONMENT
- SNDIO_DEBUG
-
The debug level:
may be a value between 0 and 2.
SEE ALSO
poll(2),
midi(4),
sndio(7),
sndiod(8)
HISTORY
These functions first appeared in
Ox 4.7 .
AUTHORS
An Alexandre Ratchov Aq Mt ratchov@openbsd.org
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Opening and closing a MIDI stream
-
- Sending and receiving data
-
- Non-blocking mode operation
-
- Error handling
-
- RETURN VALUES
-
- ENVIRONMENT
-
- SEE ALSO
-
- HISTORY
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 05:01:05 GMT, March 29, 2024