mirror of
https://github.com/alsa-project/alsa-utils
synced 2024-11-09 17:45:41 +01:00
c68a3d02d1
When alsactl init is invoked and a directory path is passed to INCLUDE command in the config file, read only *.conf files in that directory. This will avoid reading backup files or invalid files that have been created accidentally. Also by using scandir() with alphasort(), alsactl reads the files in alphabetical order. Thus it's highly recommended to use some number prefix to the file name for assuring the order. Signed-off-by: Takashi Iwai <tiwai@suse.de>
633 lines
26 KiB
XML
633 lines
26 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<article>
|
|
<section>
|
|
<title>alsactl init</title>
|
|
<refentry>
|
|
<refentryinfo>
|
|
<title>alsactl init</title>
|
|
<date>July 2008</date>
|
|
<productname>alsactl</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>alsactl_init</refentrytitle>
|
|
<manvolnum>7</manvolnum>
|
|
<refmiscinfo class="version"></refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>alsactl init</refname>
|
|
<refpurpose>alsa control management - initialization</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1><title>DESCRIPTION</title>
|
|
<para>"alsactl init" provides soundcard specific initialization.</para>
|
|
</refsect1>
|
|
|
|
<refsect1><title>CONFIGURATION</title>
|
|
<para>All "alsactl init" configuration files are placed in
|
|
<filename>/usr/share/alsa/init/</filename> directory. The top level
|
|
configuration file is <filename>/usr/share/alsa/init/00main</filename>.
|
|
The default top-level file can be also specified using -i or
|
|
--initfile parameter for the alsactl tool.
|
|
Every file consists of a set of lines of text. All empty lines or
|
|
lines beginning with '#' will be ignored.</para>
|
|
|
|
<refsect2><title>Rules files</title>
|
|
<para>The "alsactl init" rules are read from the files located
|
|
in the <filename>/usr/share/alsa/init/*</filename>. The top
|
|
level configuration file is <filename>/usr/share/alsa/init/00main</filename>.
|
|
Every line in the rules file contains at least one key value pair.
|
|
There are two kind of keys, match and assignment keys. If all match
|
|
keys are matching against its value, the rule gets applied and the
|
|
assign keys get the specified value assigned.</para>
|
|
|
|
<para>A rule may consists of a list of one or more key value pairs
|
|
separated by a comma. Each key has a distinct operation, depending
|
|
on the used operator. Valid operators are:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>==</option></term>
|
|
<listitem>
|
|
<para>Compare for equality.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>!=</option></term>
|
|
<listitem>
|
|
<para>Compare for non-equality.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>=</option></term>
|
|
<listitem>
|
|
<para>Assign a value to a key. Keys that represent a list,
|
|
are reset and only this single value is assigned.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>+=</option></term>
|
|
<listitem>
|
|
<para>Add the value to a key that holds a list
|
|
of entries.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>:=</option></term>
|
|
<listitem>
|
|
<para>Assign a value to a key finally; disallow any
|
|
later changes, which may be used to prevent changes by
|
|
any later rules.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>The following key names can be used to match against device
|
|
properties:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>CARDINDEX</option></term>
|
|
<listitem>
|
|
<para>Match the card index of the ALSA driver.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>CTL{<replaceable>attribute</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Set or test universal control attribute. Possible
|
|
attributes:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>numid</option></term>
|
|
<listitem>
|
|
<para>Numeric control identification.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>iface</option>, <option>interface</option></term>
|
|
<listitem>
|
|
<para>Control interface name (CARD, HWEDEP, MIXER, PCM, RAWMIDI, TIMER, SEQUENCER)</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdev</option>, <option>subdevice</option></term>
|
|
<listitem>
|
|
<para>Subdevice number.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>name</option></term>
|
|
<listitem>
|
|
<para>Control name</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>index</option></term>
|
|
<listitem>
|
|
<para>Control index</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>type</option></term>
|
|
<listitem>
|
|
<para>Control type (BOOLEAN, INTEGER, INTEGER64, ENUMERATED, BYTES, IEC958)</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>attr</option>, <option>attribute</option></term>
|
|
<listitem>
|
|
<para>Attributes (stored in a string - use match characters * and ?):</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>r</option></term>
|
|
<listitem>
|
|
<para>control is readable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>w</option></term>
|
|
<listitem>
|
|
<para>control is writable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>v</option></term>
|
|
<listitem>
|
|
<para>control is volatile</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>i</option></term>
|
|
<listitem>
|
|
<para>control is inactive</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>l</option></term>
|
|
<listitem>
|
|
<para>control is locked</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>R</option></term>
|
|
<listitem>
|
|
<para>control is TLV readable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>W</option></term>
|
|
<listitem>
|
|
<para>control is TLV writable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>C</option></term>
|
|
<listitem>
|
|
<para>control is TLV commandable</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>o</option></term>
|
|
<listitem>
|
|
<para>process is owner of this control</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>u</option></term>
|
|
<listitem>
|
|
<para>control created in user space</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>owner</option></term>
|
|
<listitem>
|
|
<para>Control owner process PID number</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>count</option></term>
|
|
<listitem>
|
|
<para>Control count of values</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>min</option></term>
|
|
<listitem>
|
|
<para>Value range - minimum value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>max</option></term>
|
|
<listitem>
|
|
<para>Value range - maximum value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>step</option></term>
|
|
<listitem>
|
|
<para>Value range - step value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dBmin</option></term>
|
|
<listitem>
|
|
<para>Value range - minimum dB value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>dBmax</option></term>
|
|
<listitem>
|
|
<para>Value range - maximum dB value</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>items</option></term>
|
|
<listitem>
|
|
<para>Enumerated value - number of text items</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>enums</option></term>
|
|
<listitem>
|
|
<para>Enumerated value - list of text names stored between '|' character</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>value</option></term>
|
|
<listitem>
|
|
<para>Value of control stored to a string delimited by
|
|
comma (,).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>do_search</option></term>
|
|
<listitem>
|
|
<para>Search for a control. Value "1" is returned
|
|
if a control was found. The CTL{name} key might
|
|
contain match characters * and ?. An control index
|
|
might be specified as first argument starting from
|
|
zero (e.g. CTL{do_search 2}="1").</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>do_count</option></term>
|
|
<listitem>
|
|
<para>Search for a controls and return total count
|
|
of matched ones. The CTL{name} key might contain match
|
|
characters * and ?.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>CONFIG{sysfs_device}</option></term>
|
|
<listitem>
|
|
<para>The relative path to sysfs subsystem specifying
|
|
the root directory of a soundcard device. Usually,
|
|
it should be set to "/class/sound/card$cardinfo{card}/device".
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ATTR{<replaceable>filename</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Match sysfs attribute values of the soundcard device.
|
|
The relative path to sysfs tree must be defined by
|
|
CONFIG{sysfs_device} key. Trailing whitespace in the attribute
|
|
values is ignored, if the specified match value does
|
|
not contain trailing whitespace itself. Depending on
|
|
the type of operator, this key is also used to set
|
|
the value of a sysfs attribute.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Match against the value of an environment variable. Up
|
|
to five <option>ENV</option> keys can be specified per rule.
|
|
Depending on the type of operator, this key is also used
|
|
to export a variable to the environment.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>PROGRAM</option></term>
|
|
<listitem>
|
|
<para>Execute external program. The key is true, if
|
|
the program returns without exit code zero. The whole event
|
|
environment is available to the executed program. The
|
|
program's output printed to stdout is available for
|
|
the RESULT key.</para>
|
|
<para>Several buildin commands are available:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>__ctl_search</option></term>
|
|
<listitem>
|
|
<para>Search for a control. The CTL{name} key might
|
|
contain match characters * and ?. An control index
|
|
might be specified as first argument starting from
|
|
zero (e.g. PROGRAM="__ctl_search 2").</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>__ctl_count</option></term>
|
|
<listitem>
|
|
<para>Search for a controls and return total count
|
|
of matched ones. The CTL{name} key might contain match
|
|
characters * and ?.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>RESULT</option></term>
|
|
<listitem>
|
|
<para>Match the returned string of the last PROGRAM call.
|
|
This key can be used in the same or in any later rule
|
|
after a PROGRAM call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>Most of the fields support a shell style pattern matching.
|
|
The following pattern characters are supported:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>*</option></term>
|
|
<listitem>
|
|
<para>Matches zero, or any number of characters.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>?</option></term>
|
|
<listitem>
|
|
<para>Matches any single character.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>[]</option></term>
|
|
<listitem>
|
|
<para>Matches any single character specified within
|
|
the brackets. For example, the pattern string 'tty[SR]'
|
|
would match either 'ttyS' or 'ttyR'. Ranges are also
|
|
supported within this match with the '-' character.
|
|
For example, to match on the range of all digits,
|
|
the pattern [0-9] would be used. If the first character
|
|
following the '[' is a '!', any characters
|
|
not enclosed are matched.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>The following keys can get values assigned:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>CTL{numid}</option>, <option>CTL{iface}</option>,
|
|
<option>CTL{device}</option>, <option>CTL{subdev}</option>,
|
|
<option>CTL{name}</option>, <option>CTL{index}</option>,
|
|
</term>
|
|
<listitem>
|
|
<para>Select universal control element.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CTL{value}</option></term>
|
|
<listitem>
|
|
<para>Value is set (written) also to soundcard's control
|
|
device and RESULT key is set to errno code. The result of
|
|
set operation is always true (it means continue with
|
|
next key on line).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CTL{values}</option></term>
|
|
<listitem>
|
|
<para>Value is set (written) also to soundcard's control
|
|
device (all control values are set to specified value) and
|
|
RESULT key is set to errno code. The result of
|
|
set operation is always true (it means continue with
|
|
next key on line).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>CTL{write}</option></term>
|
|
<listitem>
|
|
<para>Value is set (written) also to soundcard's control
|
|
device (all control values are set to specified value).
|
|
The result of set operation is true when operation
|
|
succeed (it means continue with next key on line).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>Export a variable to the environment. Depending on the type of operator,
|
|
this key is also to match against an environment variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>RESULT</option></term>
|
|
<listitem>
|
|
<para>Set RESULT variable. Note that PROGRAM also sets
|
|
this variable, but setting this variable manually
|
|
might be useful to change code execution order (included
|
|
files).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>LABEL</option></term>
|
|
<listitem>
|
|
<para>Named label where a GOTO can jump to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>GOTO</option></term>
|
|
<listitem>
|
|
<para>Jumps to the next LABEL with a matching name.
|
|
The goto cannot jump backward.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>INCLUDE</option></term>
|
|
<listitem>
|
|
<para>Include the specified filename or files in specified directory.
|
|
</para>
|
|
<para>
|
|
When a directory is specified, only the files with the
|
|
extension ".conf" are read.
|
|
Also they are read in the alphabetical order.
|
|
Thus it's highly recommended to use some number prefix
|
|
(e.g. "01-something.conf") to assure the order of execucions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ACCESS</option></term>
|
|
<listitem>
|
|
<para>Check if specified file or directory exists</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>CONFIG{sysfs_device}</option></term>
|
|
<listitem>
|
|
<para>The relative path to sysfs subsystem specifying
|
|
the root directory of a soundcard device. Usually,
|
|
it should be set to "/class/sound/card$cardinfo{card}/device".
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>PRINT</option></term>
|
|
<listitem>
|
|
<para>PRINT value to stdout.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ERROR</option></term>
|
|
<listitem>
|
|
<para>PRINT value to stderr.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>EXIT</option></term>
|
|
<listitem>
|
|
<para>Exit immediately and set program exit code to value
|
|
(should be integer). If value is "return" string,
|
|
parser leaves current included file and returns to parent
|
|
configuration file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>The <option>PROGRAM</option>, <option>RESULT</option>,
|
|
<option>CTL{value}</option>,
|
|
<option>PRINT</option>, <option>ERROR</option>,
|
|
<option>EXIT</option>, <option>CONFIG{}</option>
|
|
fields support simple printf-like string substitutions.
|
|
It allows the use of the complete environment set by earlier matching
|
|
rules. For all other fields, substitutions are applied while the individual rule is
|
|
being processed. The available substitutions are:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>$cardinfo{<replaceable>attribute</replaceable>}</option>, <option>%i{<replaceable>attribute</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>See CARDINFO{} for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$ctl{<replaceable>attribute</replaceable>}</option>, <option>%C{<replaceable>attribute</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>See CTL{} for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$attr{<replaceable>file</replaceable>}</option>, <option>%s{<replaceable>file</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>The value of a sysfs attribute found at the device, where
|
|
all keys of the rule have matched.
|
|
If the attribute is a symlink, the last element of the symlink target is
|
|
returned as the value.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$env{<replaceable>key</replaceable>}</option>, <option>%E{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>The value of an environment variable.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$result</option>, <option>%c</option></term>
|
|
<listitem>
|
|
<para>The string returned by the external program requested with PROGRAM.
|
|
A single part of the string, separated by a space character may be selected
|
|
by specifying the part number as an attribute: <option>%c{N}</option>.
|
|
If the number is followed by the '+' char this part plus all remaining parts
|
|
of the result string are substituted: <option>%c{N+}</option></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$sysfsroot</option>, <option>%r</option></term>
|
|
<listitem>
|
|
<para>Root directory where sysfs file-system is mounted.
|
|
Ususally, this value is just "/sys".</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$config{<replaceable>key</replaceable>}</option>, <option>%g{<replaceable>key</replaceable>}</option></term>
|
|
<listitem>
|
|
<para>The value of a configuration variable. See CONFIG{} for more details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>%%</option></term>
|
|
<listitem>
|
|
<para>The '%' character itself.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>$$</option></term>
|
|
<listitem>
|
|
<para>The '$' character itself.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>The count of characters to be substituted may be limited
|
|
by specifying the format length value. For example, '%3s{file}'
|
|
will only insert the first three characters of the sysfs
|
|
attribute</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1><title>AUTHOR</title>
|
|
<para>Written by Jaroslav Kysela <email>perex@perex.cz</email></para>
|
|
<para>Some portions are written by Greg Kroah-Hartman <email>greg@kroah.com</email> and
|
|
Kay Sievers <email>kay.sievers@vrfy.org</email>.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>SEE ALSO</title>
|
|
<para><citerefentry>
|
|
<refentrytitle>alsactl</refentrytitle><manvolnum>1</manvolnum>
|
|
</citerefentry></para>
|
|
</refsect1>
|
|
</refentry>
|
|
</section>
|
|
</article>
|