1*18bc0c2fSjmc.\" $OpenBSD: mio_open.3,v 1.18 2018/12/18 20:37:27 jmc Exp $ 26efede29Sratchov.\" 36efede29Sratchov.\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org> 46efede29Sratchov.\" 56efede29Sratchov.\" Permission to use, copy, modify, and distribute this software for any 66efede29Sratchov.\" purpose with or without fee is hereby granted, provided that the above 76efede29Sratchov.\" copyright notice and this permission notice appear in all copies. 86efede29Sratchov.\" 96efede29Sratchov.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 106efede29Sratchov.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 116efede29Sratchov.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 126efede29Sratchov.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 136efede29Sratchov.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 146efede29Sratchov.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 156efede29Sratchov.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 166efede29Sratchov.\" 17*18bc0c2fSjmc.Dd $Mdocdate: December 18 2018 $ 186efede29Sratchov.Dt MIO_OPEN 3 196efede29Sratchov.Os 206efede29Sratchov.Sh NAME 216efede29Sratchov.Nm mio_open , 226efede29Sratchov.Nm mio_close , 236efede29Sratchov.Nm mio_read , 246efede29Sratchov.Nm mio_write , 256efede29Sratchov.Nm mio_nfds , 266efede29Sratchov.Nm mio_pollfd , 276efede29Sratchov.Nm mio_revents , 286efede29Sratchov.Nm mio_eof 290064b033Sratchov.Nd sndio interface to MIDI streams 306efede29Sratchov.Sh SYNOPSIS 3186f9d4cdStedu.In sndio.h 326efede29Sratchov.Ft "struct mio_hdl *" 335dfee228Sschwarze.Fn mio_open "const char *name" "unsigned int mode" "int nbio_flag" 346efede29Sratchov.Ft "void" 355dfee228Sschwarze.Fn mio_close "struct mio_hdl *hdl" 366efede29Sratchov.Ft "size_t" 375dfee228Sschwarze.Fn mio_read "struct mio_hdl *hdl" "void *addr" "size_t nbytes" 386efede29Sratchov.Ft "size_t" 395dfee228Sschwarze.Fn mio_write "struct mio_hdl *hdl" "const void *addr" "size_t nbytes" 406efede29Sratchov.Ft "int" 415dfee228Sschwarze.Fn mio_nfds "struct mio_hdl *hdl" 426efede29Sratchov.Ft "int" 435dfee228Sschwarze.Fn mio_pollfd "struct mio_hdl *hdl" "struct pollfd *pfd" "int events" 446efede29Sratchov.Ft "int" 455dfee228Sschwarze.Fn mio_revents "struct mio_hdl *hdl" "struct pollfd *pfd" 466efede29Sratchov.Ft "int" 475dfee228Sschwarze.Fn mio_eof "struct mio_hdl *hdl" 486efede29Sratchov.Sh DESCRIPTION 496efede29SratchovThe 506efede29Sratchov.Nm sndio 516efede29Sratchovlibrary allows user processes to access 526efede29Sratchov.Xr midi 4 536efede29Sratchovhardware and 543f2e611aSratchov.Xr sndiod 8 558825335aSratchovMIDI thru boxes and control ports in a uniform way. 56*18bc0c2fSjmc.Ss Opening and closing a MIDI stream 576efede29SratchovFirst the application must call the 586efede29Sratchov.Fn mio_open 596efede29Sratchovfunction to obtain a handle representing the newly created stream; 606efede29Sratchovlater it will be passed as the 616efede29Sratchov.Ar hdl 626efede29Sratchovargument of most other functions. 636efede29SratchovThe 646efede29Sratchov.Ar name 656efede29Sratchovparameter gives the device string discussed in 666efede29Sratchov.Xr sndio 7 . 676efede29SratchovIf the program is using a single device and is providing no device chooser, 689f9aa69fSratchovit should be set to MIO_PORTANY to allow the user to select it using the 696efede29Sratchov.Ev MIDIDEVICE 706efede29Sratchovenvironment variable. 716efede29Sratchov.Pp 726efede29SratchovThe 736efede29Sratchov.Ar mode 746efede29Sratchovparameter gives the direction of the stream. 756efede29SratchovThe following are supported: 766efede29Sratchov.Bl -tag -width "MIO_OUT | MIO_IN" 776efede29Sratchov.It MIO_OUT 786efede29SratchovThe stream is output-only; data written to the stream will be sent 796efede29Sratchovto the hardware or other programs. 806efede29Sratchov.It MIO_IN 816efede29SratchovThe stream is input-only; received data from the hardware or 826efede29Sratchovother programs must be read from the stream. 836efede29Sratchov.It MIO_IN | MIO_OUT 846efede29SratchovThe stream sends and receives data. 8585e7b1feSratchovThis mode should be used rather than calling 8685e7b1feSratchov.Fn mio_open 8785e7b1feSratchovtwice. 886efede29Sratchov.El 896efede29Sratchov.Pp 906efede29SratchovIf the 916efede29Sratchov.Ar nbio_flag 926efede29Sratchovargument is true (i.e. non-zero), then the 936efede29Sratchov.Fn mio_read 946efede29Sratchovand 956efede29Sratchov.Fn mio_write 966efede29Sratchovfunctions (see below) will be non-blocking. 976efede29Sratchov.Pp 986efede29SratchovThe 996efede29Sratchov.Fn mio_close 1006efede29Sratchovfunction closes the stream and frees all allocated resources 1016efede29Sratchovassociated with the 1026efede29Sratchov.Nm libsndio 1036efede29Sratchovhandle. 1046efede29Sratchov.Ss Sending and receiving data 1056efede29SratchovWhen input mode is selected, the 1066efede29Sratchov.Fn mio_read 1076efede29Sratchovfunction must be called to retrieve received data; it must be called 1086efede29Sratchovoften enough to ensure that internal buffers will not overrun. 1096efede29SratchovIt will store at most 1106efede29Sratchov.Ar nbytes 1116efede29Sratchovbytes at the 1126efede29Sratchov.Ar addr 11357838383Sstsplocation. 1146efede29SratchovUnless the 1156efede29Sratchov.Ar nbio_flag 1166efede29Sratchovflag is set, it will block until data becomes available and 1176efede29Sratchovwill return zero only on error. 1186efede29Sratchov.Pp 1196efede29SratchovWhen output mode is selected, the 1206efede29Sratchov.Fn mio_write 1216efede29Sratchovfunction can be called to provide data to transmit. 1226efede29SratchovUnless the 1236efede29Sratchov.Ar nbio_flag 1246efede29Sratchovis set, 1256efede29Sratchov.Fn mio_write 1266efede29Sratchovwill block until the requested amount of data is written. 1276efede29Sratchov.Ss Non-blocking mode operation 1286efede29SratchovIf the 1296efede29Sratchov.Ar nbio_flag 1306efede29Sratchovis set on 1316efede29Sratchov.Fn mio_open , 1326efede29Sratchovthen the 1336efede29Sratchov.Fn mio_read 1346efede29Sratchovand 1356efede29Sratchov.Fn mio_write 1366efede29Sratchovfunctions will never block; if no data is available, they will 1376efede29Sratchovreturn zero immediately. 1386efede29Sratchov.Pp 1396efede29SratchovTo avoid busy loops when non-blocking mode is used, the 1406efede29Sratchov.Xr poll 2 1416efede29Sratchovsystem call can be used to check if data can be 1426efede29Sratchovread from or written to the stream. 1436efede29SratchovThe 1446efede29Sratchov.Fn mio_pollfd 145f7e031c0Sstspfunction prepares the array 1466efede29Sratchov.Ar pfd 1476efede29Sratchovof 1486efede29Sratchov.Va pollfd 149f7e031c0Sstspstructures for use with 150f7e031c0Sstsp.Xr poll 2 . 151f7e031c0SstspThe optimal size of the 152f7e031c0Sstsp.Ar pfd 153f7e031c0Sstsparray, which the caller must pre-allocate, is provided by the 154f7e031c0Sstsp.Fn mio_nfds 155f7e031c0Sstspfunction. 156f7e031c0Sstsp.Pp 157f7e031c0Sstsp.Xr poll 2 158f7e031c0Sstspwill sleep until any of the 159f7e031c0Sstsp.Ar events 160f7e031c0Sstsprequested with 161f7e031c0Sstsp.Fn mio_pollfd 162f7e031c0Sstsphave occurred. 163f7e031c0SstspEvents are represented as a bit-mask of 1646efede29Sratchov.Va POLLIN 1656efede29Sratchovand 1666efede29Sratchov.Va POLLOUT 167f7e031c0Sstspconstants. 168f7e031c0SstspThe events which woke up 1696efede29Sratchov.Xr poll 2 170f7e031c0Sstspcan be obtained with the 171f7e031c0Sstsp.Fn mio_revents 172f7e031c0Sstspfunction. 1736efede29SratchovIf 1746efede29Sratchov.Va POLLIN 1756efede29Sratchovis set, 1766efede29Sratchov.Fn mio_read 1776efede29Sratchovcan be called without blocking. 1786efede29SratchovIf 1796efede29Sratchov.Va POLLOUT 1806efede29Sratchovis set, 1816efede29Sratchov.Fn mio_write 1826efede29Sratchovcan be called without blocking. 1836efede29SratchovPOLLHUP may be set if an error occurs, even if 184f7e031c0Sstspit is not requested with 1856efede29Sratchov.Fn mio_pollfd . 1866efede29Sratchov.Ss Error handling 1876efede29SratchovErrors related to the MIDI subsystem 1886efede29Sratchov(like hardware errors or dropped connections) and 1896efede29Sratchovprogramming errors (such as a call to 1906efede29Sratchov.Fn mio_read 1916efede29Sratchovon a play-only stream) are considered fatal. 1926efede29SratchovOnce an error occurs, all functions which take a 1936efede29Sratchov.Va mio_hdl 1946efede29Sratchovargument, except 1956efede29Sratchov.Fn mio_close 1966efede29Sratchovand 1976efede29Sratchov.Fn mio_eof , 1986efede29Sratchovstop working (i.e. always return 0). 1996efede29Sratchov.Sh RETURN VALUES 2006efede29SratchovThe 2016efede29Sratchov.Fn mio_open 2026efede29Sratchovfunction returns the newly created handle on success or NULL 2036efede29Sratchovon failure. 204f7e031c0Sstsp.Pp 2056efede29SratchovThe 2066efede29Sratchov.Fn mio_pollfd 20757838383Sstspfunction returns the number of 20857838383Sstsp.Va pollfd 20957838383Sstspstructures filled. 21057838383SstspThe 21157838383Sstsp.Fn mio_nfds 21257838383Sstspfunction returns the number of 21357838383Sstsp.Va pollfd 21457838383Sstspstructures the caller must preallocate in order to be sure 21557838383Sstspthat 21657838383Sstsp.Fn mio_pollfd 21757838383Sstspwill never overrun. 218f7e031c0Sstsp.Pp 21957838383SstspThe 22057838383Sstsp.Fn mio_revents 22157838383Sstspfunction returns the bit-mask set by 22257838383Sstsp.Xr poll 2 22357838383Sstspin the 22457838383Sstsp.Va pfd 22557838383Sstsparray of 22657838383Sstsp.Va pollfd 22757838383Sstspstructures. 228f7e031c0Sstsp.Pp 2296efede29SratchovThe 2306efede29Sratchov.Fn mio_read 2316efede29Sratchovand 2326efede29Sratchov.Fn mio_write 2336efede29Sratchovfunctions return the number of bytes transferred. 234f7e031c0Sstsp.Pp 23557838383SstspThe 23657838383Sstsp.Fn mio_eof 237f7e031c0Sstspfunction returns 0 if there's no pending error, and a non-zero 23857838383Sstspvalue if there's an error. 2396efede29Sratchov.Sh ENVIRONMENT 2408825335aSratchov.Bl -tag -width "SNDIO_DEBUGXXX" -compact 24182bfc72bSratchov.It Ev SNDIO_DEBUG 2426efede29SratchovThe debug level: 2436efede29Sratchovmay be a value between 0 and 2. 2446efede29Sratchov.El 2456efede29Sratchov.Sh SEE ALSO 246f7e031c0Sstsp.Xr poll 2 , 2476efede29Sratchov.Xr midi 4 , 2483f2e611aSratchov.Xr sndio 7 , 2493f2e611aSratchov.Xr sndiod 8 250f273b081Sschwarze.Sh HISTORY 251f273b081SschwarzeThese functions first appeared in 252f273b081Sschwarze.Ox 4.7 . 253f273b081Sschwarze.Sh AUTHORS 254f273b081Sschwarze.An Alexandre Ratchov Aq Mt ratchov@openbsd.org 255