.\" Copyright (c) 1991 - Patrick J. Naughton
.\" Copyright (c) 1990, 2010, Oracle and/or its affiliates. All rights reserved.
.TH xlock 1 "30 November 2010"
.IX "xlock" "" "\f3xlock\f1(1) \(em screen locking utility"
.SH NAME
xlock \- locks the local X display until a password is entered
.SH SYNOPSIS
.B xlock
[
.BI \-display " dsp"
] [
.BI \-help
] [
.BI \-name " resource-name"
] [
.BI \-resources
] [
.BI -/+remote
]
.br
	[
.BI -/+mono
] [
.BI -/+nolock
] [
.BI -/+allowroot
] [
.BI -/+enablesaver
] [
.BI -/+allowaccess
]
.br
	[
.BI -/+echokeys
] [
.BI -/+usefirst
]
[
.BI -/+v
] [
.BI \-delay " usecs"
] [
.BI \-batchcount " num"
]
.br
	[
.BI \-nice " level"
] [
.BI \-timeout " seconds"
]
[
.BI \-saturation " value"
] [
.BI \-font " fontname"
]
.br
	[
.BI \-bg " color"
]
[
.BI \-fg " color"
] [
.BI \-mode " modename"
] [
.BI \-username " textstring"
]
.br
	[
.BI \-password " textstring"
] [
.BI \-info " textstring"
] [
.BI \-validate " textstring"
]
.br
	[
.BI \-invalid " textstring"
]

.SH DESCRIPTION
.B xlock
locks the X server till the user enters their password at the keyboard.
While
.B xlock
is running,
all new server connections are refused.
The screen saver is disabled.
The mouse cursor is turned off.
The screen is blanked and a changing pattern is put on the screen.
If a key or a mouse button is pressed then the user is prompted for the
password of the user who started
.BR xlock .
.sp
If the correct password is typed, then the screen is unlocked and the X
server is restored.  When typing the password Control-U and Control-H are
active as kill and erase respectively.  To return to the locked screen,
click in the small icon version of the changing pattern.
.sp
.SH OPTIONS
.TP 5
.BI \-display \ dsp
The
.I display
option sets the X11 display to lock.
.B xlock
locks all available screens on a given server,
and restricts you to locking only a local server such as
.BI unix:0,
.BI localhost:0,
or
.BI :0
unless you set the
.B \-remote
option.
.TP 5
.BI \-name \ resource-name
.I resource-name
is used instead of
.B XLock
when looking for resources to configure
.BR xlock .
.TP 5
.BI \-mode \ modename
As of this writing there are eight display modes supported
(plus one more for random selection of one of the eight).
.TP 8
.B hop
Hop mode shows the "real plane fractals" from the September 1986 issue of
Scientific American.
.TP 8
.B life
Life mode shows Conway's game of life.
.TP 8
.B qix
Qix mode shows the spinning lines similar to the old video game
by the same name.
.TP 8
.B image
Image mode shows several logos randomly appearing on the screen.
.TP 8
.B swarm
Swarm mode shows a swarm of bees following a wasp.
.TP 8
.B rotor
Rotor mode shows a swirling rotorlike thing.
.TP 8
.B pyro
Pyro mode shows fireworks.
.TP 8
.B flame
Flame mode shows wierd but cool fractals.
.TP 8
.B blank
Blank mode shows nothing but a black screen.
.TP 8
.B random
Random mode picks a random mode from all of the above except blank mode.
.sp
.TP 5
.BI \-delay \ usecs
The
.I delay
option sets the speed at which a mode will operate.  It simply sets the
number of microseconds to delay between batches of animations.  In
blank mode, it is important to set this to some small number of seconds,
because the keyboard and mouse are only checked after each delay, so you
cannot set the delay too high, but a delay of zero would needlessly
consume cpu checking for mouse and keyboard input in a tight loop, since
blank mode has no work to do.
.TP 5
.BI \-batchcount \ num
The
.I batchcount
option sets number of
.I things
to do per batch to
.I num .
In hop mode this refers to the number of pixels rendered in the same color.
In life mode it is the number of generations to let each species live.
In qix mode it is the number of lines rendered in the same color.
In image mode it is the number of logos on screen at once.
In swarm mode it is the number of bees.
In rotor mode it is the number of rotor thingys which whirr...
In pyro mode it is the maximum number flying rockets at one time.
In flame mode it is the number of levels to recurse (larger = more complex).
In blank mode it means nothing.
.TP 5
.BI \-nice \ nicelevel
The
.I nice
option sets system nicelevel of the
.B xlock
process to
.I nicelevel .
.TP 5
.BI \-timeout \ seconds
The
.I timeout
option sets the number of
.I seconds
before the password screen will time out.
.TP 5
.BI \-saturation \ value
The
.I saturation
option sets saturation of the color ramp used to
.I value .
0 is grayscale and 1 is very rich color.  0.4 is a nice pastel.
.TP 5
.BI \-font \ fontname
The
.I font
option sets the font to be used on the prompt screen.
.TP 5
.BI \-fg \ color
The
.I fg
option sets the color of the text on the password screen to
.I color .
.TP 5
.BI \-bg \ color
The
.I bg
option sets the color of the background on the password screen to
.I color .
.sp
.TP 5
.BI \-username \ textstring
.I textstring
is shown in front of user name, defaults to "Name: ".
.TP 5
.BI \-password \ textstring
.I textstring
is the password prompt string, defaults to "Password: ".
.TP 5
.BI \-info \ textstring
.I textstring
is an informational message to tell the user what to do, defaults to
"Enter password to unlock; select icon to lock.".
.TP 5
.BI \-validate \ textstring
.I textstring
.BI \-validate " message shown while validating the password, defaults to
"Validating login..."
.TP 5
.BI \-invalid \ textstring
.I textstring
.BI \-invalid " message shown when password is invalid, defaults to
"Invalid login."
.TP 5
.B \-resources
The
.I resources
option prints the default resource file for
.B xlock
to standard output.
.TP 5
.B -/+remote
The
.I remote
option tells
.B xlock
to not stop you from locking remote X11 servers.  This
option should be used with care and is intended mainly to lock X11 terminals
which cannot run
.B xlock
locally.  If you lock someone else's workstation, they will have to know
.B your
password to unlock it.  Using 
.I +remote
overrides any resource derived values for 
.I remote
and prevents
.B xlock
from being used to lock other X11 servers.  (Use `+'
instead of `-' to override resources for other options that can take the 
`+' modifier similarly.)
.TP 5
.B -/+mono
The
.I mono
option causes
.B xlock
to display monochrome, (black and white) pixels rather
than the default colored ones on color displays.
.TP 5
.B +/-nolock
The
.I nolock
option causes
.B xlock
to only draw the patterns and not lock the display.
A keypress or a mouse click will terminate the screen saver.
.TP 5
.B -/+allowroot
The
.I allowroot
option allows the root password to unlock the server as well as the user
who started
.BR xlock .
.TP 5
.B -/+enablesaver
By default
.B xlock
will disable the normal X server's screen saver since
it is in effect a replacement for it.  Since it is possible to set delay
parameters long enough to cause phosphor burn on some displays, this
option will turn back on the default screensaver which is very careful
to keep most of the screen black.
.TP 5
.B -/+allowaccess
This option is required for servers which do not allow clients to modify
the host access control list.  It is also useful if you need to run x
clients on a server which is locked for some reason...  When allowaccess
is true, the X11 server is left open for clients to attach and thus
lowers the inherent security of this lockscreen.  A side effect of using
this option is that if
.B xlock
is killed -KILL, the access control list is
not lost.
.TP 5
.B -/+echokeys
The
.I echokeys
option causes
.B xlock
to echo '?' characters for each key typed into the
password prompt.  Some consider this a security risk, so the default is
to not echo anything. 
.TP 5
.B -/+usefirst
The
.I usefirst
option causes
.B xlock
to use the keystroke which got you to the password screen
as the first character in the password.  The default is to ignore the first
key pressed.
.TP 5
.B \-v
Verbose mode, tells what options it is going to use.
.sp
.SH **WARNING**
.B xlock
can appear to hang if it is competing with a high-priority process for
the CPU. For example, if
.B xlock
is started after a process with 'nice -20' 
(high priority),
.B xlock
will take  considerable amount of time to respond. 
.sp
.SH BUGS
"kill -KILL
.B xlock
" causes the server that was locked to be unusable, since all hosts
(including localhost) were removed from the access control list
to lock out new X clients, and since
.B xlock
couldn't catch SIGKILL,
it terminated before restoring the access control list.  This will
leave the X server in a state where
\fI "you can no longer connect to that server, and this operation cannot be
reversed unless you reset the server."\fP
.br
		-From the X11R4 Xlib Documentation, Chapter 7.
.SH SEE ALSO
Xlib Documentation.
.sp
.SH AUTHOR
Patrick J. Naughton
.sp
.SH COPYRIGHT
Copyright (c) 1988-91 by Patrick J. Naughton and Sun Microsystems, Inc.
.sp
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.