MIO\_OPEN(3) Library Functions Manual MIO\_OPEN(3) # [NAME](#NAME) `mio_open`, `mio_close`, `mio_read`, `mio_write`, `mio_nfds`, `mio_pollfd`, `mio_revents`, `mio_eof` — sndio interface to MIDI streams # [SYNOPSIS](#SYNOPSIS) `#include ` `struct mio_hdl *` `mio_open`(`const char *name`, `unsigned int mode`, `int nbio_flag`); `void` `mio_close`(`struct mio_hdl *hdl`); `size_t` `mio_read`(`struct mio_hdl *hdl`, `void *addr`, `size_t nbytes`); `size_t` `mio_write`(`struct mio_hdl *hdl`, `const void *addr`, `size_t nbytes`); `int` `mio_nfds`(`struct mio_hdl *hdl`); `int` `mio_pollfd`(`struct mio_hdl *hdl`, `struct pollfd *pfd`, `int events`); `int` `mio_revents`(`struct mio_hdl *hdl`, `struct pollfd *pfd`); `int` `mio_eof`(`struct mio_hdl *hdl`); # [DESCRIPTION](#DESCRIPTION) The `sndio` library allows user processes to access [midi(4)](/man/os/sndio/midi.4) hardware and [sndiod(8)](/man/os/sndio/sndiod.8) MIDI thru boxes and control ports in a uniform way. ## [Opening and closing a MIDI stream](#Opening_and_closing_a_MIDI_stream) First the application must call the [`mio_open`](#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)](/man/os/sndio/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 [`mio_open`](#mio_open~2)() twice. If the `nbio_flag` argument is true (i.e. non-zero), then the [`mio_read`](#mio_read)() and `mio_write`() functions (see below) will be non-blocking. The [`mio_close`](#mio_close)() function closes the stream and frees all allocated resources associated with the `libsndio` handle. ## [Sending and receiving data](#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 [`mio_write`](#mio_write)() function can be called to provide data to transmit. Unless the `nbio_flag` is set, `mio_write`() will block until the requested amount of data is written. ## [Non-blocking mode operation](#Non-blocking_mode_operation) If the `nbio_flag` is set on `mio_open`(), then the `mio_read`() and `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)](/man/os/sndio/poll.2) system call can be used to check if data can be read from or written to the stream. The [`mio_pollfd`](#mio_pollfd)() function prepares the array `pfd` of `pollfd` structures for use with [poll(2)](/man/os/sndio/poll.2). The optimal size of the `pfd` array, which the caller must pre-allocate, is provided by the [`mio_nfds`](#mio_nfds)() function. [poll(2)](/man/os/sndio/poll.2) will sleep until any of the `events` requested with [`mio_pollfd`](#mio_pollfd~2)() have occurred. Events are represented as a bit-mask of `POLLIN` and `POLLOUT` constants. The events which woke up [poll(2)](/man/os/sndio/poll.2) can be obtained with the [`mio_revents`](#mio_revents)() function. If `POLLIN` is set, `mio_read`() can be called without blocking. If `POLLOUT` is set, `mio_write`() can be called without blocking. POLLHUP may be set if an error occurs, even if it is not requested with `mio_pollfd`(). ## [Error handling](#Error_handling) 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 `mio_close`() and [`mio_eof`](#mio_eof)(), stop working (i.e. always return 0). # [RETURN VALUES](#RETURN_VALUES) The `mio_open`() function returns the newly created handle on success or NULL on failure. The `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. The `mio_revents`() function returns the bit-mask set by [poll(2)](/man/os/sndio/poll.2) in the `pfd` array of `pollfd` structures. The `mio_read`() and `mio_write`() functions return the number of bytes transferred. The `mio_eof`() function returns 0 if there's no pending error, and a non-zero value if there's an error. # [ENVIRONMENT](#ENVIRONMENT) [`SNDIO_DEBUG`](#SNDIO_DEBUG) The debug level: may be a value between 0 and 2. # [SEE ALSO](#SEE_ALSO) [poll(2)](/man/os/sndio/poll.2), [midi(4)](/man/os/sndio/midi.4), [sndio(7)](/man/os/sndio/sndio.7), [sndiod(8)](/man/os/sndio/sndiod.8) # [HISTORY](#HISTORY) These functions first appeared in OpenBSD 4.7. # [AUTHORS](#AUTHORS) Alexandre Ratchov <[ratchov@openbsd.org](mailto:ratchov@openbsd.org)> Linux 4.19.0-gvisor --- Document: mio_pollfd(3) from sndio 1.10.0-r10 (Chainguard OS) Source: https://github.com/ratchov/sndio