= ssuspend 1.0.0 =

== About ==

ssuspend is a small c program that locks /sys/power/state, removes zero or more
kernel modules, echoes a suspend mode into /sys/power/state, and then sleeps 30
or so seconds before unlocking that file.  Because it will not wait for the
lock but exit immediately if it cant acquire that lock exclusively, it is safe
to use from window managers where a keyboard shortcut keypress held down too
long or some other race condition might lead to the program being called
multiple times quickly in succession.  Because it is a small program written 
carefully in c, it is fairly safe to make setuid or add to /etc/sudoers.


== Installation ==

=== Configure and Build ===
ssuspend uses GNU autoconf, so it is configured and built
with the standard sequence:
{{{

	./configure
	make
}}}

To install type "make install" or simply copy the executable
"src/ssuspend" to a suitable directory.

=== Using with Fvwm ===

I personally use this with fvwm using the following lines...

{{{
AddToFunc Suspend       "I" Exec exec sudo /usr/local/sbin/ssuspend -x iwl3945
}}}
and 
{{{
Key End     A   MC  Suspend
}}}

so that the laptop sleeps whenever alt-control-end is pressed.

=== Using with acpid ===

I also use the following /etc/acpi/default.sh which will suspend the computer
whenever I hit the power button or the battery gets too low.

this is also in doc/default.sh. I would read it before copying it to /etc/acpi/default.sh 
to make sure you dont lose some other functionality specific to your own distribution
that isn't in this one.

{{{
#!/bin/sh
# /etc/acpi/default.sh
# Default acpi script that takes an entry for all actions
 
set $*
 
group=${1%%/*}
action=${1#*/}
device=$2
id=$3
value=$4
 
#minimum milliamp hours remaining:
MIN_MAH=100
SUSPEND=/usr/local/sbin/ssuspend 
BAT_STATE_FILE=/proc/acpi/battery/BAT0/state
 
logger "ACPI default.sh: group=$group action=$action device=$device id=$id  value=$value  full=$*"
 
log_unhandled() {
    logger "ACPI this event unhandled: $*"
}
 
sleepnow(){
    logger "ACPI default.sh sleepnow(): group=$group action=$action device=$device id=$id  value=$value  full=$*"
    $SUSPEND -X iwl3945
    exit $?
}
 
if [ x$group == xbutton ] ; then
    logger "ACPI default.sh group == button"
    if [ x$action == xpower ] ; then
        logger "ACPI default.sh button/power"
        sleepnow 
    fi  
    if [ x$action == xlid ] ; then
        logger "ACPI default.sh button/lid"
        xset dpms force off 
        exit $?
    fi  
fi
if [ x$group == xbattery ] ; then
    logger "ACPI default.sh group == battery"
    if [ x$action == xbattery ] ; then
        MAH=$( cat $BAT_STATE_FILE |\
                /bin/grep ^remaining|\
                gawk '{print $3 }') 
        if [ $MAH -ge $MIN_MAH ] ; then 
             logger ACPI BAT0 ok, $MAH mah remaining
             exit
        else
             logger ACPI BAT0 dead. use $MAH mah to suspend
             sleepnow 
        fi
    fi  
fi
log_unhandled $*  
exit 


}}}


== OPTIONS ==

{{{
$ ./src/ssuspend -h
ssuspend [options] [module [ module ... ] ]

   each module argument found in /proc/modules is removed in order on the way down, and restored 
       in reverse order on the way back up.

   options are as follows:    -h  or -? or --help                 get this message
    -f  <file> or --file <file>         where to write the new state. defaults to /sys/power/state.
    -s  <state> or --state <state>      what state to write to the control file. defaults to 'disk'.
    -t  <seconds> or --time <seconds>   how many seconds to sleep after resume while holding the lock.
                                        This option defaults to 30 in order to prevent extra keypress 
                                        events from causing double suspends where your laptop resumes 
                                        only to suspend again immediately.
    -x  or --lock-x                     tells ssuspend to lock the screen before suspending
    -X  or --lock-x-nofail              tells ssuspend to lock the screen before suspending if possible, 
                                        but continue in any case.
    -l  or --syslog                     TODO: tells ssuspend to write status information to syslog(3).
    -v  or --verbose                    TODO: tells ssuspend to write status information to standard error.

$ 
}}}