xss

README.md

  1xss
  2===
  3
  4[xss](http://github.com/9wm/xss) is a suite of X screensaver
  5utilities.  You can use shell scripts to glue the tools together to
  6build your own screen saver and/or locker.  You can use any
  7`xscreensaver` hack instead of the built-in `magic` hack, or you can use
  8`xlock` if you prefer.
  9
 10
 11The programs
 12------------
 13
 14`xss` uses the decades-old MIT-SCREEN-SAVER extension to launch a
 15program when the X server turns on the built-in screen saver.  Unlike
 16`xautolock`, `xss` blocks until the X server says it's time to do
 17something.
 18
 19`xsswin` makes a full-screen black window and runs some other program,
 20passing along the window ID in the environment (`$XSS_WINDOW`) and
 21possibly as an argument (`XSS_WINDOW` in argv is replaced with the ID).
 22
 23`xkeygrab` grabs the keyboard and mouse, and echoes all typed lines to
 24stdout.
 25
 26`xcursorpos` prints out the x and y coordinates of the cursor.
 27
 28`xbell` sounds the X server's bell.
 29
 30`magic` is a reimplementation of the "magic" screen saver from After
 31Dark.  It might look weird at 8bpp.
 32
 33
 34Examples
 35--------
 36
 37Tell the X server to launch the screen saver after 90 seconds idle:
 38
 39    $ xset s 90
 40
 41Run like `xautolock`:
 42
 43    $ xss xlock -mode qix &
 44
 45Just run a screen saver, don't lock
 46
 47    $ xss -w /usr/lib/xscreensaver/deco -window-id XSS_WINDOW &
 48
 49Launch a program called "screenlock" when you're idle:
 50
 51    $ xss screenlock &
 52
 53An simple "screenlock" script:
 54
 55    #! /bin/sh
 56    
 57    xsswin magic XSS_WINDOW & pid=$!
 58    xkeygrab | (while read l; do [ "$l" != "secret" ] && break; done)
 59    kill $pid
 60
 61A more complex "screenlock" script which locks the screen awaiting a
 62pass phrase with the right md5 checksum.  After 4 seconds of being
 63locked, it pauses mpd (iff it was playing).  When the screen is
 64unlocked, mpd is resumed (iff it was playing beforehand).  The script
 65won't lock if the cursor's at the top of the screen.
 66
 67    #! /bin/sh
 68    
 69    xcursorpos | (read x y; [ $y -lt 20 ]) && exit 0
 70    mpc | fgrep -q '[playing]' && playing=1
 71    xsswin magic XSS_WINDOW 2>/dev/null & xsswin=$!
 72    (sleep 4; [ $playing ] && kill -0 $xsswin 2>/dev/null && mpc --no-status pause) &
 73    xkeygrab | (
 74        while read l; do
 75            md5s=$(echo -n $l | md5sum | cut -d\  -f1)
 76            if [ $md5s = 'a37c87558d98e9fe0484e09070268be1' ]; then
 77                break
 78            fi
 79            xbell
 80        done
 81        )
 82    kill $xsswin
 83    [ $playing ] && mpc --no-status play
 84
 85
 86History
 87-------
 88
 89AIX apparently had something also called `xss` which did almost exactly
 90what mine does, but with command-line options.  `magic` is similar to
 91the `qix` hack from xscreensaver and xlock.  I'm not aware of anything
 92else like the rest of the programs, which is why I wrote them.
 93
 94I lifted some code from `beforelight` from the X11 distribution, and
 95from `slock` from [suckless.org](http://suckless.org/).  Both have a
 96BSD/X11-like license.
 97
 98
 99------
100
101Neale Pickett <neale@woozle.org>