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 3/28/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.
          kbdtap  provides access to the global keyboard input. When
                  opened, global keyboard input to windows is instead
                  given through writes to kbdtap.
          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: current or
                  notcurrent; hidden or visible.  A subsequent read

     Page 2                       Plan 9             (printed 3/28/24)

     RIO(4)                                                     RIO(4)

                  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 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 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
                  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

     Page 3                       Plan 9             (printed 3/28/24)

     RIO(4)                                                     RIO(4)

                  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
          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 3/28/24)