summaryrefslogtreecommitdiff
path: root/pm/HOWTO.hooks
blob: 4e6cebc63d87db0af271a94c726780fa86804d17 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
How to write a pm-utils hook:

PARAMETERS

A pm-utils hook is simply an executable file that accepts a single parameter.
For hooks in sleep.d, the potential values of that parameter are:
suspend -- The hook MUST perform whatever action is appropriate when the
	system is preparing for S3 sleep (or its equivalent).
suspend_hybrid -- The hook MUST perform whatever action is appropriate 
		  when entering suspend mode.  The hook SHOULD also save
		  any state it may need to bring the system back from 
		  hibernate mode.
resume -- The hook MUST perform whatever action is appropriate when the 
	system is coming out of suspend.
hibernate -- The hook MUST perform whatever action is appropriate when 
	the system is preparing for suspend-to-disk.
thaw -- The hook MUST perform whatever action is appropriate when the system
	is coming out of suspend-to-disk.
help -- If your hook parses the PM_CMDLINE environment variable for switches, 
	this function SHOULD output text describing the parameters it parses
	in a format easily understandable by an end-user.

For hooks in power.d, the potential values of that parameter are:
true -- the hook MUST perform whatever action is appropriate when the system 
	transitions TO battery power.
false -- The hook MUST perform whatever action is appropriate when the system
	transitions FROM battery power.

NAMING SCHEME

All hooks are run in lexical sort order according to the C locale.

SLEEP.D SPECIFIC NOTES

For any given sleep/wakeup cycle, the hooks in sleep.d are run twice:
* Once in C lexical sort order before the system goes to sleep, and
* Once in reverse C lexical sort order when the system wakes up.

CONVENIENCE FUNCTIONS

If your hook is a shell script that supports POSIX/SuS compatible syntax, you
MAY source /usr/lib/pm-utils/functions, which will make the following 
convenience functions available:
1:  try_lock
	try_lock expects a single parameter -- the name of the lock to 
	try to acquire.  Exit code denotes success.
2:  spin_lock
	Wrapper around try_lock.  Second parameter is the number of seconds 
	to wait for the lock before giving up.  If no second parameter
	is passed, this function will wait forever.
3:  release_lock
	Release a previously acquired lock.  First parameter is the name of the
	lock.
4:  get_power_status
	Outputs our power source on stdout.
5:  modunload
	Unload a module.  Exit code denotes success.
6:  modreload
	Reload all the modules unloaded by modunload.
7:  stopservice
	Stop a service.  First parameter is the name of the service to stop.
8:  restartservice
	Restart a service.  Service must have been stopped by stopservice.
9:  savestate
	Save state piped into this function on stdin.  First parameter is the 
	name of the state being saved.  If a second parameter is passed, this
	function will use it instead of stdin.
10: restorestate
	Outputs state saved by savestate on stdout.  The first parameter is the
	name of the state to restore.
11: disablehook
	Prevent a hook from running.  The exact name of the hook (including
	numberic prefix) must be passed.