1.\" $OpenBSD: sioctl_open.3,v 1.14 2024/05/24 15:10:27 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 24 2024 $ 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 char display[SIOCTL_DISPLAYMAX]; /* free-format hint */ 172}; 173.Ed 174.Pp 175The 176.Fa addr 177attribute is the control address, usable with 178.Fn sioctl_setval 179to set its value. 180.Pp 181The 182.Fa type 183attribute indicates what the structure describes. 184Possible types are: 185.Bl -tag -width "SIOCTL_LIST" 186.It Dv SIOCTL_NONE 187A previously valid control was deleted. 188.It Dv SIOCTL_NUM 189An integer control in the range from 0 to 190.Fa maxval , 191inclusive. 192For instance the volume of the speaker. 193.It Dv SIOCTL_SW 194A boolean control. 195For instance the switch to mute the speaker. 196.It Dv SIOCTL_VEC 197Element of an array of integer controls. 198For instance the knob to control the amount of signal flowing 199from the line input to the speaker. 200.It Dv SIOCTL_LIST 201An element of an array of boolean switches. 202For instance the line-in position of the 203speaker source selector. 204.It Dv SIOCTL_SEL 205Same as 206.Dv SIOCTL_LIST 207but exactly one element is selected at a time. 208.El 209.Pp 210The 211.Fa func 212attribute is the name of the parameter being controlled. 213There may be no parameters of different types with the same name. 214.Pp 215The 216.Fa node0 217and 218.Fa node1 219attributes indicate the names of the controlled nodes, typically 220channels of audio streams. 221.Fa node1 222is meaningful for 223.Dv SIOCTL_VEC , 224.Dv SIOCTL_LIST , 225and 226.Dv SIOCTL_SEL 227only. 228.Pp 229Names in the 230.Fa node0 231and 232.Fa node1 233attributes and 234.Fa func 235are strings usable as unique identifiers within the given 236.Fa group . 237.Pp 238The 239.Fa maxval 240attribute indicates the maximum value of this control. 241For boolean control types it is set to 1. 242.Pp 243The 244.Fa display 245attribute contains an optional free-format string providing additional 246hints about the control, like the hardware model, or the units. 247.Ss Changing and reading control values 248Controls are changed with the 249.Fn sioctl_setval 250function, by giving the index of the control and the new value. 251The 252.Fn sioctl_onval 253function can be used to register a callback which will be invoked whenever 254a control changes. 255Integer values are in the range from 0 to 256.Fa maxval . 257.Ss Interface to poll(2) 258The 259.Fn sioctl_pollfd 260function fills the array 261.Fa pfd 262of 263.Vt pollfd 264structures, used by 265.Xr poll 2 , 266with 267.Fa events ; 268the latter is a bit-mask of 269.Dv POLLIN 270and 271.Dv POLLOUT 272constants. 273.Fn sioctl_pollfd 274returns the number of 275.Vt pollfd 276structures filled. 277The 278.Fn sioctl_revents 279function returns the bit-mask set by 280.Xr poll 2 281in the 282.Fa pfd 283array of 284.Vt pollfd 285structures. 286If 287.Dv POLLOUT 288is set, 289.Fn sioctl_setval 290can be called without blocking. 291.Dv POLLHUP 292may be set if an error occurs, even if it is not selected with 293.Fn sioctl_pollfd . 294.Dv POLLIN 295is not used yet. 296.Pp 297The 298.Fn sioctl_nfds 299function returns the number of 300.Vt pollfd 301structures the caller must preallocate in order to be sure 302that 303.Fn sioctl_pollfd 304will never overrun. 305.Sh ENVIRONMENT 306.Bl -tag -width AUDIODEVICE 307.It Ev AUDIODEVICE 308The default 309.Xr sndio 7 310device used by 311.Fn sioctl_open . 312.El 313.Sh SEE ALSO 314.Xr sndioctl 1 , 315.Xr poll 2 , 316.Xr sio_open 3 , 317.Xr sndio 7 318.Sh HISTORY 319These functions first appeared in 320.Ox 6.7 . 321.Sh AUTHORS 322.An Alexandre Ratchov Aq Mt ratchov@openbsd.org 323