SIOCTL_OPEN(3) | Library Functions Manual | SIOCTL_OPEN(3)

# NAME

`sioctl_open`, `sioctl_close`, `sioctl_ondesc`, `sioctl_onval`, `sioctl_setval`, `sioctl_nfds`, `sioctl_pollfd`, `sioctl_revents`, `sioctl_eof` — interface to audio parameters

# SYNOPSIS

library “libsndio”
`#include <sndio.h>`

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). 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), 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) 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) device used by `sioctl_open`().

# SEE ALSO

sndioctl(1), poll(2), sio_open(3), sndio(7)

# HISTORY

These functions first appeared in OpenBSD 6.7.

# AUTHORS

Alexandre Ratchov <ratchov@openbsd.org>

June 7, 2025 | Debian