.\" -*-nroff-*-
.TH xatom 1 "13 September 2007" "Straylight/Edgeware" "xtoys"
.SH NAME
xatom \- manipulate properties on X windows
.SH SYNOPSIS
.B xatom
.RB [ \- d
.IR display ]
.RB [ \- w
.IR window ]
.I command
.PP
where
.I command
is one of:
.PP
.B help
.RI [ command ...]
.br
.B get
.I property
.br
.B set
.I property
.I value
.br
.B delete
.I property
.br
.B wait
.I property
.RI [ value ...]
.SH DESCRIPTION
The
.B xatom
program manipulates properties of a simple kind on X windows.  It deals
only with those properties whose value is a single X atom.  It is
capable of setting, reading, and deleting properties, and also waiting
until a particular property is set, maybe to one of a number of given
values.
.PP
The program provides a number of subcommands, by which the various
operations may be carried out.
.SS "Global options"
Before the command name,
.I "global options"
may be given.  The following global options are supported.
.TP
.BR "\-h, \-\-help " [\fIcommand\fP...]
Writes a brief summary of
.BR xatom 's
various operations to standard output, and returns a successful exit
status.  With command names, gives help on those commands.
.TP
.B "\-v, \-\-version"
Writes the program's version number to standard output, and returns a
successful exit status.
.TP
.B "\-u, \-\-usage"
Writes a very terse command line summary to standard output, and returns
a successful exit status.
.TP
.BI "\-d, \-\-display=" display
Connect to the X server named by
.I display
rather than the default, which is to consult the
.B DISPLAY
environment variable.
.TP
.BI "\-w, \-\-window=" window
Manipulate properties on the window whose ID is
.I window
rather than the default, which is to use the root window of the screen
named by
.IR display .
If
.I window
is the string
.B choose
then the window can be chosen interactively: the
.B xatom
program will grab the pointer and wait for a button-1 click over a
window.  A button-3 click causes
.B xatom
to quit (and return an unsuccessful exit status).
.SH "COMMAND REFERENCE"
.SS "help"
The
.B help
command behaves exactly as the
.B \-\-help
option.  With no arguments, it shows an overview of
.BR xatom 's
options; with arguments, it described the named subcommands.
.SS "get"
The
.B get
command retrieves the named
.I property
from the specified window, and reports its value on standard output.
.PP
If the property wasn't found, or its value wasn't a single atom, nothing
is written, but a successful exit status is still returned.  If a value
was found, it is written and followed by a newline: therefore a client
can distinguish an empty value from no value at all.
.SS "set"
The
.B set
command sets the named
.I property
to have the specified
.IR value ,
overwriting any existing value.
.SS "delete"
The
.B delete
command removes the named
.I property
from the window.  If no such property exists, nothing happens.
.SS "wait"
The
.B wait
command waits on a particular
.IR property .
If any
.IR value s
are specified, then the command waits until the property's value matches
one of the specified
.IR value s:
if it already matches one of them then the command won't wait.
If no
.IR value s
are specified, then the command waits until the property is set to any
value; again, if it is already set, the command returns immediately.
.PP
If exactly one
.I value
is given, the command produces no output; otherwise, it writes the new
value of the property, as for the
.B get
command.
.SH EXAMPLE
The author uses this command at the end of his
.BR .xinitrc
file, to control the duration of his X session.  Specifically, he uses
the code
.PP
.RS
.ft B
.nf
xatom set MDW_SHUTDOWN READY
xatom wait MDW_SHUTDOWN SHUTDOWN
xatom delete MDW_SHUTDOWN
.fi
.RE
The script
.B xshutdown
looks like this.
.PP
.RS
.ft B
.nf
#! /bin/sh
set -e
me=$(basename $0)
case "$(xatom get MDW_SHUTDOWN)" in
  READY) ;;
  *) xmsg -e -t $me "Nobody's waiting for my signal."; exit 1;;
esac
case "$(xmsg -q -t $me \
  "Really shut down this session?" :_Shutdown \~gtk-cancel)" in
  _Shutdown)
    xatom set MDW_SHUTDOWN SHUTDOWN
    ;;
esac
.fi
.RE
.SH BUGS
None currently known.
.SH SEE ALSO
.BR xmsg (1),
.BR XChangeProperty (3x),
.BR XGetWindowProperty (3x),
.BR XDeleteProperty (3x).
.SH AUTHOR
Mark Wooding (mdw@distorted.org.uk).