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	 envi-
       ronment 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
       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() func-
       tion.

       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	struc-
       tures 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>

FreeBSD	Ports 14.quarterly	  $Mdocdate$			   MIO_OPEN(3)

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

home | help