<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
-<!-- $Id$ -->
-
<!--
This file is part of PulseAudio.
<cmd>pulseaudio <opt>--dump-modules</opt></cmd>
<cmd>pulseaudio <opt>--dump-resample-methods</opt></cmd>
<cmd>pulseaudio <opt>--cleanup-shm</opt></cmd>
+ <cmd>pulseaudio <opt>--start</opt></cmd>
<cmd>pulseaudio <opt>--kill</opt></cmd>
<cmd>pulseaudio <opt>--check</opt></cmd>
</synopsis>
</option>
<option>
- <p><opt>--dump-resampe-methods</opt></p>
+ <p><opt>--dump-resample-methods</opt></p>
<optdesc><p>List available audio resamplers.</p></optdesc>
</option>
(e.g. Linux).</p></optdesc>
</option>
+ <option>
+ <p><opt>--start</opt></p>
+
+ <optdesc><p>Start PulseAudio if it is not running yet. This is
+ different from starting PulseAudio without <opt>--start</opt>
+ which would fail if PA is already running. PulseAudio is
+ guaranteed to be fully initialized when this call
+ returns. Implies <opt>--daemon</opt>.</p></optdesc>
+ </option>
+
<option>
<p><opt>-k | --kill</opt></p>
<p><opt>--check</opt></p>
<optdesc><p>Return 0 as return code when the PulseAudio daemon
- is already running for the calling user.</p></optdesc>
+ is already running for the calling user, or non-zero
+ otherwise. Produces no output on the console except for errors
+ to stderr.</p></optdesc>
</option>
<p><opt>--system</opt><arg>[=BOOL]</arg></p>
<optdesc><p>Run as system-wide instance instead of
- per-user. Please not that this disables certain features of
+ per-user. Please note that this disables certain features of
PulseAudio and is generally not recommended unless the system
knows no local users (e.g. is a thin client). This feature needs
special configuration and a dedicated UNIX user set up. It is
</option>
<option>
- <p><opt>-D | --daemon</opt><arg>[=BOOL]</arg></p>
+ <p><opt>-D | --daemonize</opt><arg>[=BOOL]</arg></p>
<optdesc><p>Daemonize after startup, i.e. detach from the
terminal.</p></optdesc>
</option>
<option>
- <p><opt>--exit-idle-time</opt><arg>=SECS</arg></p>
+ <p><opt>--disallow-exit</opt><arg>[=BOOL]</arg></p>
- <optdesc><p>Terminate the daemon when idle and the specified
- number of seconds passed.</p></optdesc>
+ <optdesc><p>Disallow user requested exit</p></optdesc>
</option>
<option>
- <p><opt>--module-idle-time</opt><arg>=SECS</arg></p>
+ <p><opt>--exit-idle-time</opt><arg>=SECS</arg></p>
- <optdesc><p>Unload autoloaded modules when idle and the
- specified number of seconds passed.</p></optdesc>
+ <optdesc><p>Terminate the daemon when idle and the specified
+ number of seconds passed.</p></optdesc>
</option>
<option>
</option>
<option>
- <p><opt>-v</opt></p>
+ <p><opt>-v | --verbose</opt></p>
<optdesc><p>Increase the configured verbosity level by one (see
<opt>--log-level</opt> above). Specify multiple times to
</option>
<option>
- <p><opt>--log-target</opt><arg>={auto,syslog,stderr}</arg></p>
+ <p><opt>--log-target</opt><arg>={auto,syslog,journal,stderr,file:PATH,newfile:PATH}</arg></p>
<optdesc><p>Specify the log target. If set to <arg>auto</arg>
(which is the default), then logging is directed to syslog when
<opt>--daemonize</opt> is passed, otherwise to
- STDERR.</p></optdesc>
+ STDERR. If set to <arg>journal</arg> logging is directed to the systemd
+ journal. If set to <arg>file:PATH</arg>, logging is directed to
+ the file indicated by PATH. <arg>newfile:PATH</arg> is otherwise
+ the same as file:PATH, but existing files are never overwritten.
+ If the specified file already exists, a suffix is added to the
+ file name to avoid overwriting.</p></optdesc>
+ </option>
+
+ <option>
+ <p><opt>--log-meta</opt><arg>[=BOOL]</arg></p>
+
+ <optdesc><p>Show source code location in log messages.</p></optdesc>
+ </option>
+
+ <option>
+ <p><opt>--log-time</opt><arg>[=BOOL]</arg></p>
+
+ <optdesc><p>Show timestamps in log messages.</p></optdesc>
+ </option>
+
+ <option>
+ <p><opt>--log-backtrace</opt><arg>=FRAMES</arg></p>
+
+ <optdesc><p>When FRAMES is greater than 0, log for each message a
+ stack trace up to the number of specified stack frames.</p></optdesc>
</option>
<option>
- <p><opt>--p | --dl-search-path</opt><arg>=PATH</arg></p>
+ <p><opt>-p | --dl-search-path</opt><arg>=PATH</arg></p>
<optdesc><p>Set the search path for dynamic shared objects
(plugins).</p></optdesc>
support it. By default, PulseAudio will terminate itself when it
notices that it takes up too much CPU time. This is useful as a
protection against system lockups when real-time scheduling is
- used (see below). Disabling this meachnism is useful when
+ used (see below). Disabling this mechanism is useful when
debugging PulseAudio with tools like <manref name="valgrind"
section="1"/> which slow down execution.</p></optdesc>
</option>
<section name="Files">
- <p><file>~/.pulse/daemon.conf</file>,
- <file>@pulseconfdir@/daemon.conf</file>: configuration settings
+ <p><file>~/.config/pulse/daemon.conf</file>,
+ <file>@PA_DEFAULT_CONFIG_DIR@/daemon.conf</file>: configuration settings
for the PulseAudio daemon. If the version in the user's home
directory does not exist the global configuration file is
loaded. See <manref name="pulse-daemon.conf" section="5"/> for
more information.</p>
- <p><file>~/.pulse/default.pa</file>,
- <file>@pulseconfdir@/default.pa</file>: the default configuration
+ <p><file>~/.config/pulse/default.pa</file>,
+ <file>@PA_DEFAULT_CONFIG_DIR@/default.pa</file>: the default configuration
script to execute when the PulseAudio daemon is started. If the
version in the user's home directory does not exist the global
configuration script is loaded. See <manref name="default.pa"
section="5"/> for more information.</p>
- <p><file>~/.pulse/client.conf</file>,
- <file>@pulseconfdir@/client.conf</file>: configuration settings
+ <p><file>~/.config/pulse/client.conf</file>,
+ <file>@PA_DEFAULT_CONFIG_DIR@/client.conf</file>: configuration settings
for PulseAudio client applications. If the version in the user's
home directory does not exist the global configuration file is
loaded. See <manref name="pulse-client.conf" section="5"/> for
<p>User <arg>pulse</arg>, group <arg>pulse</arg>: if PulseAudio is running as a system
daemon (see <opt>--system</opt> above) and is started as root the
- daemon will drop priviliges and become a normal user process using
+ daemon will drop privileges and become a normal user process using
this user and group. If PulseAudio is running as a user daemon
this user and group has no meaning.</p>
</section>
when it needs it to refill the hardware playback
buffers. Unfortunately this is a security risk on most systems,
since PulseAudio runs as user process, and giving realtime
- scheduling priviliges to a user process always comes with the risk
+ scheduling privileges to a user process always comes with the risk
that the user misuses it to lock up the system -- which is
possible since making a process real-time effectively disables
preemption.</p>
on trusted systems. To do that start PulseAudio with
<opt>--realtime</opt> (see above) or enabled the appropriate option in
<file>daemon.conf</file>. Since acquiring realtime scheduling is a
- priviliged operation on most systems, some special changes to the
+ privileged operation on most systems, some special changes to the
system configuration need to be made to allow them to the calling
user. Two options are available:</p>
<file>/etc/security/limits.conf</file>, a resource limit of 9 is recommended.</p>
<p>Alternatively, the SUID root bit can be set for the PulseAudio
- binary. Then, the daemon will drop root priviliges immediately on
+ binary. Then, the daemon will drop root privileges immediately on
startup, however retain the CAP_NICE capability (on systems that
support it), but only if the calling user is a member of the
<arg>pulse-rt</arg> group (see above). For all other users all
- capababilities are dropped immediately. The advantage of this
- solution is that the real-time priviliges are only granted to the
+ capabilities are dropped immediately. The advantage of this
+ solution is that the real-time privileges are only granted to the
PulseAudio daemon -- not to all the user's processes.</p>
<p>Alternatively, if the risk of locking up the machine is
scheduling can be enabled instead (i.e. negative nice level). This
can be enabled by passing <opt>--high-priority</opt> (see above)
when starting PulseAudio and may also be enabled with the
- approriate option in <file>daemon.conf</file>. Negative nice
+ appropriate option in <file>daemon.conf</file>. Negative nice
levels can only be enabled when the appropriate resource limit
RLIMIT_NICE is set (see <manref name="setrlimit" section="2"/> for
more information), possibly configured in
<section name="Environment variables">
- <p>The PulseAudio client libraries check for the existance of the
+ <p>The PulseAudio client libraries check for the existence of the
following environment variables and change their local configuration accordingly:</p>
- <p><arg>$PULSE_SERVER</arg>: the server string specifying the server to connect to when a client asks for a sound server connection and doesn't explicitly ask for a specific server.</p>
+ <p><arg>$PULSE_SERVER</arg>: the server string specifying the server
+ to connect to when a client asks for a sound server connection and doesn't
+ explicitly ask for a specific server. The server string is a list of
+ server addresses separated by whitespace which are tried in turn. A server
+ address consists of an optional address type specifier (unix:, tcp:, tcp4:,
+ tcp6:), followed by a path or host address. A host address may include an
+ optional port number.</p>
<p><arg>$PULSE_SINK</arg>: the symbolic name of the sink to connect to when a client creates a playback stream and doesn't explicitly ask for a specific sink.</p>
<p><arg>$PULSE_CLIENTCONFIG</arg>: path of file that shall be read instead of <file>client.conf</file> (see above) for client configuration.</p>
+ <p><arg>$PULSE_COOKIE</arg>: path of file that contains the PulseAudio
+ authentication cookie. Defaults to <file>~/.config/pulse/cookie</file>.</p>
+
<p>These environment settings take precedence -- if set -- over the configuration settings from <file>client.conf</file> (see above).</p>
</section>