1*4aaef610Sratchov.\" $OpenBSD: sioctl_open.3,v 1.14 2024/05/24 15:10:27 ratchov Exp $ 2d07fece6Sratchov.\" 3bf6deef9Sratchov.\" Copyright (c) 2011-2020 Alexandre Ratchov <alex@caoua.org> 4d07fece6Sratchov.\" 5d07fece6Sratchov.\" Permission to use, copy, modify, and distribute this software for any 6d07fece6Sratchov.\" purpose with or without fee is hereby granted, provided that the above 7d07fece6Sratchov.\" copyright notice and this permission notice appear in all copies. 8d07fece6Sratchov.\" 9d07fece6Sratchov.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10d07fece6Sratchov.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11d07fece6Sratchov.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12d07fece6Sratchov.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13d07fece6Sratchov.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14d07fece6Sratchov.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15d07fece6Sratchov.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16d07fece6Sratchov.\" 17*4aaef610Sratchov.Dd $Mdocdate: May 24 2024 $ 18bf6deef9Sratchov.Dt SIOCTL_OPEN 3 19d07fece6Sratchov.Os 20d07fece6Sratchov.Sh NAME 21d07fece6Sratchov.Nm sioctl_open , 22d07fece6Sratchov.Nm sioctl_close , 23d07fece6Sratchov.Nm sioctl_ondesc , 24d07fece6Sratchov.Nm sioctl_onval , 25d07fece6Sratchov.Nm sioctl_setval , 26d07fece6Sratchov.Nm sioctl_nfds , 27d07fece6Sratchov.Nm sioctl_pollfd , 28d07fece6Sratchov.Nm sioctl_eof 29d07fece6Sratchov.Nd interface to audio parameters 30d07fece6Sratchov.Sh SYNOPSIS 31d07fece6Sratchov.Fd #include <sndio.h> 32d03c2a24Sschwarze.Ft struct sioctl_hdl * 33d03c2a24Sschwarze.Fo sioctl_open 34d03c2a24Sschwarze.Fa "const char *name" 35d03c2a24Sschwarze.Fa "unsigned int mode" 36d03c2a24Sschwarze.Fa "int nbio_flag" 37d03c2a24Sschwarze.Fc 38d03c2a24Sschwarze.Ft void 39d03c2a24Sschwarze.Fo sioctl_close 40d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 41d03c2a24Sschwarze.Fc 42d03c2a24Sschwarze.Ft int 43d03c2a24Sschwarze.Fo sioctl_ondesc 44d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 45d03c2a24Sschwarze.Fa "void (*cb)(void *arg, struct sioctl_desc *desc, int val)" 46d03c2a24Sschwarze.Fa "void *arg" 47d03c2a24Sschwarze.Fc 4889f6be33Sratchov.Ft int 49d03c2a24Sschwarze.Fo sioctl_onval 50d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 51d03c2a24Sschwarze.Fa "void (*cb)(void *arg, unsigned int addr, unsigned int val)" 52d03c2a24Sschwarze.Fa "void *arg" 53d03c2a24Sschwarze.Fc 54d03c2a24Sschwarze.Ft int 55d03c2a24Sschwarze.Fo sioctl_setval 56d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 57d03c2a24Sschwarze.Fa "unsigned int addr" 58d03c2a24Sschwarze.Fa "unsigned int val" 59d03c2a24Sschwarze.Fc 60d03c2a24Sschwarze.Ft int 61d03c2a24Sschwarze.Fo sioctl_nfds 62d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 63d03c2a24Sschwarze.Fc 64d03c2a24Sschwarze.Ft int 65d03c2a24Sschwarze.Fo sioctl_pollfd 66d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 67d03c2a24Sschwarze.Fa "struct pollfd *pfd" 68d03c2a24Sschwarze.Fa "int events" 69d03c2a24Sschwarze.Fc 70d03c2a24Sschwarze.Ft int 71d03c2a24Sschwarze.Fo sioctl_revents 72d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 73d03c2a24Sschwarze.Fa "struct pollfd *pfd" 74d03c2a24Sschwarze.Fc 75d03c2a24Sschwarze.Ft int 76d03c2a24Sschwarze.Fo sioctl_eof 77d03c2a24Sschwarze.Fa "struct sioctl_hdl *hdl" 78d03c2a24Sschwarze.Fc 79d07fece6Sratchov.Sh DESCRIPTION 80d07fece6SratchovAudio devices may expose a number of controls, like the playback volume control. 81d07fece6SratchovEach control has an integer 82d07fece6Sratchov.Em address 83d07fece6Sratchovand an integer 84d07fece6Sratchov.Em value . 85e04d4d7cSschwarzeSome values are boolean and can only be switched to either 0 (off) or 1 (on). 86d07fece6SratchovAny control may be changed by submitting 87d07fece6Sratchova new value to its address. 88d07fece6SratchovWhen values change, asynchronous notifications are sent. 89d07fece6Sratchov.Pp 9064aa3d5eSschwarzeControl descriptions are available, allowing them to be grouped and 9164aa3d5eSschwarzerepresented in a human readable form. 928fe8d172Sschwarze.Ss Opening and closing the control device 93d07fece6SratchovFirst the application must call the 94d07fece6Sratchov.Fn sioctl_open 95d07fece6Sratchovfunction to obtain a handle 96d07fece6Sratchovthat will be passed as the 978fe8d172Sschwarze.Fa hdl 98d07fece6Sratchovargument to other functions. 99d07fece6Sratchov.Pp 100d07fece6SratchovThe 1018fe8d172Sschwarze.Fa name 102d07fece6Sratchovparameter gives the device string discussed in 103d07fece6Sratchov.Xr sndio 7 . 1048ed177d7SfeinererIn most cases it should be set to SIO_DEVANY to allow 105d07fece6Sratchovthe user to select it using the 106d07fece6Sratchov.Ev AUDIODEVICE 107d07fece6Sratchovenvironment variable. 108d07fece6SratchovThe 1098fe8d172Sschwarze.Fa mode 1108fe8d172Sschwarzeparameter is a bitmap of the 1118fe8d172Sschwarze.Dv SIOCTL_READ 1128fe8d172Sschwarzeand 1138fe8d172Sschwarze.Dv SIOCTL_WRITE 1148fe8d172Sschwarzeconstants indicating whether control values can be read and 115d07fece6Sratchovmodified respectively. 116d07fece6Sratchov.Pp 117d07fece6SratchovIf the 1188fe8d172Sschwarze.Fa nbio_flag 119d07fece6Sratchovargument is 1, then the 120d07fece6Sratchov.Fn sioctl_setval 121d07fece6Sratchovfunction (see below) may fail instead of blocking and 122d07fece6Sratchovthe 123d07fece6Sratchov.Fn sioctl_ondesc 124d07fece6Sratchovfunction doesn't block. 125d07fece6Sratchov.Pp 126d07fece6SratchovThe 127d07fece6Sratchov.Fn sioctl_close 128d07fece6Sratchovfunction closes the control device and frees any allocated resources 129d07fece6Sratchovassociated with the handle. 13064aa3d5eSschwarze.Ss Control descriptions 131d07fece6SratchovThe 132d07fece6Sratchov.Fn sioctl_ondesc 133d07fece6Sratchovfunction can be used to obtain the description of all available controls 134d07fece6Sratchovand their initial values. 13564aa3d5eSschwarzeIt registers a callback function that is immediately invoked for all 136d07fece6Sratchovcontrols. 13764aa3d5eSschwarzeIt is called once with a 13864aa3d5eSschwarze.Dv NULL 13964aa3d5eSschwarzeargument to indicate that the full 140d07fece6Sratchovdescription was sent and that the caller has a consistent 14164aa3d5eSschwarzerepresentation of the control set. 142d07fece6Sratchov.Pp 14364aa3d5eSschwarzeThen, whenever a control description changes, the callback is 14464aa3d5eSschwarzeinvoked with the updated information followed by a call with a 14564aa3d5eSschwarze.Dv NULL 146d07fece6Sratchovargument. 147d07fece6Sratchov.Pp 148d07fece6SratchovControls are described by the 1498fe8d172Sschwarze.Vt sioctl_desc 1504794a64cSjmcstructure as follows: 151d07fece6Sratchov.Bd -literal 152d07fece6Sratchovstruct sioctl_node { 153d07fece6Sratchov char name[SIOCTL_NAMEMAX]; /* ex. "spkr" */ 154d07fece6Sratchov int unit; /* optional number or -1 */ 155d07fece6Sratchov}; 156d07fece6Sratchov 157d07fece6Sratchovstruct sioctl_desc { 158d07fece6Sratchov unsigned int addr; /* control address */ 159d07fece6Sratchov#define SIOCTL_NONE 0 /* deleted */ 16099f201b8Sratchov#define SIOCTL_NUM 2 /* integer in the maxval range */ 161e04d4d7cSschwarze#define SIOCTL_SW 3 /* on/off switch (1 or 0) */ 162d07fece6Sratchov#define SIOCTL_VEC 4 /* number, element of vector */ 163d07fece6Sratchov#define SIOCTL_LIST 5 /* switch, element of a list */ 16449f67e12Sratchov#define SIOCTL_SEL 6 /* element of a selector */ 165d07fece6Sratchov unsigned int type; /* one of above */ 166d07fece6Sratchov char func[SIOCTL_NAMEMAX]; /* function name, ex. "level" */ 167d07fece6Sratchov char group[SIOCTL_NAMEMAX]; /* group this control belongs to */ 168d07fece6Sratchov struct sioctl_node node0; /* affected node */ 16949f67e12Sratchov struct sioctl_node node1; /* dito for SIOCTL_{VEC,LIST,SEL} */ 17099f201b8Sratchov unsigned int maxval; /* max value */ 171*4aaef610Sratchov char display[SIOCTL_DISPLAYMAX]; /* free-format hint */ 172d07fece6Sratchov}; 173d07fece6Sratchov.Ed 174d07fece6Sratchov.Pp 175d07fece6SratchovThe 1768fe8d172Sschwarze.Fa addr 177d07fece6Sratchovattribute is the control address, usable with 178d07fece6Sratchov.Fn sioctl_setval 179d07fece6Sratchovto set its value. 180d07fece6Sratchov.Pp 181d07fece6SratchovThe 1828fe8d172Sschwarze.Fa type 183d07fece6Sratchovattribute indicates what the structure describes. 184d07fece6SratchovPossible types are: 185d07fece6Sratchov.Bl -tag -width "SIOCTL_LIST" 1868fe8d172Sschwarze.It Dv SIOCTL_NONE 187d07fece6SratchovA previously valid control was deleted. 1888fe8d172Sschwarze.It Dv SIOCTL_NUM 189e04d4d7cSschwarzeAn integer control in the range from 0 to 1908fe8d172Sschwarze.Fa maxval , 1918fe8d172Sschwarzeinclusive. 192d07fece6SratchovFor instance the volume of the speaker. 1938fe8d172Sschwarze.It Dv SIOCTL_SW 194e04d4d7cSschwarzeA boolean control. 195d07fece6SratchovFor instance the switch to mute the speaker. 1968fe8d172Sschwarze.It Dv SIOCTL_VEC 197e04d4d7cSschwarzeElement of an array of integer controls. 198d07fece6SratchovFor instance the knob to control the amount of signal flowing 199d07fece6Sratchovfrom the line input to the speaker. 2008fe8d172Sschwarze.It Dv SIOCTL_LIST 201e04d4d7cSschwarzeAn element of an array of boolean switches. 202d07fece6SratchovFor instance the line-in position of the 203d07fece6Sratchovspeaker source selector. 204803610b3Sratchov.It Dv SIOCTL_SEL 20549f67e12SratchovSame as 206803610b3Sratchov.Dv SIOCTL_LIST 20749f67e12Sratchovbut exactly one element is selected at a time. 208d07fece6Sratchov.El 209d07fece6Sratchov.Pp 210d07fece6SratchovThe 2118fe8d172Sschwarze.Fa func 212d07fece6Sratchovattribute is the name of the parameter being controlled. 213d07fece6SratchovThere may be no parameters of different types with the same name. 214d07fece6Sratchov.Pp 215d07fece6SratchovThe 2168fe8d172Sschwarze.Fa node0 217d07fece6Sratchovand 2188fe8d172Sschwarze.Fa node1 219d07fece6Sratchovattributes indicate the names of the controlled nodes, typically 220d07fece6Sratchovchannels of audio streams. 2218fe8d172Sschwarze.Fa node1 222d07fece6Sratchovis meaningful for 22349f67e12Sratchov.Dv SIOCTL_VEC , 22449f67e12Sratchov.Dv SIOCTL_LIST , 225d07fece6Sratchovand 22649f67e12Sratchov.Dv SIOCTL_SEL 227d07fece6Sratchovonly. 228d07fece6Sratchov.Pp 229d07fece6SratchovNames in the 2308fe8d172Sschwarze.Fa node0 231d07fece6Sratchovand 2328fe8d172Sschwarze.Fa node1 233d07fece6Sratchovattributes and 2348fe8d172Sschwarze.Fa func 23564aa3d5eSschwarzeare strings usable as unique identifiers within the given 2368fe8d172Sschwarze.Fa group . 23799f201b8Sratchov.Pp 23899f201b8SratchovThe 2398fe8d172Sschwarze.Fa maxval 24099f201b8Sratchovattribute indicates the maximum value of this control. 24199f201b8SratchovFor boolean control types it is set to 1. 242*4aaef610Sratchov.Pp 243*4aaef610SratchovThe 244*4aaef610Sratchov.Fa display 245*4aaef610Sratchovattribute contains an optional free-format string providing additional 246*4aaef610Sratchovhints about the control, like the hardware model, or the units. 2478fe8d172Sschwarze.Ss Changing and reading control values 248d07fece6SratchovControls are changed with the 249d07fece6Sratchov.Fn sioctl_setval 250d07fece6Sratchovfunction, by giving the index of the control and the new value. 251d07fece6SratchovThe 252d07fece6Sratchov.Fn sioctl_onval 25364aa3d5eSschwarzefunction can be used to register a callback which will be invoked whenever 254d07fece6Sratchova control changes. 255e04d4d7cSschwarzeInteger values are in the range from 0 to 2568fe8d172Sschwarze.Fa maxval . 2578fe8d172Sschwarze.Ss Interface to poll(2) 258d07fece6SratchovThe 259d07fece6Sratchov.Fn sioctl_pollfd 260d07fece6Sratchovfunction fills the array 2618fe8d172Sschwarze.Fa pfd 262d07fece6Sratchovof 2638fe8d172Sschwarze.Vt pollfd 264d07fece6Sratchovstructures, used by 265d07fece6Sratchov.Xr poll 2 , 266d07fece6Sratchovwith 2678fe8d172Sschwarze.Fa events ; 268d07fece6Sratchovthe latter is a bit-mask of 2698fe8d172Sschwarze.Dv POLLIN 270d07fece6Sratchovand 2718fe8d172Sschwarze.Dv POLLOUT 272d07fece6Sratchovconstants. 273d07fece6Sratchov.Fn sioctl_pollfd 274d07fece6Sratchovreturns the number of 2758fe8d172Sschwarze.Vt pollfd 276d07fece6Sratchovstructures filled. 277d07fece6SratchovThe 278d07fece6Sratchov.Fn sioctl_revents 279d07fece6Sratchovfunction returns the bit-mask set by 280d07fece6Sratchov.Xr poll 2 281d07fece6Sratchovin the 2828fe8d172Sschwarze.Fa pfd 283d07fece6Sratchovarray of 2848fe8d172Sschwarze.Vt pollfd 285d07fece6Sratchovstructures. 286d07fece6SratchovIf 2878fe8d172Sschwarze.Dv POLLOUT 288d07fece6Sratchovis set, 289d07fece6Sratchov.Fn sioctl_setval 290d07fece6Sratchovcan be called without blocking. 2918fe8d172Sschwarze.Dv POLLHUP 2928fe8d172Sschwarzemay be set if an error occurs, even if it is not selected with 293d07fece6Sratchov.Fn sioctl_pollfd . 2948fe8d172Sschwarze.Dv POLLIN 2958fe8d172Sschwarzeis not used yet. 296d07fece6Sratchov.Pp 297d07fece6SratchovThe 298d07fece6Sratchov.Fn sioctl_nfds 299d07fece6Sratchovfunction returns the number of 3008fe8d172Sschwarze.Vt pollfd 301d07fece6Sratchovstructures the caller must preallocate in order to be sure 302d07fece6Sratchovthat 303d07fece6Sratchov.Fn sioctl_pollfd 304d07fece6Sratchovwill never overrun. 30564aa3d5eSschwarze.Sh ENVIRONMENT 30664aa3d5eSschwarze.Bl -tag -width AUDIODEVICE 30764aa3d5eSschwarze.It Ev AUDIODEVICE 30864aa3d5eSschwarzeThe default 30964aa3d5eSschwarze.Xr sndio 7 31064aa3d5eSschwarzedevice used by 31164aa3d5eSschwarze.Fn sioctl_open . 31264aa3d5eSschwarze.El 313d07fece6Sratchov.Sh SEE ALSO 314d07fece6Sratchov.Xr sndioctl 1 , 315d07fece6Sratchov.Xr poll 2 , 31664aa3d5eSschwarze.Xr sio_open 3 , 317d07fece6Sratchov.Xr sndio 7 31864aa3d5eSschwarze.Sh HISTORY 31964aa3d5eSschwarzeThese functions first appeared in 32064aa3d5eSschwarze.Ox 6.7 . 32164aa3d5eSschwarze.Sh AUTHORS 32264aa3d5eSschwarze.An Alexandre Ratchov Aq Mt ratchov@openbsd.org 323