Page MenuHomeFreeBSD
Files F144987272

D34603.id103992.diff
No OneTemporary
Actions

D34603.id103992.diff
View Options

diff --git a/lib/libmixer/mixer.3 b/lib/libmixer/mixer.3
--- a/lib/libmixer/mixer.3
+++ b/lib/libmixer/mixer.3
@@ -21,8 +21,7 @@
.\"
.\" $FreeBSD$
.\"
-
-.Dd September 22, 2021
+.Dd March 18, 2022
.Dt MIXER 3
.Os
.Sh NAME
@@ -40,7 +39,7 @@
.Nm mixer_mod_recsrc ,
.Nm mixer_get_dunit ,
.Nm mixer_set_dunit ,
-.Nm mixer_get_mode,
+.Nm mixer_get_mode ,
.Nm mixer_get_nmixers ,
.Nm MIX_ISDEV ,
.Nm MIX_ISMUTE ,
@@ -64,7 +63,7 @@
.Ft int
.Fn mixer_add_ctl "struct mix_dev *parent" "int id" "const char *name" \
"int (*mod)(struct mix_dev *d, void *p)" \
- "int (*print)(struct mix_dev *d, void *p)
+ "int (*print)(struct mix_dev *d, void *p)"
.Ft int
.Fn mixer_add_ctl_s "mix_ctl_t *ctl"
.Ft int
@@ -105,7 +104,6 @@
library allows userspace programs to access and manipulate OSS sound mixers in
a simple way.
.Ss Mixer
-.Pp
A mixer is described by the following structure:
.Bd -literal
struct mixer {
@@ -141,16 +139,19 @@
.It Fa devs
A tail queue structure containing all supported mixer devices.
.It Fa dev
-A pointer to the currently selected device. The device is one of the elements in
+A pointer to the currently selected device.
+The device is one of the elements in
.Ar devs .
.It Fa mi
-OSS information about the mixer. Look at the definition of the
+OSS information about the mixer.
+Look at the definition of the
.Ft oss_mixerinfo
structure in
.In sys/soundcard.h
to see its fields.
.It Fa ci
-OSS audio card information. This structure is also defined in
+OSS audio card information.
+This structure is also defined in
.In sys/soundcard.h .
.It Fa name
Path to the mixer (e.g /dev/mixer0).
@@ -158,40 +159,43 @@
File descriptor returned when the mixer is opened in
.Fn mixer_open .
.It Fa unit
-Audio card unit. Since each mixer device maps to a pcmX device,
+Audio card unit.
+Since each mixer device maps to a pcmX device,
.Ar unit
-is always equal to the number of that pcmX device. For example, if the audio
-device's number is 0 (i.e pcm0), then
+is always equal to the number of that pcmX device.
+For example, if the audio device's number is 0 (i.e pcm0), then
.Ar unit
-is 0 as well. This number is useful when checking if the mixer's audio
-card is the default one.
+is 0 as well.
+This number is useful when checking if the mixer's audio card is the default one.
.It Fa ndev
Number of devices in
.Ar devs .
.It Fa devmask
-Bit mask containing all supported devices for the mixer. For example
-if device 10 is supported, then the 10th bit in the mask will be set. By default,
+Bit mask containing all supported devices for the mixer.
+For example, if device 10 is supported, then the 10th bit in the mask will be set.
+By default,
.Fn mixer_open
stores only the supported devices in devs, so it's very unlikely this mask will
be needed.
.It Fa mutemask
-Bit mask containing all muted devices. The logic is the same as with
+Bit mask containing all muted devices.
+The logic is the same as with
.Ar devmask .
.It Fa recmask
-Bit mask containing all recording devices. Again, same logic as with the
-other masks.
+Bit mask containing all recording devices.
+Again, same logic as with the other masks.
.It Fa recsrc
-Bit mask containing all recording sources. Yes, same logic again.
+Bit mask containing all recording sources.
+Yes, same logic again.
.It Fa mode
-Bit mask containing the supported modes for this audio device. It holds the value
-of the
+Bit mask containing the supported modes for this audio device.
+It holds the value of the
.Ar dev.pcm.X.mode
sysctl.
.It Fa f_default
Flag which tells whether the mixer's audio card is the default one.
.El
.Ss Mixer device
-.Pp
Each mixer device stored in a mixer is described as follows:
.Bd -literal
struct mix_dev {
@@ -217,7 +221,8 @@
.It Fa parent_mixer
Pointer to the mixer the device is attached to.
.It Fa name
-Device name given by the OSS API. Devices can have one of the following names:
+Device name given by the OSS API.
+Devices can have one of the following names:
.Bd -ragged
vol, bass, treble, synth, pcm, speaker, line, mic, cd, mix,
pcm2, rec, igain, ogain, line1, line2, line3, dig1, dig2, dig3,
@@ -229,10 +234,11 @@
This number is used to check against the masks defined in the
.Ar mixer
structure.
-.It Fa left, right
-Left and right-ear volumes. Although the OSS API stores volumes in integers from
-0-100, we normalize them to 32-bit floating point numbers. However, the volumes
-can be denormalized using the
+.It Fa left right
+Left and right-ear volumes.
+Although the OSS API stores volumes in integers from 0-100, \
+we normalize them to 32-bit floating point numbers.
+However, the volumes can be denormalized using the
.Ar MIX_VOLDENORM
macro if needed.
.It Fa nctl
@@ -241,9 +247,8 @@
A tail queue containing user-defined mixer controls.
.El
.Ss User-defined mixer controls
-.Pp
-Each mixer device can have user-defined controls. The control structure
-is defined as follows:
+Each mixer device can have user-defined controls.
+The control structure is defined as follows:
.Bd -literal
struct mix_ctl {
struct mix_dev *parent_dev; /* parent device */
@@ -260,41 +265,46 @@
.It Fa parent_dev
Pointer to the device the control is attached to.
.It Fa id
-Control ID assigned by the caller. Even though the library will
-report it, care has to be taken to not give a control the same ID in case
-the caller has to choose controls using their ID.
+Control ID assigned by the caller.
+Even though the library will report it, care has to be taken to not give \
+a control the same ID in case the caller has to choose controls using their ID.
.It Fa name
-Control name. As with
+Control name.
+As with
.Ar id ,
the caller has to make sure the same name is not used more than once.
.It Fa mod
-Function pointer to a control modification function. As in
+Function pointer to a control modification function.
+As in
.Xr mixer 8 ,
-each mixer control's values can be modified. For example, if we have a
-volume control, the
+each mixer control's values can be modified.
+For example, if we have a volume control, the
.Ar mod
function will be responsible for handling volume changes.
.It Fa print
Function pointer to a control print function.
.El
.Ss Opening and closing the mixer
-.Pp
The application must first call the
.Fn mixer_open
-function to obtain a handle to the device, which is used as an argument
-in most other functions and macros. The parameter
+function to obtain a handle to the device, which is used as an argument \
+in most other functions and macros.
+The parameter
.Ar name
-specifies the path to the mixer. OSS mixers are stored under
+specifies the path to the mixer.
+OSS mixers are stored under
.Ar /dev/mixerN
where
.Ar N
-is the number of the mixer device. Each device maps to an actual
+is the number of the mixer device.
+Each device maps to an actual
.Ar pcm
audio card, so
.Ar /dev/mixer0
is the mixer for
.Ar pcm0 ,
-and so on. If
+and so on.
+If
.Ar name
is
.Ar NULL
@@ -305,30 +315,30 @@
.Pp
The
.Fn mixer_close
-function frees resources and closes the mixer device. It's a good practice to
-always call it when the application is done using the mixer.
+function frees resources and closes the mixer device.
+It's a good practice to always call it when the application is done using the mixer.
.Ss Manipulating the mixer
-.Pp
The
.Fn mixer_get_dev
and
.Fn mixer_get_dev_byname
-functions select a mixer device, either by its number or by its name
-respectively. The mixer structure keeps a list of all the devices, but only
-one can be manipulated at a time. Each time a new device is to be manipulated,
-one of the two functions has to be called.
+functions select a mixer device, either by its number or by its name respectively.
+The mixer structure keeps a list of all the devices, but only \
+one can be manipulated at a time.
+Each time a new device is to be manipulated, one of the two functions has to be called.
.Pp
The
.Fn mixer_set_vol
-function changes the volume of the selected mixer device. The
+function changes the volume of the selected mixer device.
+The
.Ar vol
-parameter is a structure that stores the left and right volumes of a given
-device. The allowed volume values are between MIX_VOLMIN (0.0) and
-MIX_VOLMAX (1.0).
+parameter is a structure that stores the left and right volumes of a given device.
+The allowed volume values are between MIX_VOLMIN (0.0) and MIX_VOLMAX (1.0).
.Pp
The
.Fn mixer_set_mute
-function modifies the mute of a selected device. The
+function modifies the mute of a selected device.
+The
.Ar opt
parameter has to be one of the following options:
.Bl -tag -width MIX_TOGGLEMUTE -offset indent
@@ -342,8 +352,9 @@
.Pp
The
.Fn mixer_mod_recsrc
-function modifies a recording device. The selected device has to be
-a recording device, otherwise the function will fail. The
+function modifies a recording device.
+The selected device has to be a recording device, otherwise the function will fail.
+The
.Ar opt
parameter has to be one of the following options:
.Bl -tag -width MIX_REMOVERECSRC -offset indent
@@ -361,16 +372,17 @@
.Fn mixer_get_dunit
and
.Fn mixer_set_dunit
-functions get and set the default audio card in the system. Although this is
-not really a mixer feature, it's useful to have instead of having to use
-the
+functions get and set the default audio card in the system.
+Although this is not really a mixer feature, it's useful to have instead of \
+having to use the
.Xr sysctl 3
controls.
.Pp
The
.Fn mixer_get_mode
-function returns the playback/recording mode of the audio device the mixer
-belongs to. The available values are the following:
+function returns the playback/recording mode of the audio device the mixer \
+belongs to.
+The available values are the following:
.Bl -tag -width "MIX_STATUS_PLAY | MIX_STATUS_REC" -offset indent
.It Dv MIX_STATUS_NONE
Neither playback nor recording.
@@ -388,9 +400,9 @@
.Pp
The
.Fn MIX_ISDEV
-macro checks if a device is actually a valid device for a given mixer. It's very
-unlikely that this macro will ever be needed since the library stores only
-valid devices by default.
+macro checks if a device is actually a valid device for a given mixer.
+It's very unlikely that this macro will ever be needed since the library \
+stores only valid devices by default.
.Pp
The
.Fn MIX_ISMUTE
@@ -406,8 +418,8 @@
.Pp
The
.Fn MIX_VOLNORM
-macro normalizes a value to 32-bit floating point number. It's used
-to normalize the volumes read from the OSS API.
+macro normalizes a value to 32-bit floating point number.
+It's used to normalize the volumes read from the OSS API.
.Pp
The
.Fn MIX_VOLDENORM
@@ -415,7 +427,6 @@
.Ft mix_dev
structure.
.Ss Defining and using mixer controls
-.Pp
The
.Fn mix_add_ctl
function creates a control and attaches it to the device specified in the
@@ -438,7 +449,8 @@
.Fn mixer_get_ctl
function searches for a control in the device specified in the
.Ar d
-argument and returns a pointer to it. The search is done using the control's ID.
+argument and returns a pointer to it.
+The search is done using the control's ID.
.Pp
The
.Fn mixer_get_ctl_byname
@@ -446,7 +458,6 @@
.Fn mixer_get_ctl
but the search is done using the control's name.
.Sh RETURN VALUES
-.Pp
The
.Fn mixer_open
function returns the newly created handle on success and NULL on failure.
@@ -530,10 +541,10 @@
(void)mixer_close(m);
.Ed
.Sh SEE ALSO
-.Xr mixer 8 ,
-.Xr sound 4 ,
+.Xr queue 3 ,
.Xr sysctl 3 ,
-.Xr queue 3
+.Xr sound 4 ,
+.Xr mixer 8
and
.Xr errno 2
.Sh AUTHORS
diff --git a/usr.sbin/mixer/mixer.8 b/usr.sbin/mixer/mixer.8
--- a/usr.sbin/mixer/mixer.8
+++ b/usr.sbin/mixer/mixer.8
@@ -21,7 +21,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd March 13, 2022
+.Dd March 18, 2022
.Dt MIXER 8
.Os
.Sh NAME
@@ -32,7 +32,7 @@
.Op Fl f Ar device
.Op Fl d Ar unit
.Op Fl os
-.Op Ar dev Ns Op Cm \&. Ns Ar control Ns Op Cm \&= Ns Ar value
+.Op Ar dev Ns Op . Ns Ar control Ns Op = Ns Ar value
.Ar ...
.Nm
.Op Fl d Ar unit
@@ -48,22 +48,19 @@
The options are as follows:
.Bl -tag -width "-f device"
.It Fl a
-Print the values for all mixer devices available in the system
-.Pq see Sx FILES .
+Print the values for all mixer devices available in the system (see FILES).
.It Fl d Ar unit
Change the default audio card to
.Ar unit .
The unit has to be an integer value.
-To see what unit values are available, look
-at the number each mixer device has by running
+To see what unit values are available, look at the number each mixer device has by running
.Nm .
.It Fl f Ar device
Open
.Ar device
-as the mixer device
-.Pq see Sx FILES .
+as the mixer device (see FILES).
.It Fl h
-Print a help message.
+Print a help message to stderr.
.It Fl o
Print mixer values in a format suitable for use inside scripts.
The mixer's header (name, audio card name, ...) will not be printed.
@@ -73,14 +70,9 @@
.Pp
The list of mixer devices that may be modified are:
.Bd -ragged -offset indent
-.Cm vol , bass , treble , synth , pcm , speaker , line , mic , cd , mix ,
-.Cm pcm2 , rec ,
-.Cm igain , ogain ,
-.Cm line1 , line2 , line3 ,
-.Cm dig1 , dig2 , dig3 ,
-.Cm phin , phout , video , radio ,
-and
-.Cm monitor .
+vol, bass, treble, synth, pcm, speaker, line, mic, cd, mix,
+pcm2, rec, igain, ogain, line1, line2, line3, dig1, dig2, dig3,
+phin, phout, video, radio, and monitor.
.Ed
.Pp
Not all mixer devices are available.
@@ -99,43 +91,33 @@
.Pp
Commands use the following format:
.Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent
-.It Sy Name Ta Sy Action
-.It Ar dev Ta Display all controls
-.It Ar dev Ns Cm \&. Ns Ar control Ta Display only the specified control
-.It Ar dev Ns Cm \&. Ns Ar control Ns Cm \&= Ns Ar value Ta Set control value
+.It Sy "Name Action"
+.It "dev Display all controls"
+.It "dev.control Display only the specified control"
+.It "dev.control=value Set control value"
.El
.Pp
The available controls are as follows (replace
.Ar dev
with one of the available devices):
-.Sm off
.Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent
-.It Sy Name Ta Sy Value
-.It Ar dev Cm .volume Ta Xo
-.Ar vol |
-.Oo Cm \&+ | Cm \&- Oc Ar lvol
-.Oo Cm \&: Oo Cm \&+ | Cm \&- Oc Ar rvol Oc
-.Xc
-.It Ar dev Cm .mute Ta Cm 0 | 1 | ^
-.It Ar dev Cm .recsrc Ta Cm ^ | + | - | =
+.It Sy "Name Value"
+.It "dev.volume [[+|-]lvol[:[+|-]rvol]]"
+.It "dev.mute {0|1|^}"
+.It "dev.recsrc {+|-|^|=}"
.El
-.Sm on
.Pp
The
-.Ar dev Ns Cm .volume
+.Ar dev.volume
control modifies a device's volume.
The optional
.Ar lvol
and/or
.Ar rvol
values have to be specified.
-The values have to be normalized 32-bit floats,
-from 0.0 to 1.0 inclusivly.
-If no
-.Ql \&.
-character is present, the value is treated
-like a percentage, for backwards compatibility.
-If the left or right volume values are prefixed with
+The values have to be normalized 32-bit floats, from 0.0 to 1.0 inclusivly.
+If no "." character is present, the value is treated like a percentage, for backwards compatibility.
+If the the left or right volume values are prefixed with
.Cm +
or
.Cm - ,
@@ -143,32 +125,32 @@
current settings by the amount specified.
.Pp
The
-.Ar dev Ns Cm .mute
+.Ar dev.mute
control (un)mutes a device.
The following values are available:
.Bl -tag -width = -offset indent
.It Cm 0
unmutes
-.Ar dev
+.Ar dev .
.It Cm 1
mutes
-.Ar dev
+.Ar dev .
.It Cm ^
toggles the mute of
-.Ar dev
+.Ar dev .
.El
.Pp
The
-.Ar dev Ns Cm .recsrc
+.Ar dev.recsrc
control modifies the recording sources of a mixer.
.Nm
marks devices which can be used as a recording source with
-.Sy rec .
+.Ar rec .
Recording sources are marked with
-.Sy src .
+.Ar src .
To modify the recording source you can use one of the following modifiers
on a
-.Sy rec
+.Ar rec
device:
.Bl -tag -width = -offset indent
.It Cm ^
@@ -195,9 +177,9 @@
is the number of that device, for example
.Ar /dev/mixer0 .
PCM cards and mixers have a 1:1 relationship, which means that
-.Pa /dev/mixer0
+.Ar mixer0
is the mixer for
-.Pa /dev/pcm0
+.Ar pcm0
and so on.
By default,
.Nm
@@ -205,8 +187,8 @@
in the form of
.Ar pcmN:mixer .
The
-.Pa /dev/mixer
-file, although it does not exist in the filesystem, points to the default
+.Ar /dev/mixer
+file, although it doesn't exist in the filesystem, points to the default
mixer device and is the file
.Nm
opens when the
@@ -215,45 +197,45 @@
.El
.Sh EXAMPLES
Change the volume for the
-.Cm vol
+.Ar vol
device of the
-.Pa /dev/mixer0
+.Ar /dev/mixer0
mixer device to 0.65:
-.Bd -literal -offset indent
-$ mixer -f /dev/mixer0 vol.volume=0.65
-.Ed
+.Bl -tag -width Ds -offset indent
+.It $ mixer -f /dev/mixer0 vol.volume=0.65
+.El
.Pp
Increase the
-.Cm mic
+.Ar mic
device's left volume by 0.10 and decrease the right
volume by 0.05:
-.Bd -literal -offset indent
-$ mixer mic.volume=+0.10:-0.05
-.Ed
+.Bl -tag -width Ds -offset indent
+.It $ mixer mic.volume=+0.10:-0.05
+.El
.Pp
Toggle the mute for
-.Cm vol :
-.Bd -literal -offset indent
-$ mixer vol.mute=^
-.Ed
+.Ar vol :
+.Bl -tag -width Ds -offset indent
+.It $ mixer vol.mute=^
+.El
.Pp
Set
-.Cm mic
+.Ar mic
and toggle
-.Cm line
+.Ar line
recording sources:
-.Bd -literal -offset indent
-$ mixer mic.recsrc=+ line.recsrc=^
-.Ed
+.Bl -tag -width Ds -offset indent
+.It $ mixer mic.recsrc=+ line.recsrc=^
+.El
.Pp
Dump
-.Pa /dev/mixer0
-information to a file and retrieve back later:
-.Bd -literal -offset indent
-$ mixer -f /dev/mixer0 -o > info
-\&...
-$ mixer -f /dev/mixer0 `cat info`
-.Ed
+.Ar /dev/mixer0
+information to a file and retrieve back later
+.Bl -tag -width Ds -offset indent
+.It $ mixer -f /dev/mixer0 -o > info
+.It ...
+.It $ mixer -f /dev/mixer0 `cat info`
+.El
.Sh SEE ALSO
.Xr mixer 3 ,
.Xr sound 4 ,

File Metadata

Mime Type
text/plain
Expires
Sun, Feb 15, 6:53 PM (10 h, 22 s)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28752417
Default Alt Text
D34603.id103992.diff (17 KB)

Event Timeline