SIOCTL\_OPEN(3) Library Functions Manual SIOCTL\_OPEN(3) # [NAME](#NAME) `sioctl_open`, `sioctl_close`, `sioctl_ondesc`, `sioctl_onval`, `sioctl_setval`, `sioctl_nfds`, `sioctl_pollfd`, `sioctl_eof` — interface to audio parameters # [SYNOPSIS](#SYNOPSIS) `#include ` `struct sioctl_hdl *` `sioctl_open`(`const char *name`, `unsigned int mode`, `int nbio_flag`); `void` `sioctl_close`(`struct sioctl_hdl *hdl`); `int` `sioctl_ondesc`(`struct sioctl_hdl *hdl`, `void (*cb)(void *arg, struct sioctl_desc *desc, int val)`, `void *arg`); `int` `sioctl_onval`(`struct sioctl_hdl *hdl`, `void (*cb)(void *arg, unsigned int addr, unsigned int val)`, `void *arg`); `int` `sioctl_setval`(`struct sioctl_hdl *hdl`, `unsigned int addr`, `unsigned int val`); `int` `sioctl_nfds`(`struct sioctl_hdl *hdl`); `int` `sioctl_pollfd`(`struct sioctl_hdl *hdl`, `struct pollfd *pfd`, `int events`); `int` `sioctl_revents`(`struct sioctl_hdl *hdl`, `struct pollfd *pfd`); `int` `sioctl_eof`(`struct sioctl_hdl *hdl`); # [DESCRIPTION](#DESCRIPTION) Audio devices may expose a number of controls, like the playback volume control. Each control has an integer [*address*](#address) and an integer [*value*](#value). Some values are boolean and can only be switched to either 0 (off) or 1 (on). Any control may be changed by submitting a new value to its address. When values change, asynchronous notifications are sent. Control descriptions are available, allowing them to be grouped and represented in a human readable form. ## [Opening and closing the control device](#Opening_and_closing_the_control_device) First the application must call the [`sioctl_open`](#sioctl_open)() function to obtain a handle that will be passed as the `hdl` argument to other functions. The `name` parameter gives the device string discussed in [sndio(7)](/man/os/sndio/sndio.7). In most cases it should be set to SIO\_DEVANY to allow the user to select it using the `AUDIODEVICE` environment variable. The `mode` parameter is a bitmap of the `SIOCTL_READ` and `SIOCTL_WRITE` constants indicating whether control values can be read and modified respectively. If the `nbio_flag` argument is 1, then the [`sioctl_setval`](#sioctl_setval)() function (see below) may fail instead of blocking and the [`sioctl_ondesc`](#sioctl_ondesc)() function doesn't block. The [`sioctl_close`](#sioctl_close)() function closes the control device and frees any allocated resources associated with the handle. ## [Control descriptions](#Control_descriptions) The [`sioctl_ondesc`](#sioctl_ondesc~2)() function can be used to obtain the description of all available controls and their initial values. It registers a callback function that is immediately invoked for all controls. It is called once with a `NULL` argument to indicate that the full description was sent and that the caller has a consistent representation of the control set. Then, whenever a control description changes, the callback is invoked with the updated information followed by a call with a `NULL` argument. Controls are described by the `sioctl_desc` structure as follows: ``` struct sioctl_node { char name[SIOCTL_NAMEMAX]; /* ex. "spkr" */ int unit; /* optional number or -1 */ }; struct sioctl_desc { unsigned int addr; /* control address */ #define SIOCTL_NONE 0 /* deleted */ #define SIOCTL_NUM 2 /* integer in the maxval range */ #define SIOCTL_SW 3 /* on/off switch (1 or 0) */ #define SIOCTL_VEC 4 /* number, element of vector */ #define SIOCTL_LIST 5 /* switch, element of a list */ #define SIOCTL_SEL 6 /* element of a selector */ unsigned int type; /* one of above */ char func[SIOCTL_NAMEMAX]; /* function name, ex. "level" */ char group[SIOCTL_NAMEMAX]; /* group this control belongs to */ struct sioctl_node node0; /* affected node */ struct sioctl_node node1; /* dito for SIOCTL_{VEC,LIST,SEL} */ unsigned int maxval; /* max value */ char display[SIOCTL_DISPLAYMAX]; /* free-format hint */ }; ``` The `addr` attribute is the control address, usable with [`sioctl_setval`](#sioctl_setval~2)() to set its value. The `type` attribute indicates what the structure describes. Possible types are: [`SIOCTL_NONE`](#SIOCTL_NONE) A previously valid control was deleted. [`SIOCTL_NUM`](#SIOCTL_NUM) An integer control in the range from 0 to `maxval`, inclusive. For instance the volume of the speaker. [`SIOCTL_SW`](#SIOCTL_SW) A boolean control. For instance the switch to mute the speaker. [`SIOCTL_VEC`](#SIOCTL_VEC) Element of an array of integer controls. For instance the knob to control the amount of signal flowing from the line input to the speaker. [`SIOCTL_LIST`](#SIOCTL_LIST) An element of an array of boolean switches. For instance the line-in position of the speaker source selector. [`SIOCTL_SEL`](#SIOCTL_SEL) Same as `SIOCTL_LIST` but exactly one element is selected at a time. The `func` attribute is the name of the parameter being controlled. There may be no parameters of different types with the same name. The `node0` and `node1` attributes indicate the names of the controlled nodes, typically channels of audio streams. `node1` is meaningful for `SIOCTL_VEC`, `SIOCTL_LIST`, and `SIOCTL_SEL` only. Names in the `node0` and `node1` attributes and `func` are strings usable as unique identifiers within the given `group`. The `maxval` attribute indicates the maximum value of this control. For boolean control types it is set to 1. The `display` attribute contains an optional free-format string providing additional hints about the control, like the hardware model, or the units. ## [Changing and reading control values](#Changing_and_reading_control_values) Controls are changed with the [`sioctl_setval`](#sioctl_setval~3)() function, by giving the index of the control and the new value. The [`sioctl_onval`](#sioctl_onval)() function can be used to register a callback which will be invoked whenever a control changes. Integer values are in the range from 0 to `maxval`. ## [Interface to poll(2)](#Interface_to_poll%282%29) The `sioctl_pollfd`() function fills the array `pfd` of `pollfd` structures, used by [poll(2)](/man/os/sndio/poll.2), with `events`; the latter is a bit-mask of `POLLIN` and `POLLOUT` constants. `sioctl_pollfd`() returns the number of `pollfd` structures filled. The [`sioctl_revents`](#sioctl_revents)() function returns the bit-mask set by [poll(2)](/man/os/sndio/poll.2) in the `pfd` array of `pollfd` structures. If `POLLOUT` is set, `sioctl_setval`() can be called without blocking. `POLLHUP` may be set if an error occurs, even if it is not selected with `sioctl_pollfd`(). `POLLIN` is not used yet. The [`sioctl_nfds`](#sioctl_nfds)() function returns the number of `pollfd` structures the caller must preallocate in order to be sure that [`sioctl_pollfd`](#sioctl_pollfd)() will never overrun. # [ENVIRONMENT](#ENVIRONMENT) [`AUDIODEVICE`](#AUDIODEVICE) The default [sndio(7)](/man/os/sndio/sndio.7) device used by `sioctl_open`(). # [SEE ALSO](#SEE_ALSO) [sndioctl(1)](/man/os/sndio/sndioctl.1), [poll(2)](/man/os/sndio/poll.2), [sio\_open(3)](/man/os/sndio/sio_open.3), [sndio(7)](/man/os/sndio/sndio.7) # [HISTORY](#HISTORY) These functions first appeared in OpenBSD 6.7. # [AUTHORS](#AUTHORS) Alexandre Ratchov <[ratchov@openbsd.org](mailto:ratchov@openbsd.org)> Linux 4.19.0-gvisor --- Document: sioctl_onval(3) from sndio 1.10.0-r10 (Chainguard OS) Source: https://github.com/ratchov/sndio