path: root/man/pm-action.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [


  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "Tim">
  <!ENTITY dhsurname   "Dijkstra">
  <!-- dhusername could also be set to "&firstname; &surname;". -->  
  <!ENTITY dhusername  "Tim Dijkstra">
  <!ENTITY dhemail     "tim@famdijkstra.org">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "Apr 25, 2007">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1) and
       http://www.tldp.org/HOWTO/Man-Page/q2.html. -->
  <!ENTITY dhsection   "8">
  <!-- TITLE should be something like "User commands" or similar (see
       http://www.tldp.org/HOWTO/Man-Page/q2.html). -->
  <!ENTITY dhtitle     "pm-utils User Manual">
  <!ENTITY dhucpackage "pm-action">
  <!ENTITY dhpackage   "pm-action">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <title>&dhtitle;</title>
    <productname>&dhpackage;</productname>
    <date>&dhdate;</date>
    <authorgroup>
      <author>
	<firstname>&dhfirstname;</firstname>
	<surname>&dhsurname;</surname>
	<contrib>Manpage author.</contrib>
	<address>
	  <email>&dhemail;</email>
	</address>
      </author>
    </authorgroup>
    <copyright>
      <year>2007</year>
      <holder>&dhusername;</holder>
    </copyright>
    <legalnotice>
      <para>
	This manual page was written for the &debian; system
	(but may be used by others).
      </para>
      <para>
	Permission is granted to copy, distribute and/or modify this
	document under the terms of the &gnu; General Public License,
	Version 2 or (at your option) any later version published by
        the Free Software Foundation.
      </para>
      <para>
	On Debian systems, the complete text of the GNU General Public
	License can be found
	in <filename>file:///usr/share/common-licenses/GPL</filename>.
      </para>
    </legalnotice>
  </refentryinfo>

  <refmeta>
    <refentrytitle>&dhucpackage;</refentrytitle>
    <manvolnum>&dhsection;</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>
    <refpurpose>suspend or hibernate your computer</refpurpose>
  </refnamediv>
  <refsynopsisdiv>

    <cmdsynopsis>
      <command>pm-hibernate</command>
    </cmdsynopsis>
  
    <cmdsynopsis>
      <command>pm-suspend</command>
      <group choice="opt">
	<arg choice="plain">
	  <group choice="req">
	    <arg choice="plain"><option>--quirk-*</option></arg>
	  </group>
        </arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>pm-suspend-hybrid</command>
      <group choice="opt">
	<arg choice="plain">
	  <group choice="req">
	    <arg choice="plain"><option>--quirk-*</option></arg>
	  </group>
        </arg>
      </group>
    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para>
      This manual page documents briefly the
      <command>&dhpackage;</command>, <command>pm-hibernate</command>,
      <command>pm-suspend</command> and <command>pm-suspend-hybrid</command>
      commands. This manual page was written for the &debian; distribution
      because the original program does not have a manual page.
    </para>
    <para>
      These commands can be used to put the machine in a sleep 
      state. The precise  way how this is done can be
      influenced by installing executables and configuration snippets. 
      For some options external programs are needed.
    </para>
    <para>
      These commands will usually be called by 
      <command>hald</command> when triggered to do so by a program
      in a desktop session such as <command>gnome-power-manager</command>. 
      Calling them from the command line is also possible, but it is not 
      guaranteed that all programs in your desktop session keep working
      as expected.
    </para>
    <variablelist>
      <!-- Use the variablelist.term.separator and the
	   variablelist.term.break.after parameters to
	   control the term elements. -->
      <varlistentry>
	<term><option>pm-suspend</option></term>
	<listitem>
	  <para>
	    Suspend is a state where most devices are shutdown, except 
	    for RAM. This state still draws power.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>pm-hibernate</option></term>
	<listitem>
	  <para>
	    During hibernate the state of the system is saved to disk, 
	    the system is fully powered off. Except maybe for a very low
	    power state on - for example - an ethernet card to enable
	    wake-on-lan.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>pm-suspend-hybrid</option></term>
	<listitem>
	  <para>
	    Hybrid-suspend is the process where first the state of the 
	    system is saved to disk - just like with hibernate - but 
	    instead of poweroff, the 
	    system goes in suspend state, which means it can wakeup 
	    quicker than for normal hibernation. The advantage over
	    suspend is that you can resume even if you run out of power.
	    s2both(8) is an hybrid-suspend implementation.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1 id="options">
    <title>OPTIONS</title>
    <para>
      Om most hardware putting the video card in the suspend state and 
      recovering from it needs some hacks.
      With the --quirk-* options of the <command>pm-suspend</command> and
      <command>pm-suspend-hybrid</command> commands you can select which
      should be used.
    </para>

    <variablelist>
      <!-- Use the variablelist.term.separator and the
	   variablelist.term.break.after parameters to
	   control the term elements. -->
      <varlistentry>
	<term><option>--quirk-dpms-on</option></term>
	<listitem>
          <para>
            This option forces the video hardware to turn on the screen during
            resume. Most video adapters turn on the screen themselves, but if
            you get a blank screen on resume, that can be turned back on by
            moving the mouse or typing then this option may be useful.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-dpms-suspend</option></term>
        <listitem>
          <para>
            This option forces the video hardware to turn off the output
            device when suspending. Most video adapters seem to do this
            correctly, but some leave the backlight on (with a blank screen)
            using lots and lots of power in the process. If you can see the
            backlight is on when you have successfully suspended you may need
            to use this option.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-radeon-off</option></term>
        <listitem>
          <para>
            This option forces Radeon hardware to turn on the brightness DAC
            and also to turn on the backlight during resume. You only need to
            do this on some old ThinkPads of the '30 series 
            (T30, X31, R32,... ) with Radeon video hardware.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-s3-bios</option></term>
        <listitem>
          <para>
            This option calls the video BIOS during S3 resume. Unfortunately,
            it is not always allowed to call the video BIOS at this point, so
            sometimes adding this option can actually break resume on some
            systems.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-s3-mode</option></term>
        <listitem>
          <para>
            This option initializes the video card into a VGA text mode, and
            then uses the BIOS to set the video mode. On some systems S3 BIOS
            only initializes the video bios to text mode, and so both S3 BIOS
            and S3 MODE are needed.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-vbe-post</option></term>
        <listitem>
          <para>
            This option will attempt to run BIOS code located at c000:0003
            during resume. This is the code also run by the system BIOS at
            boot in order to initialize the video hardware.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-vbemode-restore</option></term>
        <listitem>
          <para>
            This option will save and restore the current VESA mode which may
            be necessary to avoid X screen corruption. Using this feature on
            Intel graphics hardware is probably a bad idea.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-vbestate-restore</option></term>
        <listitem>
          <para>
            This option uses the VESA 0x4f0f extensions to save and restore
            hardware state which may be invalid after suspend.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-vga-mode3</option></term>
        <listitem>
          <para>
            This option will try to re-enable the video card on resume.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--quirk-save-pci</option></term>
        <listitem>
          <para>
            Save the PCI config space for the VGA card.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="files">
    <title>FILES</title>
    <variablelist>
      <varlistentry>
	<term><filename>/etc/pm/config.d</filename></term>
	<listitem>
	  <para>
	    The files in this directory are evaluated in C sort order. 
	    These files can be provided by individual packages outside 
	    of pm-utils. If a global configuration variable is set, the 
	    value set to will be appended to the previous value.
	    If any other variable is set, it will be ignored. 
	    The syntax is simply: VAR_NAME = value.
	    See the
	    CONFIGURATION VARIABLES section for valid variables defined
	    by pm-utils. External packages can define others, see
	    their respective documentation for more information.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/etc/pm/sleep.d</filename></term>
	<term><filename>/usr/lib/pm-utils/sleep.d</filename></term>
	<listitem>
	  <para>
	    Programs in these directories (we call them hooks) are 
	    combined and executed in C sort order before suspend and 
	    hibernate with as argument 'suspend' or 'hibernate'.
	    Afterwards they are called  in reverse order with
	    argument 'resume' and 'thaw' respectively.
	    If both directories contain a similar named file,
	    the one in /etc/pm/sleep.d will get preference. It
	    is possible to disable a hook in the distribution
	    directory by putting a non-executable file in 
	    /etc/pm/sleep.d.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/var/log/pm-suspend.log</filename></term>
	<listitem>
	  <para>
	    The log file showing what is done on suspend/hibernate
	    and resume/thaw.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="config_vars">
    <title>CONFIGURATION VARIABLES</title>
    <para>
      Configuration variables defined by pm-utils. These can be set 
      in any file in /etc/pm/config.d
    </para>

    <variablelist>
      <varlistentry>
        <term><envar>SLEEP_MODULE [=auto]</envar></term>
        <listitem>
          <para>
            The default suspend backend to use. Valid values are:
            <variablelist>
              <varlistentry>
                <term><parameter>kernel</parameter></term>
                <listitem>
                  <para>
                    The built-in kernel suspend/resume support.
                    Use this if nothing else is supported on your system.
                </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><parameter>uswsusp</parameter></term>
                <listitem>
                  <para>
                    If your system has support for the userspace
                    suspend programs (s2ram/s2disk/s2both), then use this.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><parameter>tuxonice</parameter></term>
                <listitem>
                  <para>
                    If your system has support for tuxonice, use this.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><parameter>auto</parameter></term>
                <listitem>
                  <para>
                    Try to autodetect which backend to use.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><envar>HIBERNATE_RESUME_POST_VIDEO [=no]</envar></term>
        <listitem>
          <para>
            If video should be posted after hibernate, just like
            after suspend. You should not normally need to set this.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><envar>SUSPEND_MODULES</envar></term>
        <listitem>
          <para>
            Space separated list of modules to unload before suspend.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><envar>HOOK_BLACKLIST</envar></term>
        <listitem>
          <para>
            Space separated list of hooks that should be disabled.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><envar>HIBERNATE_MODE</envar></term>
        <listitem>
          <para>
            Default method to power down the system when hibernating.
            If not set, the system will use the kernel default as a
            default value.
            Check /sys/power/disk for valid values. The default value
            will be surrounded by [square brackets].
          </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="bugs">
    <title>BUGS</title>
    <para>
      The upstream <acronym>BTS</acronym> can be found
      at <ulink url="https://bugs.freedesktop.org/"/>.
      Select 'pm-utils' as product.
    </para>
  </refsect1>

  <refsect1 id="see_also">
    <title>SEE ALSO</title>
    <!-- In alpabetical order. -->
    <para>
      <citerefentry>
        <refentrytitle>s2ram</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>s2disk</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>s2both</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pm-is-supported</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pm-powersave</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>vbetool</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>radeontool</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry> 
    </para>
  </refsect1>
</refentry>