RIO(4)                                                     RIO(4)

     NAME
          rio - window system files

     SYNOPSIS
          rio [ -i 'cmd' ] [ -s ] [ -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(3), 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    is a virtual version of the standard terminal file
                  cons(3). Rio supplies extra editing features and a
                  scroll bar (see rio(1)).
          consctl controls interpretation of keyboard input.  Writing
                  strings to it sets these modes: rawon turns on raw
                  mode; rawoff turns off raw mode; holdon turns on

     Page 1                       Plan 9            (printed 11/23/24)

     RIO(4)                                                     RIO(4)

                  hold mode; holdoff turns off hold mode.  Closing the
                  file makes the window revert to default state (raw
                  off, hold off).
          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
                  underyling 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.  It may not
                  be written.
          wctl    may be read or written.  When read, it returns the
                  location of the window as four decimal integers for-
                  matted in the usual 12-character style: upper left x
                  and y, lower right x and y. Following these numbers
                  are strings 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 win-
                  dow, 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

     Page 2                       Plan 9            (printed 11/23/24)

     RIO(4)                                                     RIO(4)

                  position of the window), move (move the window),
                  scroll (enable scrolling in the window), noscroll
                  (disable scrolling), 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 hidden window), current (make the window
                  the recipient of keyboard and mouse input), and new
                  (make a new window).  The top and bottom commands do
                  not change whether the window is current or not; the
                  others always make the affected window current.
                  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 convenient
                  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
                  option used when mounting rio to make a new window
                  is disregarded by the wctl file.  The initial work-
                  ing directory of the new window may be set by a -cd
                  directory option.
                  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,
                  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

     Page 3                       Plan 9            (printed 11/23/24)

     RIO(4)                                                     RIO(4)

          the word `hi' to be printed there.

               mount $riosrv /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), cons(3), event(2), graphics(2).

     Page 4                       Plan 9            (printed 11/23/24)