MIO_OPEN(3)

💖 MIO_OPEN(3) — Library Functions Manual 💖

okay bestie, so this is the page for the sndio MIDI stream functions, and I'm gonna hold your hand through every single one of them. grab a snack. 🍓

---

✨ NAME ✨

mio_open, mio_close, mio_read, mio_write, mio_nfds, mio_pollfd, mio_revents, mio_eof — the 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 lets your user processes get at midi(4) hardware and sndiod(8) MIDI thru boxes and control ports — all in one uniform way. one API, every MIDI thing, slay. 🔥

🎀 Opening and closing a MIDI stream 🎀

First things first: your app must call mio_open() to get a handle representing the brand-new stream. that handle then gets passed as the hdl argument to basically every other function, it's giving main character energy fr fr.

The name parameter is the device string discussed in sndio(7). If your program is using a single device and isn't providing a device chooser, set it to MIO_PORTANY so the user can pick it with the MIDIDEVICE environment variable. let them choose, it's their moment. 💅

The mode parameter sets the direction of the stream. the supported ones are:

• MIO_OUT — the stream is output-only; whatever you write to it gets sent to the hardware or to other programs. 📤
• MIO_IN — the stream is input-only; data coming in from the hardware or other programs has to be read out of the stream. 📥
• MIO_IN | MIO_OUT — the stream sends and receives data. use this one instead of calling mio_open() twice, bestie, seriously, don't be extra. ✨

If the nbio_flag argument is true (i.e. non-zero), then mio_read() and mio_write() (see below 👇) will be non-blocking.

The mio_close() function closes the stream and frees all allocated resources tied to the libsndio handle. clean up after yourself, icon behaviour. 🫶

🦋 Sending and receiving data 🦋

When input mode is selected, you must call mio_read() to retrieve the received data — and you gotta call it often enough that the internal buffers don't overrun. it stores at most nbytes bytes at the addr location. Unless the nbio_flag flag is set, it will block until data becomes available, and it returns zero only on error. 😭

When output mode is selected, mio_write() can be called to hand over data to transmit. Unless the nbio_flag is set, mio_write() will block until the requested amount of data is written. patient king. 👑

🌸 Non-blocking mode operation 🌸

If nbio_flag is set on mio_open(), then mio_read() and mio_write() will never block; if there's no data available, they return zero immediately. no waiting, no drama.

To avoid busy loops when you're in non-blocking mode, you can use the poll(2) system call to check whether 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). The optimal size of that pfd array — which you, the caller, must pre-allocate — is provided by the mio_nfds() function. do the math first, okay? 🧮

poll(2) will sleep until any of the events requested with mio_pollfd() have occurred. Events are represented as a bit-mask of the POLLIN and POLLOUT constants. The events that actually woke poll(2) up 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 you never requested it with mio_pollfd(). sneaky. 🙈

💀 Error handling 💀

Errors related to the MIDI subsystem (like hardware errors or dropped connections) and programming errors (such as calling mio_read() on a play-only stream) are considered fatal. Once an error occurs, all functions that take a mio_hdl argument stop working (i.e. they always return 0) — with the exception of mio_close() and mio_eof(), which are the only survivors. it's giving apocalypse. 😭

⚠️ fr fr: after a fatal error, don't expect anything else to work. mio_close() and mio_eof() are literally the only ones still picking up the phone. 📞

---

⭐ RETURN VALUES ⭐

• mio_open() — returns the newly created handle on success, or NULL on failure. 🎉
• mio_pollfd() — returns the number of pollfd structures filled.
• mio_nfds() — returns the number of pollfd structures the caller must preallocate so that mio_pollfd() will never overrun.
• mio_revents() — returns the bit-mask set by poll(2) in the pfd array of pollfd structures.
• mio_read() and mio_write() — return the number of bytes transferred.
• mio_eof() — 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. turn it up when things get weird. 🔍

---

👑 SEE ALSO 👑

poll(2), midi(4), sndio(7), sndiod(8)

---

🎀 HISTORY 🎀

These functions first appeared in OpenBSD 4.7. vintage. ✨

---

💖 AUTHORS 💖

Alexandre Ratchov <ratchov@openbsd.org>

---

and that's the whole page bestie, you ate it up 💅 no cap, you're basically a MIDI stream expert now. this was the Debian build of MIO_OPEN(3), tagged $Mdocdate$ in the footer — mwah, go write something iconic with it 🫶🌟🎀