| <?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 specified filename or all files in specified directory</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> |
