X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=man%2Fpulseaudio.1.xml.in;h=6a658ff770156528764c902ae5e31d541397ba60;hb=5f16d42ffa51b8b169fccdcdc6568b848491aacd;hp=b30f44843c98d9a282d3458432babd15a2373355;hpb=bff4ca431b0146cb0cbb3935905f50714072a0d9;p=profile%2Fivi%2Fpulseaudio.git

diff --git a/man/pulseaudio.1.xml.in b/man/pulseaudio.1.xml.in
index b30f448..6a658ff 100644
--- a/man/pulseaudio.1.xml.in
+++ b/man/pulseaudio.1.xml.in
@@ -2,8 +2,6 @@
 <!DOCTYPE manpage SYSTEM "xmltoman.dtd">
 <?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
 
-<!-- $Id$ -->
-
 <!--
 This file is part of PulseAudio.
 
@@ -28,10 +26,12 @@ USA.
   <synopsis>
     <cmd>pulseaudio [<arg>options</arg>]</cmd>
     <cmd>pulseaudio <opt>--help</opt></cmd>
+    <cmd>pulseaudio <opt>--version</opt></cmd>
     <cmd>pulseaudio <opt>--dump-conf</opt></cmd>
     <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>
@@ -72,7 +72,7 @@ USA.
     </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>
 
@@ -90,6 +90,16 @@ USA.
     </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>
 
       <optdesc><p>Kill an already running PulseAudio daemon of the
@@ -100,7 +110,9 @@ USA.
       <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>
 
 
@@ -108,7 +120,7 @@ USA.
       <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
@@ -117,7 +129,7 @@ USA.
     </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>
@@ -176,13 +188,6 @@ USA.
     </option>
 
     <option>
-      <p><opt>--module-idle-time</opt><arg>=SECS</arg></p>
-
-      <optdesc><p>Unload autoloaded modules when idle and the
-      specified number of seconds passed.</p></optdesc>
-    </option>
-
-    <option>
       <p><opt>--scache-idle-time</opt><arg>=SECS</arg></p>
 
       <optdesc><p>Unload autoloaded samples from the cache when the
@@ -212,12 +217,13 @@ USA.
     </option>
 
     <option>
-      <p><opt>--log-target</opt><arg>={auto,syslog,stderr}</arg></p>
+      <p><opt>--log-target</opt><arg>={auto,syslog,stderr,file: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>file:PATH</arg>, logging is directed to
+      the file indicated by PATH.</p></optdesc>
     </option>
 
     <option>
@@ -302,21 +308,21 @@ USA.
   <section name="Files">
 
     <p><file>~/.pulse/daemon.conf</file>,
-    <file>@pulseconfdir@/daemon.conf</file>: configuration settings
+    <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
+    <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
+    <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
@@ -363,7 +369,73 @@ USA.
   </section>
 
   <section name="Real-time and high-priority scheduling">
-    Blablub
+    <p>To minimize the risk of drop-outs during playback it is
+    recommended to run PulseAudio with real-time scheduling if the
+    underlying platform supports it. This decouples the scheduling
+    latency of the PulseAudio daemon from the system load and is thus
+    the best way to make sure that PulseAudio always gets CPU time
+    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
+    that the user misuses it to lock up the system -- which is
+    possible since making a process real-time effectively disables
+    preemption.</p>
+
+    <p>To minimize the risk PulseAudio by default does not enable
+    real-time scheduling. It is however recommended to enable it
+    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
+    system configuration need to be made to allow them to the calling
+    user. Two options are available:</p>
+
+    <p>On newer Linux systems the system resource limit RLIMIT_RTPRIO
+    (see <manref name="setrlimit" section="2"/> for more information)
+    can be used to allow specific users to acquire real-time
+    scheduling. This can be configured in
+    <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
+    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
+    PulseAudio daemon -- not to all the user's processes.</p>
+
+    <p>Alternatively, if the risk of locking up the machine is
+    considered too big to enable real-time scheduling, high-priority
+    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
+    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
+    <file>/etc/security/limits.conf</file>. A resource limit of 31
+    (corresponding with nice level -11) is recommended.</p>
+  </section>
+
+  <section name="Environment variables">
+
+    <p>The PulseAudio client libraries check for the existance 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_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_SOURCE</arg>: the symbolic name of the source to connect to when a client creates a record stream and doesn't explicitly ask for a specific source.</p>
+
+    <p><arg>$PULSE_BINARY</arg>: path of PulseAudio executable to run when server auto-spawning is used.</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>These environment settings take precedence -- if set -- over the configuration settings from <file>client.conf</file> (see above).</p>
+
   </section>
 
   <section name="Authors">