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