RIO(4) RIO(4)
NAME
rio - window system files
SYNOPSIS
rio [ -i 'cmd' ] [ -k 'kbdcmd' ] [ -s ] [ -b ] [ -f font ]
DESCRIPTION
The window system rio serves a variety of files for reading,
writing, and controlling windows. Some of them are virtual
versions of system files for dealing with the display, key-
board, and mouse; others control operations of the window
system itself. Rio posts its service in the /srv directory,
using a name constructed from a catenation of the user ID
and a process id; the environment variable $wsys is set to
this service name within processes running under the control
of each invocation of rio. Similarly, rio posts a named pipe
to access the window creation features (see window in
rio(1)) from outside its name space; this is named in $wctl.
A mount (see bind(1)) of $wsys causes rio to create a new
window; the attach specifier in the mount gives the coordi-
nates of the created window. The syntax of the specifier is
the same as the arguments to window (see rio(1)). By
default, the window is sized and placed automatically. It
is always necessary, however, to provide the process id of
the process to whom to deliver notes generated by DEL char-
acters and hangups in that window. That pid is specified by
including the string -pid pid in the attach specifier. (See
the Examples section q.v.)
When a window is created either by the window command (see
rio(1)) or by using the menu supplied by rio, this server is
mounted on /mnt/wsys and also /dev; the files mentioned here
appear in both those directories.
Some of these files supply virtual versions of services
available from the underlying environment, in particular the
character terminal files cons and kbd (see kbdfs(8)), and
the mouse files mouse(3) and cursor, each specific to the
window. Note that the draw(3) device multiplexes itself;
rio places windows but does not mediate programs' access to
the display device.
Other files are unique to rio.
cons a virtual version of the standard terminal file from
kbdfs(8). Rio supplies extra editing features and a
scroll bar (see rio(1)).
consctl controls interpretation of console input. Writing
strings to it sets these modes: rawon turns on raw
Page 1 Plan 9 (printed 12/30/24)
RIO(4) RIO(4)
mode; rawoff turns off raw mode; holdon turns on
hold mode; holdoff turns off hold mode. Closing the
file makes the window revert to default state (raw
off, hold off).
kbd represents the raw keyboard events (see kbdfs(8))
for the corresponding window. While open, navigation
keys and input on the cons file is disabled.
cursor Like mouse (q.v.), a multiplexed version of the
underlying device file, in this case representing
the appearance of the mouse cursor when the mouse is
within the corresponding window.
label initially contains a string with the process ID of
the lead process in the window and the command being
executed there. It may be written and is used as a
tag when the window is hidden.
mouse is a virtual version of the standard mouse file (see
mouse(3)). Opening it turns off scrolling, editing,
and rio-supplied menus in the associated window. In
a standard mouse message, the first character is m,
but rio will send an otherwise normal message with
the first character r if the corresponding window
has been resized. The application must then call
getwindow (see graphics(2)) to re-establish its
state in the newly moved or changed window. Reading
the mouse file blocks until the mouse moves or a
button changes. Mouse movements or button changes
are invisible when the mouse cursor is located out-
side the window, except that if the mouse leaves the
window while a button is pressed, it will continue
receiving mouse data until the button is released.
screen is a read-only file reporting the depth, coordi-
nates, and raster image corresponding to the entire
underlying display, in the uncompressed format
defined in image(6).
snarf returns the string currently in the snarf buffer.
Writing this file sets the contents of the snarf
buffer. When rio is run recursively, the inner
instance uses the snarf buffer of the parent, rather
than managing its own.
text returns the full contents of the window. Write
appends to the window. Truncating clears the windows
contents.
wctl may be read or written. When read, it returns the
location of the window as four decimal integers,
padded to 12 characters as described in image(6):
upper left x and y, lower right x and y. Following
these numbers are strings, also padded to 12 charac-
ters, describing the window's state: hidden or
visible; current or notcurrent. A subsequent read
will block until the window changes size, location,
or state. When written to, wctl accepts messages to
change the size or placement of the associated
Page 2 Plan 9 (printed 12/30/24)
RIO(4) RIO(4)
window, and to create new windows. The messages are
in a command-line like format, with a command name,
possibly followed by options introduced by a minus
sign. The options must be separated by blanks, for
example -dx 100 rather than -dx100.
The commands are resize (change the size and posi-
tion of the window), move (move the window), scroll
(enable scrolling in the window), noscroll (disable
scrolling), set (change selected properties of the
window), top (move the window to the `top', making
it fully visible), bottom (move the window to the
`bottom', perhaps partially or totally obscuring
it), hide (hide the window), unhide (restore a hid-
den window), current (make the window the recipient
of keyboard and mouse input), delete (close the win-
dow and terminate its associated processes) and new
(make a new window). The top and bottom commands do
not change whether the window is current or not.
Neither top nor bottom has any options.
The resize, move, and new commands accept -minx n,
-miny n, -maxx n, and -maxy n options to set the
position of the corresponding edge of the window.
They also accept an option -r minx miny maxx maxy to
set all four at once. The resize and new commands
accept -dx n and -dy n to set the width and height
of the window. By default, rio will choose a conve-
nient geometry automatically.
Finally, the new command accepts an optional shell
command and argument string, given as plain strings
after any standard options, to run in the window
instead of the default rc -i (see rc(1)). The -pid
pid option to new identifies the pid of the process
whose `note group' should receive interrupt and
hangup notes generated in the window. The initial
working directory of the new window may be set by a
-cd directory option. The -hide option causes the
window to be created off-screen, in the hidden
state, while -scroll and -noscroll set the initial
scrolling state of the window; the default is that
of the main program.
The set command accepts a set of parameters in the
same style; only -pid pid is implemented.
So programs outside name spaces controlled by rio
may create windows, wctl new messages may also be
written to the named pipe identified by $wctl.
wdir is a read/write text file containing rio's idea of
the current working directory of the process running
in the window. It is used to fill in the wdir field
of plumb(6) messages rio generates from the plumb
menu item on button 2. The file is writable so the
program may update it; rio is otherwise unaware of
chdir(2) calls its clients make. In particular,
Page 3 Plan 9 (printed 12/30/24)
RIO(4) RIO(4)
rc(1) maintains /dev/wdir in default rio(1) windows.
winid returns the unique and unchangeable ID for the win-
dow; it is a string of digits.
window is the virtual version of /dev/screen. It contains
the depth, coordinates, and uncompressed raster
image corresponding to the associated window.
wsys is a directory containing a subdirectory for each
window, named by the unique ID for that window.
Within each subdirectory are entries corresponding
to several of the special files associated with that
window: cons, consctl, label, mouse, etc.
EXAMPLES
Cause a window to be created in the upper left corner, and
the word `hi' to be printed there.
mount $wsys /tmp 'new -r 0 0 128 64 -pid '$pid
echo hi > /tmp/cons
Start sam(1) in a large horizontal window.
echo new -dx 800 -dy 200 -cd /sys/src/cmd sam > /dev/wctl
Print the screen image of window with id 123.
lp /dev/wsys/123/window
SOURCE
/sys/src/cmd/rio
SEE ALSO
rio(1), draw(3), mouse(3), kbdfs(8), event(2), graphics(2).
Page 4 Plan 9 (printed 12/30/24)