NAME

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

SYNOPSIS

     #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 */
     };

     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.

   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>