The missing sleepwatcher manpage

NAME
sleepwatcher – daemon to monitor sleep, wakeup and idleness of a Mac

SYNOPSIS
sleepwatcher [-n] [-v] [-V] [-d] [-g] [-f configfile] [-p pidfile]
[-a[allowsleepcommand]] [-c cantsleepcommand]
[-s sleepcommand] [-w wakeupcommand] [-D displaydimcommand]
[-E displayundimcommand] [-S displaysleepcommand]
[-W displaywakeupcommand] [-t timeout -i idlecommand
[-R idleresumecommand]] [-b break -r resumecommand]
[-P plugcommand] [-U unplugcommand]

DESCRIPTION
sleepwatcher is a program that monitors sleep, wakeup and idleness of a Mac. It can be used to execute a Unix command when the Mac or the display of the Mac goes to sleep mode or wakes up, after a given time without user interaction or when the user resumes activity after a break or when the power supply of a Mac notebook is attached or detached. It also can send the Mac to sleep mode or retrieve the time since last user activity.

Command line options:

-n, --now
Sleep now and exit, ignoring other options.

-v, --version
Display version and copyright information and exit.

-V, --verbose
Log any action sleepwatcher performs, either to stdout or, when running as daemon, to the syslog.

-d, --daemon
Run as background daemon. Don't use this option when starting sleepwatcher via launchd(8).

-g, --getidletime
Print the time (in 0.1 seconds) of no keyboard or mouse activity to stdout and exit, ignoring other options.

-f configfile, --config configfile
Read additional configuration options from configfile. contains options in the form option [ = value ] where option is one of the long command line options (without --). sleepwatcher rereads its configuration file when it receives a hangup signal, SIGHUP.

-p pidfile, --pidfile pidfile
Write the process id of sleepwatcher to pidfile.

-a[allowsleepcommand], --allowsleep[=allowsleepcommand]
Allow the Mac to idle sleep only when allowsleepcommand returns a zero exit code. Without allowsleepcommand, this option prevents idle sleep at all. When the -a option is not used at all, sleepwatcher allows idle sleep unconditionally. (Note: no space after the -a.)

-c cantsleepcommand, --cantsleep cantsleepcommand
Execute cantsleepcommand when the Mac retracts an attempt to sleep that was previously allowed by the -a option, but vetoed by another process that wants to prevent idle sleep. Note that the kernel notifies sleepwatcher about the retracted sleep only when it previously asked it if sleeping is allowed. There might be canceled idle sleep attempts without the -a and -c commands executed at all.

-s sleepcommand, --sleep sleepcommand
Execute sleepcommand when the Mac is put to sleep mode. sleepcommand must not take longer than 15 seconds because after this timeout the sleep mode is forced by the system.

-w wakeupcommand, --wakeup wakeupcommand
Execute wakeupcommand when the Mac wakes up from sleep mode.

-D displaydimcommand, --displaydim displaydimcommand
Execute displaydimcommand when the display of the Mac is dimmed. Note that the displaydimcommand is executed when the Mac goes to sleep mode, too.

-E displayundimcommand, --displayundim displayundimcommand
Execute displayundimcommand when the display of the Mac is undimmed without having gone to sleep. Note that the displayundimcommand is not executed when the Mac or the display of the Mac wakes up from sleep mode.

-S displaysleepcommand, --displaysleep displaysleepcommand
Execute displaysleepcommand when the display of the Mac is put to sleep mode.

-W displaywakeupcommand, --displaywakeup displaywakeupcommand
Execute displaywakeupcommand when the display of the Mac wakes up from sleep mode. Note that the displaywakeupcommand is executed when the Mac wakes up from sleep mode, too.

-t timeout, --timeout timeout
Set the timeout (in 0.1 seconds) for the -i option, i. e. execute idlecommand after this time of no user interactivity.

-i idlecommand, --idle idlecommand
Execute idlecommand after the time of no user interactivity set with the -t option.

-R idleresumecommand, --idleresume idleresumecommand
Execute idleresumecommand when the user resumes input after the -i command was executed due to an idle time.

-b breakduration, --break breakduration
Set the breakduration (in 0.1 seconds) for the -r option, i. e. execute resumecommand when the user resumes input after a break of at least this duration.

-r resumecommand, --resume resumecommand
Execute resumecommand when the user resumes keyboard or mouse activity after a break with a duration given with the -b option.

-P plugcommand, --plug plugcommand
Execute plugcommand when a Mac notebook is connected to the power supply.

-U unplugcommand, --unplug unplugcommand
Execute unplugcommand when a Mac notebook is disconnected from the power supply.

SEE ALSO
pmset(1), launchd(8), SystemStarter(8)

BUGS
The -t -i and -b -r options only work when the Mac OS X GUI is running, so they cannot be used when sleepwatcher is started as a system-wide launchd(8) agent during system startup.

Any user with execute permission for sleepwatcher can send the Mac to sleep mode with the -n option, making the system unavailable for other (remote) users.

ACKNOWLEDGEMENTS
Thanks to Daniel Griscom for the idea and code for the deny sleep feature. Thanks to Darren Creutz for the idea and code for the display sleep support. Thanks to Michael Lee for the ideas for idleness handling within sleepwatcher. Thanks to Brian Jenkins for the idea and code for the power supply feature. And thanks to Louis Pan for the idea and code for the can't sleep callback.