1.\" $OpenBSD: sioctl_open.3,v 1.13 2022/05/03 13:03:30 ratchov Exp $ 2.\" 3.\" Copyright (c) 2011-2020 Alexandre Ratchov <alex@caoua.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 3 2022 $ 18.Dt SIOCTL_OPEN 3 19.Os 20.Sh NAME 21.Nm sioctl_open , 22.Nm sioctl_close , 23.Nm sioctl_ondesc , 24.Nm sioctl_onval , 25.Nm sioctl_setval , 26.Nm sioctl_nfds , 27.Nm sioctl_pollfd , 28.Nm sioctl_eof 29.Nd interface to audio parameters 30.Sh SYNOPSIS 31.Fd #include <sndio.h> 32.Ft struct sioctl_hdl * 33.Fo sioctl_open 34.Fa "const char *name" 35.Fa "unsigned int mode" 36.Fa "int nbio_flag" 37.Fc 38.Ft void 39.Fo sioctl_close 40.Fa "struct sioctl_hdl *hdl" 41.Fc 42.Ft int 43.Fo sioctl_ondesc 44.Fa "struct sioctl_hdl *hdl" 45.Fa "void (*cb)(void *arg, struct sioctl_desc *desc, int val)" 46.Fa "void *arg" 47.Fc 48.Ft int 49.Fo sioctl_onval 50.Fa "struct sioctl_hdl *hdl" 51.Fa "void (*cb)(void *arg, unsigned int addr, unsigned int val)" 52.Fa "void *arg" 53.Fc 54.Ft int 55.Fo sioctl_setval 56.Fa "struct sioctl_hdl *hdl" 57.Fa "unsigned int addr" 58.Fa "unsigned int val" 59.Fc 60.Ft int 61.Fo sioctl_nfds 62.Fa "struct sioctl_hdl *hdl" 63.Fc 64.Ft int 65.Fo sioctl_pollfd 66.Fa "struct sioctl_hdl *hdl" 67.Fa "struct pollfd *pfd" 68.Fa "int events" 69.Fc 70.Ft int 71.Fo sioctl_revents 72.Fa "struct sioctl_hdl *hdl" 73.Fa "struct pollfd *pfd" 74.Fc 75.Ft int 76.Fo sioctl_eof 77.Fa "struct sioctl_hdl *hdl" 78.Fc 79.Sh DESCRIPTION 80Audio devices may expose a number of controls, like the playback volume control. 81Each control has an integer 82.Em address 83and an integer 84.Em value . 85Some values are boolean and can only be switched to either 0 (off) or 1 (on). 86Any control may be changed by submitting 87a new value to its address. 88When values change, asynchronous notifications are sent. 89.Pp 90Control descriptions are available, allowing them to be grouped and 91represented in a human readable form. 92.Ss Opening and closing the control device 93First the application must call the 94.Fn sioctl_open 95function to obtain a handle 96that will be passed as the 97.Fa hdl 98argument to other functions. 99.Pp 100The 101.Fa name 102parameter gives the device string discussed in 103.Xr sndio 7 . 104In most cases it should be set to SIO_DEVANY to allow 105the user to select it using the 106.Ev AUDIODEVICE 107environment variable. 108The 109.Fa mode 110parameter is a bitmap of the 111.Dv SIOCTL_READ 112and 113.Dv SIOCTL_WRITE 114constants indicating whether control values can be read and 115modified respectively. 116.Pp 117If the 118.Fa nbio_flag 119argument is 1, then the 120.Fn sioctl_setval 121function (see below) may fail instead of blocking and 122the 123.Fn sioctl_ondesc 124function doesn't block. 125.Pp 126The 127.Fn sioctl_close 128function closes the control device and frees any allocated resources 129associated with the handle. 130.Ss Control descriptions 131The 132.Fn sioctl_ondesc 133function can be used to obtain the description of all available controls 134and their initial values. 135It registers a callback function that is immediately invoked for all 136controls. 137It is called once with a 138.Dv NULL 139argument to indicate that the full 140description was sent and that the caller has a consistent 141representation of the control set. 142.Pp 143Then, whenever a control description changes, the callback is 144invoked with the updated information followed by a call with a 145.Dv NULL 146argument. 147.Pp 148Controls are described by the 149.Vt sioctl_desc 150structure as follows: 151.Bd -literal 152struct sioctl_node { 153 char name[SIOCTL_NAMEMAX]; /* ex. "spkr" */ 154 int unit; /* optional number or -1 */ 155}; 156 157struct sioctl_desc { 158 unsigned int addr; /* control address */ 159#define SIOCTL_NONE 0 /* deleted */ 160#define SIOCTL_NUM 2 /* integer in the maxval range */ 161#define SIOCTL_SW 3 /* on/off switch (1 or 0) */ 162#define SIOCTL_VEC 4 /* number, element of vector */ 163#define SIOCTL_LIST 5 /* switch, element of a list */ 164#define SIOCTL_SEL 6 /* element of a selector */ 165 unsigned int type; /* one of above */ 166 char func[SIOCTL_NAMEMAX]; /* function name, ex. "level" */ 167 char group[SIOCTL_NAMEMAX]; /* group this control belongs to */ 168 struct sioctl_node node0; /* affected node */ 169 struct sioctl_node node1; /* dito for SIOCTL_{VEC,LIST,SEL} */ 170 unsigned int maxval; /* max value */ 171}; 172.Ed 173.Pp 174The 175.Fa addr 176attribute is the control address, usable with 177.Fn sioctl_setval 178to set its value. 179.Pp 180The 181.Fa type 182attribute indicates what the structure describes. 183Possible types are: 184.Bl -tag -width "SIOCTL_LIST" 185.It Dv SIOCTL_NONE 186A previously valid control was deleted. 187.It Dv SIOCTL_NUM 188An integer control in the range from 0 to 189.Fa maxval , 190inclusive. 191For instance the volume of the speaker. 192.It Dv SIOCTL_SW 193A boolean control. 194For instance the switch to mute the speaker. 195.It Dv SIOCTL_VEC 196Element of an array of integer controls. 197For instance the knob to control the amount of signal flowing 198from the line input to the speaker. 199.It Dv SIOCTL_LIST 200An element of an array of boolean switches. 201For instance the line-in position of the 202speaker source selector. 203.It Dv SIOCTL_SEL 204Same as 205.Dv SIOCTL_LIST 206but exactly one element is selected at a time. 207.El 208.Pp 209The 210.Fa func 211attribute is the name of the parameter being controlled. 212There may be no parameters of different types with the same name. 213.Pp 214The 215.Fa node0 216and 217.Fa node1 218attributes indicate the names of the controlled nodes, typically 219channels of audio streams. 220.Fa node1 221is meaningful for 222.Dv SIOCTL_VEC , 223.Dv SIOCTL_LIST , 224and 225.Dv SIOCTL_SEL 226only. 227.Pp 228Names in the 229.Fa node0 230and 231.Fa node1 232attributes and 233.Fa func 234are strings usable as unique identifiers within the given 235.Fa group . 236.Pp 237The 238.Fa maxval 239attribute indicates the maximum value of this control. 240For boolean control types it is set to 1. 241.Ss Changing and reading control values 242Controls are changed with the 243.Fn sioctl_setval 244function, by giving the index of the control and the new value. 245The 246.Fn sioctl_onval 247function can be used to register a callback which will be invoked whenever 248a control changes. 249Integer values are in the range from 0 to 250.Fa maxval . 251.Ss Interface to poll(2) 252The 253.Fn sioctl_pollfd 254function fills the array 255.Fa pfd 256of 257.Vt pollfd 258structures, used by 259.Xr poll 2 , 260with 261.Fa events ; 262the latter is a bit-mask of 263.Dv POLLIN 264and 265.Dv POLLOUT 266constants. 267.Fn sioctl_pollfd 268returns the number of 269.Vt pollfd 270structures filled. 271The 272.Fn sioctl_revents 273function returns the bit-mask set by 274.Xr poll 2 275in the 276.Fa pfd 277array of 278.Vt pollfd 279structures. 280If 281.Dv POLLOUT 282is set, 283.Fn sioctl_setval 284can be called without blocking. 285.Dv POLLHUP 286may be set if an error occurs, even if it is not selected with 287.Fn sioctl_pollfd . 288.Dv POLLIN 289is not used yet. 290.Pp 291The 292.Fn sioctl_nfds 293function returns the number of 294.Vt pollfd 295structures the caller must preallocate in order to be sure 296that 297.Fn sioctl_pollfd 298will never overrun. 299.Sh ENVIRONMENT 300.Bl -tag -width AUDIODEVICE 301.It Ev AUDIODEVICE 302The default 303.Xr sndio 7 304device used by 305.Fn sioctl_open . 306.El 307.Sh SEE ALSO 308.Xr sndioctl 1 , 309.Xr poll 2 , 310.Xr sio_open 3 , 311.Xr sndio 7 312.Sh HISTORY 313These functions first appeared in 314.Ox 6.7 . 315.Sh AUTHORS 316.An Alexandre Ratchov Aq Mt ratchov@openbsd.org 317