1ALSACTL_INIT(7) alsactl init ALSACTL_INIT(7)
2
6 alsactl_init - alsa control management - initialization
7
9 "alsactl init" provides soundcard specific initialization.
10
12 All "alsactl init" configuration files are placed in
13 /usr/share/alsa/init/ directory. The top level configuration file is
14 /usr/share/alsa/init/00main. The default top-level file can be also
15 specified using -i or --initfile parameter for the alsactl tool. Every
16 file consists of a set of lines of text. All empty lines or lines
17 beginning with '#' will be ignored.
18 Rules files
20 The "alsactl init" rules are read from the files located in the
21 /usr/share/alsa/init/*. The top level configuration file is
22 /usr/share/alsa/init/00main. Every line in the rules file contains at
23 least one key value pair. There are two kind of keys, match and
24 assignment keys. If all match keys are matching against its value, the
25 rule gets applied and the assign keys get the specified value assigned.
26 A rule may consists of a list of one or more key value pairs separated
28 by a comma. Each key has a distinct operation, depending on the used
29 operator. Valid operators are:
30 ==
32 Compare for equality.
33 !=
35 Compare for non-equality.
36 =
38 Assign a value to a key. Keys that represent a list, are reset and
39 only this single value is assigned.
40 +=
42 Add the value to a key that holds a list of entries.
43 :=
45 Assign a value to a key finally; disallow any later changes, which
46 may be used to prevent changes by any later rules.
47 The following key names can be used to match against device properties:
49 CARDINDEX
51 Match the card index of the ALSA driver.
52 CTL{attribute}
54 Set or test universal control attribute. Possible attributes:
55 numid
57 Numeric control identification.
58 iface, interface
60 Control interface name (CARD, HWEDEP, MIXER, PCM, RAWMIDI,
61 TIMER, SEQUENCER)
62 subdev, subdevice
64 Subdevice number.
65 name
67 Control name
68 index
70 Control index
71 type
73 Control type (BOOLEAN, INTEGER, INTEGER64, ENUMERATED, BYTES,
74 IEC958)
75 attr, attribute
77 Attributes (stored in a string - use match characters * and ?):
78 r
80 control is readable
81 w
83 control is writable
84 v
86 control is volatile
87 i
89 control is inactive
90 l
92 control is locked
93 R
95 control is TLV readable
96 W
98 control is TLV writable
99 C
101 control is TLV commandable
102 o
104 process is owner of this control
105 u
107 control created in user space
108 owner
110 Control owner process PID number
111 count
113 Control count of values
114 min
116 Value range - minimum value
117 max
119 Value range - maximum value
120 step
122 Value range - step value
123 dBmin
125 Value range - minimum dB value
126 dBmax
128 Value range - maximum dB value
129 items
131 Enumerated value - number of text items
132 enums
134 Enumerated value - list of text names stored between '|'
135 character
136 value
138 Value of control stored to a string delimited by comma (,).
139 do_search
141 Search for a control. Value "1" is returned if a control was
142 found. The CTL{name} key might contain match characters * and
143 ?. An control index might be specified as first argument
144 starting from zero (e.g. CTL{do_search 2}="1").
145 do_count
147 Search for a controls and return total count of matched ones.
148 The CTL{name} key might contain match characters * and ?.
149 CONFIG{sysfs_device}
151 The relative path to sysfs subsystem specifying the root directory
152 of a soundcard device. Usually, it should be set to
153 "/class/sound/card$cardinfo{card}/device".
154 ATTR{filename}
156 Match sysfs attribute values of the soundcard device. The relative
157 path to sysfs tree must be defined by CONFIG{sysfs_device} key.
158 Trailing whitespace in the attribute values is ignored, if the
159 specified match value does not contain trailing whitespace itself.
160 Depending on the type of operator, this key is also used to set the
161 value of a sysfs attribute.
162 ENV{key}
164 Match against the value of an environment variable. Up to five ENV
165 keys can be specified per rule. Depending on the type of operator,
166 this key is also used to export a variable to the environment.
167 PROGRAM
169 Execute external program. The key is true, if the program returns
170 without exit code zero. The whole event environment is available to
171 the executed program. The program's output printed to stdout is
172 available for the RESULT key.
173 Several buildin commands are available:
175 __ctl_search
177 Search for a control. The CTL{name} key might contain match
178 characters * and ?. An control index might be specified as
179 first argument starting from zero (e.g. PROGRAM="__ctl_search
180 2").
181 __ctl_count
183 Search for a controls and return total count of matched ones.
184 The CTL{name} key might contain match characters * and ?.
185 RESULT
187 Match the returned string of the last PROGRAM call. This key can be
188 used in the same or in any later rule after a PROGRAM call.
189 Most of the fields support a shell style pattern matching. The
191 following pattern characters are supported:
192 *
194 Matches zero, or any number of characters.
195 ?
197 Matches any single character.
198 []
200 Matches any single character specified within the brackets. For
201 example, the pattern string 'tty[SR]' would match either 'ttyS' or
202 'ttyR'. Ranges are also supported within this match with the '-'
203 character. For example, to match on the range of all digits, the
204 pattern [0-9] would be used. If the first character following the
205 '[' is a '!', any characters not enclosed are matched.
206 The following keys can get values assigned:
208 CTL{numid}, CTL{iface}, CTL{device}, CTL{subdev}, CTL{name},
210 CTL{index},
211 Select universal control element.
212 CTL{value}
214 Value is set (written) also to soundcard's control device and
215 RESULT key is set to errno code. The result of set operation is
216 always true (it means continue with next key on line).
217 CTL{values}
219 Value is set (written) also to soundcard's control device (all
220 control values are set to specified value) and RESULT key is set to
221 errno code. The result of set operation is always true (it means
222 continue with next key on line).
223 CTL{write}
225 Value is set (written) also to soundcard's control device (all
226 control values are set to specified value). The result of set
227 operation is true when operation succeed (it means continue with
228 next key on line).
229 ENV{key}
231 Export a variable to the environment. Depending on the type of
232 operator, this key is also to match against an environment
233 variable.
234 RESULT
236 Set RESULT variable. Note that PROGRAM also sets this variable, but
237 setting this variable manually might be useful to change code
238 execution order (included files).
239 LABEL
241 Named label where a GOTO can jump to.
242 GOTO
244 Jumps to the next LABEL with a matching name. The goto cannot jump
245 backward.
246 INCLUDE
248 Include the specified filename or files in specified directory.
249 When a directory is specified, only the files with the extension
251 ".conf" are read. Also they are read in the alphabetical order.
252 Thus it's highly recommended to use some number prefix (e.g.
253 "01-something.conf") to assure the order of execucions.
254 ACCESS
256 Check if specified file or directory exists
257 CONFIG{sysfs_device}
259 The relative path to sysfs subsystem specifying the root directory
260 of a soundcard device. Usually, it should be set to
261 "/class/sound/card$cardinfo{card}/device".
262 PRINT
264 PRINT value to stdout.
265 ERROR
267 PRINT value to stderr.
268 EXIT
270 Exit immediately and set program exit code to value (should be
271 integer). If value is "return" string, parser leaves current
272 included file and returns to parent configuration file.
273 The PROGRAM, RESULT, CTL{value}, PRINT, ERROR, EXIT, CONFIG{} fields
275 support simple printf-like string substitutions. It allows the use of
276 the complete environment set by earlier matching rules. For all other
277 fields, substitutions are applied while the individual rule is being
278 processed. The available substitutions are:
279 $cardinfo{attribute}, %i{attribute}
281 See CARDINFO{} for more details.
282 $ctl{attribute}, %C{attribute}
284 See CTL{} for more details.
285 $attr{file}, %s{file}
287 The value of a sysfs attribute found at the device, where all keys
288 of the rule have matched. If the attribute is a symlink, the last
289 element of the symlink target is returned as the value.
290 $env{key}, %E{key}
292 The value of an environment variable.
293 $result, %c
295 The string returned by the external program requested with PROGRAM.
296 A single part of the string, separated by a space character may be
297 selected by specifying the part number as an attribute: %c{N}. If
298 the number is followed by the '+' char this part plus all remaining
299 parts of the result string are substituted: %c{N+}
300 $sysfsroot, %r
302 Root directory where sysfs file-system is mounted. Ususally, this
303 value is just "/sys".
304 $config{key}, %g{key}
306 The value of a configuration variable. See CONFIG{} for more
307 details.
308 %%
310 The '%' character itself.
311 $$
313 The '$' character itself.
314 The count of characters to be substituted may be limited by specifying
316 the format length value. For example, '%3s{file}' will only insert the
317 first three characters of the sysfs attribute
318
320 Written by Jaroslav Kysela <perex@perex.cz>
321 Some portions are written by Greg Kroah-Hartman <greg@kroah.com> and
323 Kay Sievers <kay.sievers@vrfy.org>.
324
326 alsactl(1)
327alsactl July 2008 ALSACTL_INIT(7)