317 lines
7.4 KiB
Groff
317 lines
7.4 KiB
Groff
.\" $OpenBSD: sioctl_open.3,v 1.13 2022/05/03 13:03:30 ratchov Exp $
|
|
.\"
|
|
.\" Copyright (c) 2011-2020 Alexandre Ratchov <alex@caoua.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: May 3 2022 $
|
|
.Dt SIOCTL_OPEN 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sioctl_open ,
|
|
.Nm sioctl_close ,
|
|
.Nm sioctl_ondesc ,
|
|
.Nm sioctl_onval ,
|
|
.Nm sioctl_setval ,
|
|
.Nm sioctl_nfds ,
|
|
.Nm sioctl_pollfd ,
|
|
.Nm sioctl_eof
|
|
.Nd interface to audio parameters
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sndio.h>
|
|
.Ft struct sioctl_hdl *
|
|
.Fo sioctl_open
|
|
.Fa "const char *name"
|
|
.Fa "unsigned int mode"
|
|
.Fa "int nbio_flag"
|
|
.Fc
|
|
.Ft void
|
|
.Fo sioctl_close
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_ondesc
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fa "void (*cb)(void *arg, struct sioctl_desc *desc, int val)"
|
|
.Fa "void *arg"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_onval
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fa "void (*cb)(void *arg, unsigned int addr, unsigned int val)"
|
|
.Fa "void *arg"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_setval
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fa "unsigned int addr"
|
|
.Fa "unsigned int val"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_nfds
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_pollfd
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fa "struct pollfd *pfd"
|
|
.Fa "int events"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_revents
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fa "struct pollfd *pfd"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sioctl_eof
|
|
.Fa "struct sioctl_hdl *hdl"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
Audio devices may expose a number of controls, like the playback volume control.
|
|
Each control has an integer
|
|
.Em address
|
|
and an integer
|
|
.Em 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.
|
|
.Pp
|
|
Control descriptions are available, allowing them to be grouped and
|
|
represented in a human readable form.
|
|
.Ss Opening and closing the control device
|
|
First the application must call the
|
|
.Fn sioctl_open
|
|
function to obtain a handle
|
|
that will be passed as the
|
|
.Fa hdl
|
|
argument to other functions.
|
|
.Pp
|
|
The
|
|
.Fa name
|
|
parameter gives the device string discussed in
|
|
.Xr sndio 7 .
|
|
In most cases it should be set to SIO_DEVANY to allow
|
|
the user to select it using the
|
|
.Ev AUDIODEVICE
|
|
environment variable.
|
|
The
|
|
.Fa mode
|
|
parameter is a bitmap of the
|
|
.Dv SIOCTL_READ
|
|
and
|
|
.Dv SIOCTL_WRITE
|
|
constants indicating whether control values can be read and
|
|
modified respectively.
|
|
.Pp
|
|
If the
|
|
.Fa nbio_flag
|
|
argument is 1, then the
|
|
.Fn sioctl_setval
|
|
function (see below) may fail instead of blocking and
|
|
the
|
|
.Fn sioctl_ondesc
|
|
function doesn't block.
|
|
.Pp
|
|
The
|
|
.Fn sioctl_close
|
|
function closes the control device and frees any allocated resources
|
|
associated with the handle.
|
|
.Ss Control descriptions
|
|
The
|
|
.Fn 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
|
|
.Dv NULL
|
|
argument to indicate that the full
|
|
description was sent and that the caller has a consistent
|
|
representation of the control set.
|
|
.Pp
|
|
Then, whenever a control description changes, the callback is
|
|
invoked with the updated information followed by a call with a
|
|
.Dv NULL
|
|
argument.
|
|
.Pp
|
|
Controls are described by the
|
|
.Vt sioctl_desc
|
|
structure as follows:
|
|
.Bd -literal
|
|
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 */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa addr
|
|
attribute is the control address, usable with
|
|
.Fn sioctl_setval
|
|
to set its value.
|
|
.Pp
|
|
The
|
|
.Fa type
|
|
attribute indicates what the structure describes.
|
|
Possible types are:
|
|
.Bl -tag -width "SIOCTL_LIST"
|
|
.It Dv SIOCTL_NONE
|
|
A previously valid control was deleted.
|
|
.It Dv SIOCTL_NUM
|
|
An integer control in the range from 0 to
|
|
.Fa maxval ,
|
|
inclusive.
|
|
For instance the volume of the speaker.
|
|
.It Dv SIOCTL_SW
|
|
A boolean control.
|
|
For instance the switch to mute the speaker.
|
|
.It Dv 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.
|
|
.It Dv SIOCTL_LIST
|
|
An element of an array of boolean switches.
|
|
For instance the line-in position of the
|
|
speaker source selector.
|
|
.It Dv SIOCTL_SEL
|
|
Same as
|
|
.Dv SIOCTL_LIST
|
|
but exactly one element is selected at a time.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa func
|
|
attribute is the name of the parameter being controlled.
|
|
There may be no parameters of different types with the same name.
|
|
.Pp
|
|
The
|
|
.Fa node0
|
|
and
|
|
.Fa node1
|
|
attributes indicate the names of the controlled nodes, typically
|
|
channels of audio streams.
|
|
.Fa node1
|
|
is meaningful for
|
|
.Dv SIOCTL_VEC ,
|
|
.Dv SIOCTL_LIST ,
|
|
and
|
|
.Dv SIOCTL_SEL
|
|
only.
|
|
.Pp
|
|
Names in the
|
|
.Fa node0
|
|
and
|
|
.Fa node1
|
|
attributes and
|
|
.Fa func
|
|
are strings usable as unique identifiers within the given
|
|
.Fa group .
|
|
.Pp
|
|
The
|
|
.Fa maxval
|
|
attribute indicates the maximum value of this control.
|
|
For boolean control types it is set to 1.
|
|
.Ss Changing and reading control values
|
|
Controls are changed with the
|
|
.Fn sioctl_setval
|
|
function, by giving the index of the control and the new value.
|
|
The
|
|
.Fn 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
|
|
.Fa maxval .
|
|
.Ss Interface to poll(2)
|
|
The
|
|
.Fn sioctl_pollfd
|
|
function fills the array
|
|
.Fa pfd
|
|
of
|
|
.Vt pollfd
|
|
structures, used by
|
|
.Xr poll 2 ,
|
|
with
|
|
.Fa events ;
|
|
the latter is a bit-mask of
|
|
.Dv POLLIN
|
|
and
|
|
.Dv POLLOUT
|
|
constants.
|
|
.Fn sioctl_pollfd
|
|
returns the number of
|
|
.Vt pollfd
|
|
structures filled.
|
|
The
|
|
.Fn sioctl_revents
|
|
function returns the bit-mask set by
|
|
.Xr poll 2
|
|
in the
|
|
.Fa pfd
|
|
array of
|
|
.Vt pollfd
|
|
structures.
|
|
If
|
|
.Dv POLLOUT
|
|
is set,
|
|
.Fn sioctl_setval
|
|
can be called without blocking.
|
|
.Dv POLLHUP
|
|
may be set if an error occurs, even if it is not selected with
|
|
.Fn sioctl_pollfd .
|
|
.Dv POLLIN
|
|
is not used yet.
|
|
.Pp
|
|
The
|
|
.Fn sioctl_nfds
|
|
function returns the number of
|
|
.Vt pollfd
|
|
structures the caller must preallocate in order to be sure
|
|
that
|
|
.Fn sioctl_pollfd
|
|
will never overrun.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width AUDIODEVICE
|
|
.It Ev AUDIODEVICE
|
|
The default
|
|
.Xr sndio 7
|
|
device used by
|
|
.Fn sioctl_open .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr sndioctl 1 ,
|
|
.Xr poll 2 ,
|
|
.Xr sio_open 3 ,
|
|
.Xr sndio 7
|
|
.Sh HISTORY
|
|
These functions first appeared in
|
|
.Ox 6.7 .
|
|
.Sh AUTHORS
|
|
.An Alexandre Ratchov Aq Mt ratchov@openbsd.org
|