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) 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 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
                         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) 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).  The optimal size of the pfd array, which the caller must  pre-allocate,
       is provided by the mio_nfds() function.

       poll(2)  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)  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) 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), midi(4), sndio(7), sndiod(8)

HISTORY

       These functions first appeared in OpenBSD 4.7.

AUTHORS

       Alexandre Ratchov <ratchov@openbsd.org>

Debian                                             $Mdocdate$                                        MIO_OPEN(3)