Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SIOCTL_OPEN(3)	       FreeBSD 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);

     sioctl_close(struct sioctl_hdl *hdl);

     sioctl_ondesc(struct sioctl_hdl *hdl,
	 void (*cb)(void *arg, struct sioctl_desc *desc, int val), void	*arg);

     sioctl_onval(struct sioctl_hdl *hdl,
	 void (*cb)(void *arg, unsigned	int addr, unsigned int val),
	 void *arg);

     sioctl_setval(struct sioctl_hdl *hdl, unsigned int	addr,
	 unsigned int val);

     sioctl_nfds(struct	sioctl_hdl *hdl);

     sioctl_pollfd(struct sioctl_hdl *hdl, struct pollfd *pfd, int events);

     sioctl_revents(struct sioctl_hdl *hdl, struct pollfd *pfd);

     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 rep-
     resented 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 bit-
     map of the	SIOCTL_READ and	SIOCTL_WRITE constants indicating whether con-
     trol 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 allo-
     cated 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

     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

     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

     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 in-
     dex 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 struc-
     tures 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  The default sndio(7) device used by sioctl_open().

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

     These functions first appeared in OpenBSD 6.7.

     Alexandre Ratchov <>

FreeBSD	13.0			 June 28, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help