← Back to branch summary

~ubuntu-branches/ubuntu/quantal/pm-utils/quantal-proposed

« back to all changes in this revision

Viewing changes to man/pm-action.xml

Tags: upstream-1.1.2.2
Import upstream version 1.1.2.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
man/pm-action.xml
 
1
<?xml version='1.0' encoding='UTF-8'?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 
3
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
4
 
 
5
 
 
6
  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
 
7
  <!ENTITY dhfirstname "Tim">
 
8
  <!ENTITY dhsurname   "Dijkstra">
 
9
  <!-- dhusername could also be set to "&firstname; &surname;". -->  
 
10
  <!ENTITY dhusername  "Tim Dijkstra">
 
11
  <!ENTITY dhemail     "tim@famdijkstra.org">
 
12
  <!-- Please adjust the date whenever revising the manpage. -->
 
13
  <!ENTITY dhdate      "Apr 25, 2007">
 
14
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
 
15
       allowed: see man(7), man(1) and
 
16
       http://www.tldp.org/HOWTO/Man-Page/q2.html. -->
 
17
  <!ENTITY dhsection   "8">
 
18
  <!-- TITLE should be something like "User commands" or similar (see
 
19
       http://www.tldp.org/HOWTO/Man-Page/q2.html). -->
 
20
  <!ENTITY dhtitle     "pm-utils User Manual">
 
21
  <!ENTITY dhucpackage "pm-action">
 
22
  <!ENTITY dhpackage   "pm-action">
 
23
 
 
24
  <!ENTITY debian      "<productname>Debian</productname>">
 
25
  <!ENTITY gnu         "<acronym>GNU</acronym>">
 
26
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
 
27
]>
 
28
 
 
29
<refentry>
 
30
  <refentryinfo>
 
31
    <title>&dhtitle;</title>
 
32
    <productname>&dhpackage;</productname>
 
33
    <date>&dhdate;</date>
 
34
    <authorgroup>
 
35
      <author>
 
36
        <firstname>&dhfirstname;</firstname>
 
37
        <surname>&dhsurname;</surname>
 
38
        <contrib>Manpage author.</contrib>
 
39
        <address>
 
40
          <email>&dhemail;</email>
 
41
        </address>
 
42
      </author>
 
43
    </authorgroup>
 
44
    <copyright>
 
45
      <year>2007</year>
 
46
      <holder>&dhusername;</holder>
 
47
    </copyright>
 
48
    <legalnotice>
 
49
      <para>
 
50
        This manual page was originally written for the &debian; system, and
 
51
        has been adopted by the pm-utils project.
 
52
      </para>
 
53
      <para>
 
54
        Permission is granted to copy, distribute and/or modify this
 
55
        document under the terms of the &gnu; General Public License,
 
56
        Version 2 or (at your option) any later version published by
 
57
        the Free Software Foundation.
 
58
      </para>
 
59
    </legalnotice>
 
60
  </refentryinfo>
 
61
 
 
62
  <refmeta>
 
63
    <refentrytitle>&dhucpackage;</refentrytitle>
 
64
    <manvolnum>&dhsection;</manvolnum>
 
65
  </refmeta>
 
66
  <refnamediv>
 
67
    <refname>&dhpackage;</refname>
 
68
    <refpurpose>Suspend or Hibernate your computer</refpurpose>
 
69
  </refnamediv>
 
70
  <refsynopsisdiv>
 
71
 
 
72
    <cmdsynopsis>
 
73
      <command>pm-hibernate</command>
 
74
      <group choice="opt">
 
75
        <option>--help</option>
 
76
      </group>
 
77
    </cmdsynopsis>
 
78
  
 
79
    <cmdsynopsis>
 
80
      <command>pm-suspend</command>
 
81
      <group choice="opt">
 
82
        <option>--quirk-*</option>
 
83
        <option>--help</option>
 
84
      </group>
 
85
    </cmdsynopsis>
 
86
 
 
87
    <cmdsynopsis>
 
88
      <command>pm-suspend-hybrid</command>
 
89
      <group choice="opt">
 
90
        <option>--quirk-*</option>
 
91
        <option>--help</option>
 
92
      </group>
 
93
    </cmdsynopsis>
 
94
 
 
95
  </refsynopsisdiv>
 
96
 
 
97
  <refsect1 id="description">
 
98
    <title>DESCRIPTION</title>
 
99
    <para>
 
100
      This manual page documents briefly the
 
101
      <command>&dhpackage;</command>, <command>pm-hibernate</command>,
 
102
      <command>pm-suspend</command> and <command>pm-suspend-hybrid</command>
 
103
      commands. This manual page was originally written for the &debian; 
 
104
      distribution and has been adopted by the pm-utils project.
 
105
    </para>
 
106
    <para>
 
107
      These commands can be used to put the machine in a sleep 
 
108
      state. The precise way how this is done can be
 
109
      influenced by installing executables and configuration snippets. 
 
110
      For some options external programs are needed.
 
111
    </para>
 
112
    <para>
 
113
      These commands will usually be called by 
 
114
      <command>hald</command> when triggered to do so by a program
 
115
      in a desktop session such as <command>gnome-power-manager</command>. 
 
116
      Calling them from the command line is also possible, but it is not 
 
117
      guaranteed that all programs in your desktop session keep working
 
118
      as expected.
 
119
    </para>
 
120
    <variablelist>
 
121
      <!-- Use the variablelist.term.separator and the
 
122
           variablelist.term.break.after parameters to
 
123
           control the term elements. -->
 
124
      <varlistentry>
 
125
        <term><option>pm-suspend</option></term>
 
126
        <listitem>
 
127
          <para>
 
128
            During suspend most devices are shutdown, and system state is 
 
129
            saved in RAM. The system still requires power in this state. Most
 
130
            modern systems require 3 to 5 seconds to enter and leave suspend,
 
131
            and most laptops can stay in suspend mode for 1 to 3 days before
 
132
            exhausting their battery.
 
133
          </para>
 
134
        </listitem>
 
135
      </varlistentry>
 
136
      <varlistentry>
 
137
        <term><option>pm-hibernate</option></term>
 
138
        <listitem>
 
139
          <para>
 
140
            During hibernate the system is fully powered off, and system state
 
141
            is saved to disk. The system does not require power, and can stay
 
142
            in hibernate mode indefinitely. Most modern systems require 15 to 45
 
143
            seconds to enter and leave hibernate, and entering and leaving
 
144
            hibernate takes longer when you have more memory.
 
145
          </para>
 
146
        </listitem>
 
147
      </varlistentry>
 
148
      <varlistentry>
 
149
        <term><option>pm-suspend-hybrid</option></term>
 
150
        <listitem>
 
151
          <para>
 
152
            Hybrid-suspend is the process where the system does everything it
 
153
            needs to hibernate, suspends instead of shutting down. This means that 
 
154
            your computer can wake up quicker than for normal hibernation 
 
155
            if you do not run out of power, and you can resume even if you run out of power.
 
156
            s2both(8) is an hybrid-suspend implementation.
 
157
          </para>
 
158
        </listitem>
 
159
      </varlistentry>
 
160
    </variablelist>
 
161
 
 
162
  </refsect1>
 
163
 
 
164
  <refsect1 id="options">
 
165
    <title>OPTIONS</title>
 
166
    <para>
 
167
      Om most hardware putting the video card in the suspend state and 
 
168
      recovering from it needs some special quirk handling.
 
169
      With the --quirk-* options of the <command>pm-suspend</command> and
 
170
      <command>pm-suspend-hybrid</command> commands you can select which
 
171
      quirks should be used.
 
172
    </para>
 
173
 
 
174
    <variablelist>
 
175
      <!-- Use the variablelist.term.separator and the
 
176
           variablelist.term.break.after parameters to
 
177
           control the term elements. -->
 
178
      <varlistentry>
 
179
        <term><option>--quirk-dpms-on</option></term>
 
180
        <listitem>
 
181
          <para>
 
182
            This option forces the video hardware to turn on the screen during
 
183
            resume. Most video adapters turn on the screen themselves, but if
 
184
            you get a blank screen on resume that can be turned back on by
 
185
            moving the mouse or typing then this option may be useful.
 
186
          </para>
 
187
        </listitem>
 
188
      </varlistentry>
 
189
      <varlistentry>
 
190
        <term><option>--quirk-dpms-suspend</option></term>
 
191
        <listitem>
 
192
          <para>
 
193
            This option forces the video hardware to turn off the screen when suspending. 
 
194
            Most video adapters seem to do this correctly, but some do not, which
 
195
            wastes lits of power. If your screen is still on after successfully suspending
 
196
            you may need to use this option.
 
197
          </para>
 
198
        </listitem>
 
199
      </varlistentry>
 
200
      <varlistentry>
 
201
        <term><option>--quirk-radeon-off</option></term>
 
202
        <listitem>
 
203
          <para>
 
204
            This option forces Radeon hardware to turn off the display 
 
205
            during suspend and turn it back on during resume. You only need to
 
206
            do this on some old ThinkPads of the '30 series 
 
207
            (T30, X31, R32,... ) with Radeon video hardware.
 
208
          </para>
 
209
        </listitem>
 
210
      </varlistentry>
 
211
      <varlistentry>
 
212
        <term><option>--quirk-s3-bios</option></term>
 
213
        <listitem>
 
214
          <para>
 
215
            This option calls the video BIOS during S3 resume. Unfortunately,
 
216
            it is not always allowed to call the video BIOS at this point, so
 
217
            sometimes adding this option can actually break resume on some
 
218
            systems.
 
219
          </para>
 
220
        </listitem>
 
221
      </varlistentry>
 
222
      <varlistentry>
 
223
        <term><option>--quirk-s3-mode</option></term>
 
224
        <listitem>
 
225
          <para>
 
226
            This option initializes the video card into a VGA text mode, and
 
227
            then uses the BIOS to set the video mode. On some systems S3 BIOS
 
228
            only initializes the video bios to text mode, and so both S3 BIOS
 
229
            and S3 MODE are needed.
 
230
          </para>
 
231
        </listitem>
 
232
      </varlistentry>
 
233
      <varlistentry>
 
234
        <term><option>--quirk-vbe-post</option></term>
 
235
        <listitem>
 
236
          <para>
 
237
            This option will attempt to reinitialize the video card when
 
238
            resuming from suspend, using the same code the system BIOS uses
 
239
            at boot in order to initialize the video hardware.
 
240
            Not all video cards need this, and using this option on systems 
 
241
            where it is not needed can cause a system to lock up when resuming.
 
242
          </para>
 
243
        </listitem>
 
244
      </varlistentry>
 
245
      <varlistentry>
 
246
        <term><option>--quirk-vbemode-restore</option></term>
 
247
        <listitem>
 
248
          <para>
 
249
            This option will save and restore the current VESA mode which may
 
250
            be necessary to avoid X screen corruption. Using this feature on
 
251
            Intel graphics hardware is probably a bad idea.
 
252
          </para>
 
253
        </listitem>
 
254
      </varlistentry>
 
255
      <varlistentry>
 
256
        <term><option>--quirk-vbestate-restore</option></term>
 
257
        <listitem>
 
258
          <para>
 
259
            This option saves and restores some low level hardware state
 
260
            which may be invalid after suspend.
 
261
          </para>
 
262
        </listitem>
 
263
      </varlistentry>
 
264
      <varlistentry>
 
265
        <term><option>--quirk-vga-mode3</option></term>
 
266
        <listitem>
 
267
          <para>
 
268
            This option will try to force the video card into a standard
 
269
            text mode on resume.  
 
270
          </para>
 
271
        </listitem>
 
272
      </varlistentry>
 
273
      <varlistentry>
 
274
        <term><option>--quirk-save-pci</option></term>
 
275
        <listitem>
 
276
          <para>
 
277
            Save the PCI config space for the VGA card.
 
278
          </para>
 
279
        </listitem>
 
280
      </varlistentry>
 
281
    </variablelist>
 
282
  </refsect1>
 
283
 
 
284
  <refsect1 id="files">
 
285
    <title>FILES</title>
 
286
    <variablelist>
 
287
      <varlistentry>
 
288
        <term><filename>/etc/pm/config.d</filename></term>
 
289
        <listitem>
 
290
          <para>
 
291
            The files in this directory are evaluated in C sort order. 
 
292
            These files can be provided by individual packages outside 
 
293
            of pm-utils. If a global configuration variable is set, the 
 
294
            value set to will be appended to the previous value.
 
295
            If any other variable is set, it will be ignored. 
 
296
            The syntax is simply: VAR_NAME = value.
 
297
            See the
 
298
            CONFIGURATION VARIABLES section for valid variables defined
 
299
            by pm-utils. External packages can define others, see
 
300
            their respective documentation for more information.
 
301
          </para>
 
302
        </listitem>
 
303
      </varlistentry>
 
304
      <varlistentry>
 
305
        <term><filename>/etc/pm/sleep.d</filename></term>
 
306
        <term><filename>/usr/lib/pm-utils/sleep.d</filename></term>
 
307
        <listitem>
 
308
          <para>
 
309
            Programs in these directories (we call them hooks) are 
 
310
            combined and executed in C sort order before suspend and 
 
311
            hibernate with as argument 'suspend' or 'hibernate'.
 
312
            Afterwards they are called  in reverse order with
 
313
            argument 'resume' and 'thaw' respectively.
 
314
            If both directories contain a similar named file,
 
315
            the one in /etc/pm/sleep.d will get preference. It
 
316
            is possible to disable a hook in the distribution
 
317
            directory by putting a non-executable file in 
 
318
            /etc/pm/sleep.d, or by adding it to the HOOK_BLACKLIST 
 
319
            configuration variable.
 
320
          </para>
 
321
        </listitem>
 
322
      </varlistentry>
 
323
      <varlistentry>
 
324
        <term><filename>/var/log/pm-suspend.log</filename></term>
 
325
        <listitem>
 
326
          <para>
 
327
            The log file shows what was done on the last suspend/hibernate
 
328
            and resume/thaw.
 
329
          </para>
 
330
        </listitem>
 
331
      </varlistentry>
 
332
    </variablelist>
 
333
  </refsect1>
 
334
 
 
335
  <refsect1 id="config_vars">
 
336
    <title>CONFIGURATION VARIABLES</title>
 
337
    <para>
 
338
      Configuration variables defined by pm-utils. These can be set 
 
339
      in any file in /etc/pm/config.d
 
340
    </para>
 
341
 
 
342
    <variablelist>
 
343
      <varlistentry>
 
344
        <term><envar>SLEEP_MODULE [=kernel]</envar></term>
 
345
        <listitem>
 
346
          <para>
 
347
            The default suspend backend to use. Valid values are:
 
348
            <variablelist>
 
349
              <varlistentry>
 
350
                <term><parameter>kernel</parameter></term>
 
351
                <listitem>
 
352
                  <para>
 
353
                    The built-in kernel suspend/resume support.
 
354
                    Use this if nothing else is supported on your system.
 
355
                </para>
 
356
                </listitem>
 
357
              </varlistentry>
 
358
              <varlistentry>
 
359
                <term><parameter>uswsusp</parameter></term>
 
360
                <listitem>
 
361
                  <para>
 
362
                    If your system has support for the userspace
 
363
                    suspend programs (s2ram/s2disk/s2both), then use this.
 
364
                  </para>
 
365
                </listitem>
 
366
              </varlistentry>
 
367
              <varlistentry>
 
368
                <term><parameter>tuxonice</parameter></term>
 
369
                <listitem>
 
370
                  <para>
 
371
                    If your system has support for tuxonice/suspend2, use this.
 
372
                  </para>
 
373
                </listitem>
 
374
              </varlistentry>
 
375
            </variablelist>
 
376
          </para>
 
377
        </listitem>
 
378
      </varlistentry>
 
379
      <varlistentry>
 
380
        <term><envar>HIBERNATE_RESUME_POST_VIDEO [=no]</envar></term>
 
381
        <listitem>
 
382
          <para>
 
383
            If video should be posted after hibernate, just like
 
384
            after suspend. You should not normally need to set this.
 
385
          </para>
 
386
        </listitem>
 
387
      </varlistentry>
 
388
      <varlistentry>
 
389
        <term><envar>SUSPEND_MODULES</envar></term>
 
390
        <listitem>
 
391
          <para>
 
392
            Space separated list of modules to unload before suspend.
 
393
          </para>
 
394
        </listitem>
 
395
      </varlistentry>
 
396
      <varlistentry>
 
397
        <term><envar>HOOK_BLACKLIST</envar></term>
 
398
        <listitem>
 
399
          <para>
 
400
            Space separated list of hooks that should be disabled.
 
401
          </para>
 
402
        </listitem>
 
403
      </varlistentry>
 
404
      <varlistentry>
 
405
        <term><envar>HIBERNATE_MODE</envar></term>
 
406
        <listitem>
 
407
          <para>
 
408
            Default method to power down the system when hibernating.
 
409
            If not set, the system will use the kernel default as a
 
410
            default value.
 
411
            Check /sys/power/disk for valid values. The default value
 
412
            will be surrounded by [square brackets].
 
413
          </para>
 
414
        </listitem>
 
415
      </varlistentry>
 
416
    </variablelist>
 
417
  </refsect1>
 
418
 
 
419
  <refsect1 id="bugs">
 
420
    <title>BUGS</title>
 
421
    <para>
 
422
      The upstream <acronym>BTS</acronym> can be found
 
423
      at <ulink url="https://bugs.freedesktop.org/"/>.
 
424
      Select 'pm-utils' as product.
 
425
    </para>
 
426
  </refsect1>
 
427
 
 
428
  <refsect1 id="see_also">
 
429
    <title>SEE ALSO</title>
 
430
    <!-- In alpabetical order. -->
 
431
    <para>
 
432
      <citerefentry>
 
433
        <refentrytitle>s2ram</refentrytitle>
 
434
        <manvolnum>8</manvolnum>
 
435
      </citerefentry>,
 
436
      <citerefentry>
 
437
        <refentrytitle>s2disk</refentrytitle>
 
438
        <manvolnum>8</manvolnum>
 
439
      </citerefentry>,
 
440
      <citerefentry>
 
441
        <refentrytitle>s2both</refentrytitle>
 
442
        <manvolnum>8</manvolnum>
 
443
      </citerefentry>,
 
444
      <citerefentry>
 
445
        <refentrytitle>pm-is-supported</refentrytitle>
 
446
        <manvolnum>1</manvolnum>
 
447
      </citerefentry>,
 
448
      <citerefentry>
 
449
        <refentrytitle>pm-powersave</refentrytitle>
 
450
        <manvolnum>8</manvolnum>
 
451
      </citerefentry>,
 
452
      <citerefentry>
 
453
        <refentrytitle>vbetool</refentrytitle>
 
454
        <manvolnum>8</manvolnum>
 
455
      </citerefentry>,
 
456
      <citerefentry>
 
457
        <refentrytitle>radeontool</refentrytitle>
 
458
        <manvolnum>8</manvolnum>
 
459
      </citerefentry> 
 
460
    </para>
 
461
  </refsect1>
 
462
</refentry>