SIOCTL_OPEN(3) | Library Functions Manual | SIOCTL_OPEN(3) |
sioctl_open
,
sioctl_close
, sioctl_ondesc
,
sioctl_onval
, sioctl_setval
,
sioctl_nfds
, sioctl_pollfd
,
sioctl_eof
— interface to
audio parameters
#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);
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.
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.
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 */ };
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
SIOCTL_NUM
SIOCTL_SW
SIOCTL_VEC
SIOCTL_LIST
SIOCTL_SEL
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.
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.
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.
AUDIODEVICE
sioctl_open
().These functions first appeared in OpenBSD 6.7.
Alexandre Ratchov <ratchov@openbsd.org>
June 19, 2024 | Debian |