Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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  re-
     sources associated with the libsndio handle.

   Sending and receiving data
     When  input mode is selected, the mio_read() function must be called to re-
     trieve received data; it must be called often enough to ensure that  inter-
     nal  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 con-
     stants.  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 con-
     nections) 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 work-
     ing (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 trans-
     ferred.

     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>

FreeBSD ports 15.quarterly	   $Mdocdate$			     MIO_OPEN(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mio_revents&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help