--- name: "sioctl_open" section: "3" platform: "linux" package: "sndio" version: "1.10.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/sioctl_open" --- # sioctl\_open(3) interface to audio parameters ## NAME **sioctl\_open**, **sioctl\_close**, **sioctl\_ondesc**, **sioctl\_onval**, **sioctl\_setval**, **sioctl\_nfds**, **sioctl\_pollfd**, **sioctl\_eof** – interface to audio parameters ## 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 Audio devices may expose a number of controls, like the playback volume control. Each control has an integer *address* and an integer *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 First the application must call the **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)](/sndio/7.md). 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**() function (see below) may fail instead of blocking and the **sioctl\_ondesc**() function doesn't block. The **sioctl\_close**() function closes the control device and frees any allocated resources associated with the handle. ### Control descriptions The **sioctl\_ondesc**() 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**() to set its value. The *type* attribute indicates what the structure describes. Possible types are: - SIOCTL\_NONE A previously valid control was deleted. - SIOCTL\_NUM An integer control in the range from 0 to *maxval*, inclusive. For instance the volume of the speaker. - SIOCTL\_SW A boolean control. For instance the switch to mute the speaker. - 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 An element of an array of boolean switches. For instance the line-in position of the speaker source selector. - 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 Controls are changed with the **sioctl\_setval**() function, by giving the index of the control and the new value. The **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) The **sioctl\_pollfd**() function fills the array *pfd* of *pollfd* structures, used by [poll(2)](/poll/2.md), 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**() function returns the bit-mask set by [poll(2)](/poll/2.md) 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**() function returns the number of *pollfd* structures the caller must preallocate in order to be sure that **sioctl\_pollfd**() will never overrun. ## ENVIRONMENT - AUDIODEVICE The default [sndio(7)](/sndio/7.md) device used by **sioctl\_open**(). ## SEE ALSO [sndioctl(1)](/sndioctl/1.md), [poll(2)](/poll/2.md), [sio\_open(3)](/sio_open/3.md), [sndio(7)](/sndio/7.md) ## HISTORY These functions first appeared in OpenBSD 6.7. ## AUTHORS Alexandre Ratchov ⟨*ratchov@openbsd.org*⟩