.\" $OpenBSD: mio_open.3,v 1.18 2018/12/18 20:37:27 jmc Exp $
.\"
.\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: December 18 2018 $
.Dt MIO_OPEN 3
.Os
.Sh NAME
.Nm mio_open ,
.Nm mio_close ,
.Nm mio_read ,
.Nm mio_write ,
.Nm mio_nfds ,
.Nm mio_pollfd ,
.Nm mio_revents ,
.Nm mio_eof
.Nd sndio interface to MIDI streams
.Sh 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"
.Sh DESCRIPTION
The
.Nm sndio
library allows user processes to access
.Xr midi 4
hardware and
.Xr sndiod 8
MIDI thru boxes and control ports in a uniform way.
.Ss 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
.Ar hdl
argument of most other functions.
The
.Ar name
parameter gives the device string discussed in
.Xr 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
.Ev MIDIDEVICE
environment variable.
.Pp
The
.Ar mode
parameter gives the direction of the stream.
The following are supported:
.Bl -tag -width "MIO_OUT | MIO_IN"
.It MIO_OUT
The stream is output-only; data written to the stream will be sent
to the hardware or other programs.
.It MIO_IN
The stream is input-only; received data from the hardware or
other programs must be read from the stream.
.It MIO_IN | MIO_OUT
The stream sends and receives data.
This mode should be used rather than calling
.Fn mio_open
twice.
.El
.Pp
If the
.Ar 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.
.Pp
The
.Fn mio_close
function closes the stream and frees all allocated resources
associated with the
.Nm libsndio
handle.
.Ss 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
.Ar nbytes
bytes at the
.Ar addr
location.
Unless the
.Ar nbio_flag
flag is set, it will block until data becomes available and
will return zero only on error.
.Pp
When output mode is selected, the
.Fn mio_write
function can be called to provide data to transmit.
Unless the
.Ar nbio_flag
is set,
.Fn mio_write
will block until the requested amount of data is written.
.Ss Non-blocking mode operation
If the
.Ar 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.
.Pp
To avoid busy loops when non-blocking mode is used, the
.Xr 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
.Ar pfd
of
.Va pollfd
structures for use with
.Xr poll 2 .
The optimal size of the
.Ar pfd
array, which the caller must pre-allocate, is provided by the
.Fn mio_nfds
function.
.Pp
.Xr poll 2
will sleep until any of the
.Ar events
requested with
.Fn mio_pollfd
have occurred.
Events are represented as a bit-mask of
.Va POLLIN
and
.Va POLLOUT
constants.
The events which woke up
.Xr poll 2
can be obtained with the
.Fn mio_revents
function.
If
.Va POLLIN
is set,
.Fn mio_read
can be called without blocking.
If
.Va 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 .
.Ss 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
.Va mio_hdl
argument, except
.Fn mio_close
and
.Fn mio_eof ,
stop working (i.e. always return 0).
.Sh RETURN VALUES
The
.Fn mio_open
function returns the newly created handle on success or NULL
on failure.
.Pp
The
.Fn mio_pollfd
function returns the number of
.Va pollfd
structures filled.
The
.Fn mio_nfds
function returns the number of
.Va pollfd
structures the caller must preallocate in order to be sure
that
.Fn mio_pollfd
will never overrun.
.Pp
The
.Fn mio_revents
function returns the bit-mask set by
.Xr poll 2
in the
.Va pfd
array of
.Va pollfd
structures.
.Pp
The
.Fn mio_read
and
.Fn mio_write
functions return the number of bytes transferred.
.Pp
The
.Fn mio_eof
function returns 0 if there's no pending error, and a non-zero
value if there's an error.
.Sh ENVIRONMENT
.Bl -tag -width "SNDIO_DEBUGXXX" -compact
.It Ev SNDIO_DEBUG
The debug level:
may be a value between 0 and 2.
.El
.Sh SEE ALSO
.Xr poll 2 ,
.Xr midi 4 ,
.Xr sndio 7 ,
.Xr sndiod 8
.Sh HISTORY
These functions first appeared in
.Ox 4.7 .
.Sh AUTHORS
.An Alexandre Ratchov Aq Mt ratchov@openbsd.org