1.\" $OpenBSD: sioctl_open.3,v 1.2 2020/02/26 14:41:42 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: February 26 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.Fn "sioctl_open" "const char *name" "unsigned int mode" "int nbio_flag" 34.Ft "void" 35.Fn "sioctl_close" "struct sioctl_hdl *hdl" 36.Ft "int" 37.Fn "sioctl_ondesc" "struct sioctl_hdl *hdl" "void (*cb)(void *arg, struct sioctl_desc *desc, int val)" "void *arg" 38.Ft "void" 39.Fn "sioctl_onval" "struct sioctl_hdl *hdl" "void (*cb)(void *arg, unsigned int addr, unsigned int val)" "void *arg" 40.Ft "int" 41.Fn "sioctl_setval" "struct sioctl_hdl *hdl" "unsigned int addr" "unsigned int val" 42.Ft "int" 43.Fn "sioctl_nfds" "struct sioctl_hdl *hdl" 44.Ft "int" 45.Fn "sioctl_pollfd" "struct sioctl_hdl *hdl" "struct pollfd *pfd" "int events" 46.Ft "int" 47.Fn "sioctl_revents" "struct sioctl_hdl *hdl" "struct pollfd *pfd" 48.Ft "int" 49.Fn "sioctl_eof" "struct sioctl_hdl *hdl" 50.Sh DESCRIPTION 51Audio devices may expose a number of controls, like the playback volume control. 52Each control has an integer 53.Em address 54and an integer 55.Em value . 56Depending on the control type, its integer value represents either a 57continuous quantity or a boolean. 58Any control may be changed by submitting 59a new value to its address. 60When values change, asynchronous notifications are sent. 61.Pp 62Controls descriptions are available, allowing them to be grouped and 63represented in a human usable form. 64.Sh Opening and closing the control device 65First the application must call the 66.Fn sioctl_open 67function to obtain a handle 68that will be passed as the 69.Ar hdl 70argument to other functions. 71.Pp 72The 73.Ar name 74parameter gives the device string discussed in 75.Xr sndio 7 . 76In most cases it should be set to SIOCTL_DEVANY to allow 77the user to select it using the 78.Ev AUDIODEVICE 79environment variable. 80The 81.Ar mode 82parameter is a bitmap of the SIOCTL_READ and SIOCTL_WRITE constants 83indicating whether control values can be read and 84modified respectively. 85.Pp 86If the 87.Ar nbio_flag 88argument is 1, then the 89.Fn sioctl_setval 90function (see below) may fail instead of blocking and 91the 92.Fn sioctl_ondesc 93function doesn't block. 94.Pp 95The 96.Fn sioctl_close 97function closes the control device and frees any allocated resources 98associated with the handle. 99.Sh Controls descriptions 100The 101.Fn sioctl_ondesc 102function can be used to obtain the description of all available controls 103and their initial values. 104It registers a call-back that is immediately invoked for all 105controls. 106It's called once with a NULL argument to indicate that the full 107description was sent and that the caller has a consistent 108representation of the controls set. 109.Pp 110Then, whenever a control description changes, the call-back is 111invoked with the updated information followed by a call with a NULL 112argument. 113.Pp 114Controls are described by the 115.Va sioctl_ondesc 116stucture as follows: 117.Bd -literal 118struct sioctl_node { 119 char name[SIOCTL_NAMEMAX]; /* ex. "spkr" */ 120 int unit; /* optional number or -1 */ 121}; 122 123struct sioctl_desc { 124 unsigned int addr; /* control address */ 125#define SIOCTL_NONE 0 /* deleted */ 126#define SIOCTL_NUM 2 /* integer in the 0..127 range */ 127#define SIOCTL_SW 3 /* on/off switch (0 or 1) */ 128#define SIOCTL_VEC 4 /* number, element of vector */ 129#define SIOCTL_LIST 5 /* switch, element of a list */ 130 unsigned int type; /* one of above */ 131 char func[SIOCTL_NAMEMAX]; /* function name, ex. "level" */ 132 char group[SIOCTL_NAMEMAX]; /* group this control belongs to */ 133 struct sioctl_node node0; /* affected node */ 134 struct sioctl_node node1; /* dito for SIOCTL_{VEC,LIST} */ 135}; 136.Ed 137.Pp 138The 139.Va addr 140attribute is the control address, usable with 141.Fn sioctl_setval 142to set its value. 143.Pp 144The 145.Va type 146attribute indicates what the structure describes. 147Possible types are: 148.Bl -tag -width "SIOCTL_LIST" 149.It SIOCTL_NONE 150A previously valid control was deleted. 151.It SIOCTL_NUM 152A continuous control in the 0..SIOCTL_VALMAX range. 153For instance the volume of the speaker. 154.It SIOCTL_SW 155A on/off switch control. 156For instance the switch to mute the speaker. 157.It SIOCTL_VEC 158Element of an array of continuous controls. 159For instance the knob to control the amount of signal flowing 160from the line input to the speaker. 161.It SIOCTL_LIST 162An element of an array of on/off switches. 163For instance the line-in position of the 164speaker source selector. 165.El 166.Pp 167The 168.Va func 169attribute is the name of the parameter being controlled. 170There may be no parameters of different types with the same name. 171.Pp 172The 173.Va node0 174and 175.Va node1 176attributes indicate the names of the controlled nodes, typically 177channels of audio streams. 178.Va node1 179is meaningful for 180.Va SIOCTL_VEC 181and 182.Va SIOCTL_LIST 183only. 184.Pp 185Names in the 186.Va node0 187and 188.Va node1 189attributes and 190.Va func 191are strings usable as unique identifiers within the the given 192.Va group . 193.Sh Changing and reading control values 194Controls are changed with the 195.Fn sioctl_setval 196function, by giving the index of the control and the new value. 197The 198.Fn sioctl_onval 199function can be used to register a call-back which will be invoked whenever 200a control changes. 201Continuous values are in the 0..127 range. 202.Sh "Interface to" Xr poll 2 203The 204.Fn sioctl_pollfd 205function fills the array 206.Ar pfd 207of 208.Va pollfd 209structures, used by 210.Xr poll 2 , 211with 212.Ar events ; 213the latter is a bit-mask of 214.Va POLLIN 215and 216.Va POLLOUT 217constants. 218.Fn sioctl_pollfd 219returns the number of 220.Va pollfd 221structures filled. 222The 223.Fn sioctl_revents 224function returns the bit-mask set by 225.Xr poll 2 226in the 227.Va pfd 228array of 229.Va pollfd 230structures. 231If 232.Va POLLOUT 233is set, 234.Fn sioctl_setval 235can be called without blocking. 236POLLHUP may be set if an error occurs, even if 237it is not selected with 238.Fn sioctl_pollfd . 239POLLIN is not used yet. 240.Pp 241The 242.Fn sioctl_nfds 243function returns the number of 244.Va pollfd 245structures the caller must preallocate in order to be sure 246that 247.Fn sioctl_pollfd 248will never overrun. 249.Sh SEE ALSO 250.Xr sndioctl 1 , 251.Xr poll 2 , 252.Xr sndio 7 253