---
name: "mio_open"
section: "3"
platform: "linux"
package: "sndio"
version: "1.10.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/mio_open"
---

# mio\_open(3)

sndio interface to MIDI streams

## NAME

**mio\_open**, **mio\_close**, **mio\_read**, **mio\_write**, **mio\_nfds**, **mio\_pollfd**, **mio\_revents**, **mio\_eof** – sndio interface to MIDI streams

## SYNOPSIS

**#include \<sndio.h\>**

*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

The **sndio** library allows user processes to access [midi(4)](/midi/4.md) hardware and [sndiod(8)](/sndiod/8.md) MIDI thru boxes and control ports in a uniform way.

### Opening and closing a MIDI stream

First the application must call the **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)](/sndio/7.md). 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**() twice.

If the *nbio\_flag* argument is true (i.e. non-zero), then the **mio\_read**() and **mio\_write**() functions (see below) will be non-blocking.

The **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 **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**() 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

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)](/poll/2.md) system call can be used to check if data can be read from or written to the stream. The **mio\_pollfd**() function prepares the array *pfd* of *pollfd* structures for use with [poll(2)](/poll/2.md). The optimal size of the *pfd* array, which the caller must pre-allocate, is provided by the **mio\_nfds**() function.

[poll(2)](/poll/2.md) will sleep until any of the *events* requested with **mio\_pollfd**() have occurred. Events are represented as a bit-mask of *POLLIN* and *POLLOUT* constants. The events which woke up [poll(2)](/poll/2.md) can be obtained with the **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

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**(), stop working (i.e. always return 0).

## 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)](/poll/2.md) 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

- SNDIO\_DEBUG

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

## SEE ALSO

[poll(2)](/poll/2.md), [midi(4)](/midi/4.md), [sndio(7)](/sndio/7.md), [sndiod(8)](/sndiod/8.md)

## HISTORY

These functions first appeared in OpenBSD 4.7.

## AUTHORS

Alexandre Ratchov ⟨*ratchov@openbsd.org*⟩