code.delx.au - pulseaudio/blob - man/pulseaudio.1.xml.in

   1 <?xml version="1.0"?><!--*-nxml-*-->
   2 <!DOCTYPE manpage SYSTEM "xmltoman.dtd">
   3 <?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
   4
   5 <!-- $Id$ -->
   6
   7 <!--
   8 This file is part of PulseAudio.
   9
  10 PulseAudio is free software; you can redistribute it and/or modify it
  11 under the terms of the GNU Lesser General Public License as
  12 published by the Free Software Foundation; either version 2.1 of the
  13 License, or (at your option) any later version.
  14
  15 PulseAudio is distributed in the hope that it will be useful, but WITHOUT
  16 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  17 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
  18 Public License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public
  21 License along with PulseAudio; if not, write to the Free Software
  22 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23 USA.
  24 -->
  25
  26 <manpage name="pulseaudio" section="1" desc="The PulseAudio Sound System">
  27
  28   <synopsis>
  29     <cmd>pulseaudio [<arg>options</arg>]</cmd>
  30     <cmd>pulseaudio <opt>--help</opt></cmd>
  31     <cmd>pulseaudio <opt>--dump-conf</opt></cmd>
  32     <cmd>pulseaudio <opt>--dump-modules</opt></cmd>
  33     <cmd>pulseaudio <opt>--dump-resample-methods</opt></cmd>
  34     <cmd>pulseaudio <opt>--cleanup-shm</opt></cmd>
  35     <cmd>pulseaudio <opt>--kill</opt></cmd>
  36     <cmd>pulseaudio <opt>--check</opt></cmd>
  37   </synopsis>
  38
  39   <description>
  40     <p>PulseAudio is a networked low-latency sound server for Linux, POSIX and Windows systems.</p>
  41   </description>
  42
  43   <options>
  44
  45     <option>
  46       <p><opt>-h | --help</opt></p>
  47
  48       <optdesc><p>Show help.</p></optdesc>
  49     </option>
  50
  51     <option>
  52       <p><opt>--version</opt></p>
  53
  54       <optdesc><p>Show version information.</p></optdesc>
  55     </option>
  56
  57     <option>
  58       <p><opt>--dump-conf</opt></p>
  59
  60       <optdesc><p>Load the daemon configuration file
  61       <file>daemon.conf</file> (see below), parse remaining
  62       configuration options on the command line and dump the resulting
  63       daemon configuration, in a format that is compatible with
  64       <file>daemon.conf</file>.</p></optdesc>
  65     </option>
  66
  67     <option>
  68       <p><opt>--dump-modules</opt></p>
  69
  70       <optdesc><p>List available loadable modules. Combine with
  71       <opt>-v</opt> for a more elaborate listing.</p></optdesc>
  72     </option>
  73
  74     <option>
  75       <p><opt>--dump-resampe-methods</opt></p>
  76       <optdesc><p>List available audio resamplers.</p></optdesc>
  77     </option>
  78
  79     <option>
  80       <p><opt>--cleanup-shm</opt></p>
  81
  82       <optdesc><p>Identify stale PulseAudio POSIX shared memory
  83       segments in <file>/dev/shm</file> and remove them if
  84       possible. This is done implicitly whenever a new daemon starts
  85       up or a client tries to connect to a daemon. It should normally
  86       not be necessary to issue this command by hand. Only available
  87       on systems with POSIX shared memory segments implemented via a
  88       virtual file system mounted to <file>/dev/shm</file>
  89       (e.g. Linux).</p></optdesc>
  90     </option>
  91
  92     <option>
  93       <p><opt>-k | --kill</opt></p>
  94
  95       <optdesc><p>Kill an already running PulseAudio daemon of the
  96       calling user (Equivalent to sending a SIGTERM).</p></optdesc>
  97     </option>
  98
  99     <option>
 100       <p><opt>--check</opt></p>
 101
 102       <optdesc><p>Return 0 as return code when the PulseAudio daemon
 103       is already running for the calling user.</p></optdesc>
 104     </option>
 105
 106
 107     <option>
 108       <p><opt>--system</opt><arg>[=BOOL]</arg></p>
 109
 110       <optdesc><p>Run as system-wide instance instead of
 111       per-user. Please not that this disables certain features of
 112       PulseAudio and is generally not recommended unless the system
 113       knows no local users (e.g. is a thin client). This feature needs
 114       special configuration and a dedicated UNIX user set up. It is
 115       highly recommended to combine this with
 116       <opt>--disallow-module-loading</opt> (see below).</p></optdesc>
 117     </option>
 118
 119     <option>
 120       <p><opt>-D | --daemon</opt><arg>[=BOOL]</arg></p>
 121
 122       <optdesc><p>Daemonize after startup, i.e. detach from the
 123       terminal.</p></optdesc>
 124     </option>
 125
 126     <option>
 127       <p><opt>--fail</opt><arg>[=BOOL]</arg></p>
 128
 129       <optdesc><p>Fail startup when any of the commands specified in
 130       the startup script <file>default.pa</file> (see below)
 131       fails.</p></optdesc>
 132     </option>
 133
 134     <option>
 135       <p><opt>--high-priority</opt><arg>[=BOOL]</arg></p>
 136
 137       <optdesc><p>Try to acquire a high Unix nice level. This will
 138       only succeed if the calling user has a non-zero RLIMIT_NICE
 139       resource limit set (on systems that support this), or we're
 140       called SUID root (see below), or we are configure to be run as
 141       system daemon (see <arg>--system</arg> above). It is recommended
 142       to enable this, since it is only a negligible security risk (see
 143       below).</p></optdesc>
 144     </option>
 145
 146     <option>
 147       <p><opt>--realtime</opt><arg>[=BOOL]</arg></p>
 148
 149       <optdesc><p>Try to acquire a real-time scheduling for
 150       PulseAudio's I/O threads. This will only succeed if the calling
 151       user has a non-zero RLIMIT_RTPRIO resource limit set (on systems
 152       that support this), or we're called SUID root (see below), or we
 153       are configure to be run as system daemon (see
 154       <arg>--system</arg> above). It is recommended to enable this
 155       only for trusted users, since it is a major security risk (see
 156       below).</p></optdesc>
 157     </option>
 158
 159     <option>
 160       <p><opt>--disallow-module-loading</opt><arg>[=BOOL]</arg></p>
 161
 162       <optdesc><p>Disallow module loading after startup. This is a
 163       security feature since it disallows additional module loading
 164       during runtime and on user request. It is highly recommended
 165       when <arg>--system</arg> is used (see above). Note however, that
 166       this breaks certain features like automatic module loading on hot
 167       plug.</p></optdesc>
 168
 169     </option>
 170
 171     <option>
 172       <p><opt>--exit-idle-time</opt><arg>=SECS</arg></p>
 173
 174       <optdesc><p>Terminate the daemon when idle and the specified
 175       number of seconds passed.</p></optdesc>
 176     </option>
 177
 178     <option>
 179       <p><opt>--module-idle-time</opt><arg>=SECS</arg></p>
 180
 181       <optdesc><p>Unload autoloaded modules when idle and the
 182       specified number of seconds passed.</p></optdesc>
 183     </option>
 184
 185     <option>
 186       <p><opt>--scache-idle-time</opt><arg>=SECS</arg></p>
 187
 188       <optdesc><p>Unload autoloaded samples from the cache when the
 189       haven't been used for the specified number of
 190       seconds.</p></optdesc>
 191     </option>
 192
 193     <option>
 194       <p><opt>--log-level</opt><arg>[=LEVEL]</arg></p>
 195
 196       <optdesc><p>If an argument is passed, set the log level to the
 197       specified value, otherwise increase the configured verbosity
 198       level by one. The log levels are numerical from 0 to 4,
 199       corresponding to <arg>error</arg>, <arg>warn</arg>,
 200       <arg>notice</arg>, <arg>info</arg>, <arg>debug</arg>. Default
 201       log level is <arg>notice</arg>, i.e. all log messages with lower
 202       log levels are printed: <arg>error</arg>, <arg>warn</arg>,
 203       <arg>notice</arg>.</p></optdesc>
 204     </option>
 205
 206     <option>
 207       <p><opt>-v</opt></p>
 208
 209       <optdesc><p>Increase the configured verbosity level by one (see
 210       <opt>--log-level</opt> above). Specify multiple times to
 211       increase log level multiple times.</p></optdesc>
 212     </option>
 213
 214     <option>
 215       <p><opt>--log-target</opt><arg>={auto,syslog,stderr}</arg></p>
 216
 217       <optdesc><p>Specify the log target. If set to <arg>auto</arg>
 218       (which is the default), then logging is directed to syslog when
 219       <opt>--daemonize</opt> is passed, otherwise to
 220       STDERR.</p></optdesc>
 221     </option>
 222
 223     <option>
 224       <p><opt>--p | --dl-search-path</opt><arg>=PATH</arg></p>
 225
 226       <optdesc><p>Set the search path for dynamic shared objects
 227       (plugins).</p></optdesc>
 228     </option>
 229
 230     <option>
 231       <p><opt>--resample-method</opt><arg>=METHOD</arg></p>
 232
 233       <optdesc><p>Use the specified resampler by default (See
 234       <opt>--dump-resample-methods</opt> above for possible
 235       values).</p></optdesc>
 236     </option>
 237
 238     <option>
 239       <p><opt>--use-pid-file</opt><arg>[=BOOL]</arg></p>
 240
 241       <optdesc><p>Create a PID file. If this options is disabled it is possible to run multiple sound servers per user.</p></optdesc>
 242     </option>
 243
 244     <option>
 245       <p><opt>--no-cpu-limit</opt><arg>[=BOOL]</arg></p>
 246
 247       <optdesc><p>Do not install CPU load limiter on platforms that
 248       support it. By default, PulseAudio will terminate itself when it
 249       notices that it takes up too much CPU time. This is useful as a
 250       protection against system lockups when real-time scheduling is
 251       used (see below). Disabling this meachnism is useful when
 252       debugging PulseAudio with tools like <manref name="valgrind"
 253       section="1"/> which slow down execution.</p></optdesc>
 254     </option>
 255
 256     <option>
 257       <p><opt>--disable-shm</opt><arg>[=BOOL]</arg></p>
 258
 259       <optdesc><p>PulseAudio clients and the server can exchange audio
 260       data via POSIX shared memory segments (on systems that support
 261       this). If disabled PulseAudio will communicate exclusively over
 262       sockets. Please note that data transfer via shared memory
 263       segments is always disabled when PulseAudio is running with
 264       <opt>--system</opt> enabled (see above).</p></optdesc>
 265     </option>
 266
 267     <option>
 268       <p><opt>-L | --load</opt><arg>="MODULE ARGUMENTS"</arg></p>
 269
 270       <optdesc><p>Load the specified plugin module with the specified
 271       arguments.</p></optdesc>
 272     </option>
 273
 274     <option>
 275       <p><opt>-F | --file</opt><arg>=FILENAME</arg></p>
 276
 277       <optdesc><p>Run the specified script on startup. May be
 278       specified multiple times to specify multiple scripts to be run
 279       in order. Combine with <opt>-n</opt> to disable loading of the
 280       default script <file>default.pa</file> (see below).</p></optdesc>
 281     </option>
 282     <option>
 283       <p><opt>-C</opt></p>
 284
 285       <optdesc><p>Open a command interpreter on STDIN/STDOUT after
 286       startup. This may be used to configure PulseAudio dynamically
 287       during runtime. Equivalent to
 288       <opt>--load</opt><arg>=module-cli</arg>.</p></optdesc>
 289     </option>
 290     <option>
 291       <p><opt>-n</opt></p>
 292
 293       <optdesc><p>Don't load default script file
 294       <file>default.pa</file> (see below) on startup. Useful in
 295       conjunction with <opt>-C</opt> or
 296       <opt>--file</opt>.</p></optdesc>
 297     </option>
 298
 299
 300   </options>
 301
 302   <section name="Files">
 303
 304     <p><file>~/.pulse/daemon.conf</file>,
 305     <file>@pulseconfdir@/daemon.conf</file>: configuration settings
 306     for the PulseAudio daemon. If the version in the user's home
 307     directory does not exist the global configuration file is
 308     loaded. See <manref name="pulse-daemon.conf" section="5"/> for
 309     more information.</p>
 310
 311     <p><file>~/.pulse/default.pa</file>,
 312     <file>@pulseconfdir@/default.pa</file>: the default configuration
 313     script to execute when the PulseAudio daemon is started. If the
 314     version in the user's home directory does not exist the global
 315     configuration script is loaded. See <manref name="default.pa"
 316     section="5"/> for more information.</p>
 317
 318     <p><file>~/.pulse/client.conf</file>,
 319     <file>@pulseconfdir@/client.conf</file>: configuration settings
 320     for PulseAudio client applications. If the version in the user's
 321     home directory does not exist the global configuration file is
 322     loaded.  See <manref name="pulse-client.conf" section="5"/> for
 323     more information.</p>
 324
 325   </section>
 326
 327   <section name="Signals">
 328
 329     <p><arg>SIGINT, SIGTERM</arg>: the PulseAudio daemon will shut
 330     down (Same as <opt>--kill</opt>).</p>
 331
 332     <p><arg>SIGHUP</arg>: dump a long status report to STDOUT or
 333     syslog, depending on the configuration.</p>
 334
 335     <p><arg>SIGUSR1</arg>: load module-cli, allowing runtime
 336     reconfiguration via STDIN/STDOUT.</p>
 337
 338     <p><arg>SIGUSR2</arg>: load module-cli-protocol-unix, allowing
 339     runtime reconfiguration via a AF_UNIX socket. See <manref
 340     name="pacmd" section="1"/> for more information.</p>
 341
 342   </section>
 343
 344   <section name="UNIX Groups and users">
 345
 346     <p>Group <arg>pulse-rt</arg>: if the PulseAudio binary is marked
 347     SUID root, then membership of the calling user in this group
 348     decides whether real-time and/or high-priority scheduling is
 349     enabled. Please note that enabling real-time scheduling is a
 350     security risk (see below).</p>
 351
 352     <p>Group <arg>pulse-access</arg>: if PulseAudio is running as a system
 353     daemon (see <opt>--system</opt> above) access is granted to
 354     members of this group when they connect via AF_UNIX sockets. If
 355     PulseAudio is running as a user daemon this group has no
 356     meaning.</p>
 357
 358     <p>User <arg>pulse</arg>, group <arg>pulse</arg>: if PulseAudio is running as a system
 359     daemon (see <opt>--system</opt> above) and is started as root the
 360     daemon will drop priviliges and become a normal user process using
 361     this user and group. If PulseAudio is running as a user daemon
 362     this user and group has no meaning.</p>
 363   </section>
 364
 365   <section name="Real-time and high-priority scheduling">
 366     Blablub
 367   </section>
 368
 369   <section name="Authors">
 370     <p>The PulseAudio Developers &lt;@PACKAGE_BUGREPORT@&gt;; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
 371   </section>
 372
 373   <section name="See also">
 374     <p>
 375       <manref name="pulse-daemon.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulse-client.conf" section="5"/>, <manref name="pacmd" section="1"/>
 376     </p>
 377   </section>
 378
 379 </manpage>