Man page - mio_pollfd(3)
Packages contains this manual
- sio_setvol(3)
- sio_eof(3)
- mio_pollfd(3)
- sio_setpar(3)
- sioctl_onval(3)
- mio_read(3)
- sio_open(3)
- sio_stop(3)
- mio_nfds(3)
- sioctl_setval(3)
- sioctl_eof(3)
- sio_onvol(3)
- sio_pollfd(3)
- sio_getcap(3)
- sio_close(3)
- sioctl_nfds(3)
- sioctl_revents(3)
- sio_start(3)
- sioctl_open(3)
- sioctl_ondesc(3)
- sio_nfds(3)
- mio_write(3)
- sio_write(3)
- sio_revents(3)
- mio_revents(3)
- sioctl_pollfd(3)
- sio_read(3)
- mio_close(3)
- sio_getpar(3)
- mio_open(3)
- sio_initpar(3)
- sio_onmove(3)
- sioctl_close(3)
- mio_eof(3)
apt-get install libsndio-dev
Manual
MIO_OPEN (3) Library Functions Manual MIO_OPEN (3)
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)