X-Git-Url: https://git.distorted.org.uk/~mdw/xtoys/blobdiff_plain/cc52f3b6f297a8af8377a11925f789db126fea89..01a2fe8e4dc87fdb256d95504482acf0fb06b67b:/xatom.1

diff --git a/xatom.1 b/xatom.1
new file mode 100644
index 0000000..59d7ae8
--- /dev/null
+++ b/xatom.1
@@ -0,0 +1,186 @@
+.\" -*-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).