1 files changed, 403 insertions, 0 deletions
diff --git a/static/plan9-4e/man4/rio.4 b/static/plan9-4e/man4/rio.4
new file mode 100644
index 00000000..90e3cbe3
--- /dev/null
+++ b/static/plan9-4e/man4/rio.4
@@ -0,0 +1,403 @@
+.TH RIO 4
+.SH NAME
+rio \- window system files
+.SH SYNOPSIS
+.B rio
+[
+.B -i
+.BI ' cmd '
+]
+[
+.B -s
+]
+[
+.B -f
+.I font
+]
+.SH DESCRIPTION
+The window system
+.I 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, keyboard, and mouse; others control operations
+of the window system itself.
+.I Rio
+posts its service in the
+.B /srv
+directory, using a
+name constructed from a catenation of the user ID
+and a process id; the environment variable
+.BR $wsys
+is set to this service name within processes running under the control
+of each invocation of
+.IR rio .
+Similarly,
+.I rio
+posts a named pipe to access the window creation features
+(see
+.B window
+in
+.IR rio (1))
+from outside
+its name space; this is named in
+.BR $wctl .
+.PP
+A
+.I mount
+(see
+.IR bind (1))
+of
+.B $wsys
+causes
+.I rio
+to create a new window; the attach specifier in the
+.I mount
+gives the coordinates of the created window.
+The syntax of the specifier is the same as the arguments to
+.B window
+(see
+.IR 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 characters and hangups
+in that window.
+That pid is specified by including the string
+.B -pid
+.I pid
+in the attach specifier.  (See the Examples section
+.IR q.v. )
+.PP
+When a window is created either by
+the
+.I window
+command
+(see
+.IR rio (1))
+or by using the menu supplied by
+.IR rio ,
+this server is mounted on
+.BR /mnt/wsys
+and also
+.BR /dev ;
+the files mentioned here
+appear in both those directories.
+.PP
+Some of these files supply virtual versions of services available from the underlying
+environment, in particular the character terminal files
+.IR cons (3),
+and the mouse files
+.IR mouse (3)
+and
+.IR cursor ,
+each specific to the window.
+Note that the
+.IR draw (3)
+device multiplexes itself;
+.IR rio
+places windows but does not mediate programs' access to the display device.
+.PP
+Other files are unique to
+.IR rio .
+.TF window
+.TP
+.B cons
+is a virtual version of the standard terminal file
+.IR cons (3).
+.I Rio
+supplies extra editing features and a scroll bar
+(see
+.IR rio (1)).
+.TP
+.B consctl
+controls interpretation of keyboard input.
+Writing strings to it sets these modes:
+.B rawon
+turns on raw mode;
+.B rawoff
+turns off raw mode;
+.B holdon
+turns on hold mode;
+.B holdoff
+turns off hold mode.
+Closing the file makes the window revert to default state
+(raw off, hold off).
+.TP
+.B cursor
+Like
+.B mouse
+.RI ( 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.
+.TP
+.B 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.
+.TP
+.B mouse
+is a virtual version of the standard mouse file (see
+.IR mouse (3)).
+Opening it turns off scrolling, editing, and
+.IR rio -supplied
+menus in the associated
+window.
+In a standard mouse message, the first character is
+.BR m ,
+but
+.I rio
+will send an otherwise normal message with the first character
+.B r
+if the corresponding window has been resized.
+The application must then call
+.B getwindow
+(see
+.IR graphics (2))
+to re-establish its state in the newly moved or changed window.
+Reading the
+.B mouse
+file blocks until the mouse moves or a button changes.
+Mouse movements or button changes are invisible when the mouse cursor
+is located outside 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.
+.TP
+.B screen
+is a read-only file reporting the depth, coordinates, and raster image corresponding to the entire
+underlying display,
+in the uncompressed format defined in
+.IR image (6).
+.TP
+.B snarf
+returns the string currently in the snarf buffer.
+Writing this file sets the contents of the snarf buffer.
+When
+.I rio
+is run recursively, the inner instance uses the snarf buffer of the parent, rather than
+managing its own.
+.TP
+.B text
+returns the full contents of the window.
+It may not be written.
+.TP
+.B wctl
+may be read or written.
+When read, it returns the location of the window as four decimal integers formatted
+in the usual 12-character style: upper left
+.I x
+and
+.IR y ,
+lower right
+.I x
+and
+.IR y .
+Following these numbers are strings describing the window's state:
+.B hidden
+or
+.BR visible ;
+.B current
+or
+.BR notcurrent .
+A subsequent read will block until the window changes size, location, or state.
+When written to,
+.B wctl
+accepts messages to change the size or placement of the associated 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
+.B -dx 100
+rather than
+.BR -dx100 .
+.IP
+The commands are
+.B resize
+(change the size and position of the window),
+.B move
+(move the window),
+.B scroll
+(enable scrolling in the window),
+.B noscroll
+(disable scrolling),
+.B set
+(change selected properties of the window),
+.B top
+(move the window to the `top', making it fully visible),
+.B bottom
+(move the window to the `bottom', perhaps partially or totally obscuring it),
+.B hide
+(hide the window),
+.B unhide
+(restore a hidden window),
+.B current
+(make the window the recipient of keyboard and mouse input),
+and
+.B new
+(make a new window).
+The
+.B top
+and
+.B bottom
+commands do not change whether the window is current or not;
+the others always make the affected window current.
+.IP
+Neither
+.B top
+nor
+.B bottom
+has any options.
+The
+.BR resize ,
+.BR move ,
+and
+.B new
+commands accept
+.B -minx
+.IR n ,
+.B -miny
+.IR n ,
+.B -maxx
+.IR n ,
+and
+.BR -maxy
+.I n
+options to set the position of the corresponding edge of the window.
+They also accept an option
+.B -r
+.I minx miny maxx maxy
+to set all four at once.
+The
+.B resize
+and
+.B new
+commands accept
+.B -dx
+.I n
+and
+.B -dy
+.I n
+to set the width and height of the window.
+By default,
+.I rio
+will choose a convenient geometry automatically.
+.IP
+Finally, the
+.B 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
+.B rc
+.B -i
+(see
+.IR rc (1)).
+The
+.B -pid
+.I pid
+option to
+.B new
+identifies the
+.I 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
+.B -cd
+.I directory
+option.
+The
+.B -hide
+option causes the window to be created off-screen, in the hidden state.
+.IP
+The
+.B set
+command accepts a set of parameters in the same style; only
+.B -pid
+.I pid
+is implemented.
+.IP
+So programs outside name spaces controlled by
+.I rio
+may create windows,
+.B wctl
+.B new
+messages may also be written to the named pipe identified by
+.BR $wctl .
+.TP
+.B wdir
+is a read/write text file containing
+.IR rio 's
+idea of the current working directory of the process running in the window.
+It is used to fill in the
+.B wdir
+field of
+.IR plumb (6)
+messages
+.I rio
+generates from the
+.B plumb
+menu item on button 2.
+The file is writable so the program may update it;
+.I rio
+is otherwise unaware of
+.IR chdir (2)
+calls its clients make.
+In particular,
+.IR rc (1)
+maintains
+.B /dev/wdir
+in default
+.IR rio (1)
+windows.
+.TP
+.B winid
+returns the unique and unchangeable ID for the window;
+it is a string of digits.
+.TP
+.B window
+is the virtual version of
+.BR /dev/screen .
+It contains the depth, coordinates, and
+uncompressed raster image corresponding to the associated
+window.
+.TP
+.B 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:
+.BR cons ,
+.BR consctl ,
+.BR label ,
+.BR mouse ,
+etc.
+.SH EXAMPLES
+Cause a window to be created in the upper left corner,
+and the word
+.L hi
+to be printed there.
+.IP
+.EX
+mount $riosrv /tmp 'new -r 0 0 128 64 -pid '$pid
+echo hi > /tmp/cons
+.EE
+.PP
+Start
+.IR sam (1)
+in a large horizontal window.
+.IP
+.EX
+echo new -dx 800 -dy 200 -cd /sys/src/cmd sam > /dev/wctl
+.EE
+.PP
+Print the screen image of window with id 123.
+.IP
+.EX
+lp /dev/wsys/123/window
+.EE
+.SH SOURCE
+.B /sys/src/cmd/rio
+.SH SEE ALSO
+.IR rio (1),
+.IR draw (3),
+.IR mouse (3),
+.IR cons (3),
+.IR event (2),
+.IR graphics (2).