rio man page on Plan9

Printed from

RIO(1)									RIO(1)

       rio, label, window, wloc - window system

       rio [ -i 'cmd' ] [ -k 'kbdcmd' ] [ -s ] [ -f font ]

       label name

       window  [ -m ] [ -r minx miny maxx maxy ] [ -dx n ] [ -dy n ] [ -minx n
       ] [ -miny n ] [ -maxx n ] [ -maxy n ] [ -cd dir ] [ -hide ] [ -scroll ]
       [ -noscroll ] [ cmd arg ...  ]


       Rio  manages  asynchronous layers of text, or windows, on a raster dis‐
       play.  It also serves a variety of files	 for  communicating  with  and
       controlling windows; these are discussed in section rio(4).

       The  rio	 command  starts  a new instance of the window system.	Its -i
       option names a startup script, which typically contains several	window
       commands	 generated  by wloc.  The -k option causes rio to run the com‐
       mand kbdcmd at startup and allow it to provide characters  as  keyboard
       input;  the  keyboard  program  described  in bitsyload(1) is the usual

       The -s option initializes windows so that text scrolls; the default  is
       not  to	scroll.	  The font argument names a font used to display text,
       both in rio's menus and as a default for any programs  running  in  its
       windows;	 it also establishes the environment variable $font.  If -f is
       not given, rio uses the imported value of $font if  set;	 otherwise  it
       imports	the  default font from the underlying graphics server, usually
       the terminal's operating system.

       The label command changes a window's identifying name.

       The window command creates a window.  By default, it  creates  a	 shell
       window  and  sizes and places it automatically.	The geometry arguments
       control the size (dx, dy) and placement (minx, miny, maxx,  maxy);  the
       units  are  pixels  with the upper left corner of the screen at (0, 0).
       The hide option causes the window to be created off-screen.  The scroll
       and noscroll options set the scroll mode.  The cd option sets the work‐
       ing directory.  The optional command and arguments define which program
       to run in the window.

       By default, window uses /dev/wctl (see rio(4)) to create the window and
       run the command.	 Therefore, the window and command will be created  by
       rio  and	 run  in a new file name space, just as if the window had been
       created using the interactive menu.  However, the -m  option  uses  the
       file  server  properties of rio to mount (see bind(1)) the new window's
       name space within the name space of the program calling	window.	  This
       means,  for  example,  that  running window in a CPU window will create
       another window whose command runs on the terminal, where	 rio  is  run‐
       ning;  while window -m will create another window whose command runs on
       the CPU server.

       The wloc command prints the coordinates and label of each window in its
       instance of rio and is used to construct arguments for window.

   Window control
       Each  window  behaves  as a separate terminal with at least one process
       associated with it.  When a window is created, a new process (usually a
       shell;  see  rc(1))  is	established  and  bound to the window as a new
       process group.  Initially, each window acts as a simple	terminal  that
       displays character text; the standard input and output of its processes
       are attached to /dev/cons.  Other special files, accessible to the pro‐
       cesses  running in a window, may be used to make the window a more gen‐
       eral display.  Some of these are mentioned here; the  complete  set  is
       discussed in rio(4).

       One  window  is	current, and is indicated with a dark border and text;
       characters typed on the keyboard are available in the /dev/cons file of
       the  process  in	 the  current window.  Characters written on /dev/cons
       appear asynchronously in the associated window whether or not the  win‐
       dow is current.

       Windows	are created, deleted and rearranged using the mouse.  Clicking
       (pressing and releasing) mouse button 1 in a non-current	 window	 makes
       that  window  current and brings it in front of any windows that happen
       to be overlapping it.  When the mouse cursor points to  the  background
       area  or is in a window that has not claimed the mouse for its own use,
       pressing mouse button 3 activates a menu of window operations  provided
       by  rio.	 Releasing button 3 then selects an operation.	At this point,
       a gunsight or cross cursor indicates that an operation is pending.  The
       button 3 menu operations are:

       New    Create  a	 window.   Press  button 3 where one corner of the new
	      rectangle should appear (cross  cursor),	and  move  the	mouse,
	      while  holding down button 3, to the diagonally opposite corner.
	      Releasing button 3 creates the window,  and  makes  it  current.
	      Very small windows may not be created.

       Resize Change  the size and location of a window.  First click button 3
	      in the window to be changed (gunsight cursor).  Then sweep out a
	      window as for the New operation.	The window is made current.

       Move   Move  a  window to another location.  After pressing and holding
	      button 3 over the window to be moved (gunsight cursor), indicate
	      the  new position by dragging the rectangle to the new location.
	      The window is made current.  Windows may be moved partially off-

       Delete Delete  a	 window.   Click in the window to be deleted (gunsight
	      cursor).	Deleting a window causes a note to be sent to all pro‐
	      cesses in the window's process group (see notify(2)).

       Hide   Hide  a window.  Click in the window to be hidden (gunsight cur‐
	      sor); it will be moved off-screen.  Each hidden window is	 given
	      a	 menu entry in the button 3 menu according to the value of the
	      file /dev/label, which rio maintains (see rio(4)).

       label  Restore a hidden window.

       Windows may also be arranged by dragging their borders.	Pressing  but‐
       ton  1 or 2 over a window's border allows one to move the corresponding
       edge or corner, while button 3 moves the whole window.

   Text windows
       Characters typed on the keyboard or written to /dev/cons collect in the
       window to form a long, continuous document.

       There  is  always some selected text, a contiguous string marked on the
       screen by reversing its color.  If the selected text is a null  string,
       it  is  indicated  by  a	 hairline  cursor between two characters.  The
       selected text may be edited by mousing and typing.  Text is selected by
       pointing	 and  clicking button 1 to make a null-string selection, or by
       pointing, then sweeping with  button  1	pressed.   Text	 may  also  be
       selected	 by double-clicking: just inside a matched delimiter-pair with
       one of {[(<«`'" on the left and }])>»`'" on the right, it  selects  all
       text within the pair; at the beginning or end of a line, it selects the
       line; within or at the edge of an alphanumeric  word,  it  selects  the

       Characters  typed  on  the  keyboard replace the selected text; if this
       text is not empty, it is placed in a snarf buffer common to all windows
       but distinct from that of sam(1).

       Programs	 access	 the  text  in the window at a single point maintained
       automatically by rio.  The output point is the  location	 in  the  text
       where the next character written by a program to /dev/cons will appear;
       afterwards, the output point is the null string beyond the new  charac‐
       ter.   The  output  point  is also the location in the text of the next
       character that will be read (directly from the text in the window,  not
       from  an	 intervening buffer) by a program from /dev/cons.  When such a
       read will occur is, however, under control of rio and the user.

       In general there is text in the window after the output point,  usually
       placed  there  by  typing  but  occasionally  by the editing operations
       described below.	 A pending read of /dev/cons will block until the text
       after  the  output  point  contains  a  newline, whereupon the read may
       acquire the text, up to and including the newline.  After the read,  as
       described  above, the output point will be at the beginning of the next
       line of text.  In normal circumstances, therefore, typed text is deliv‐
       ered  to	 programs a line at a time.  Changes made by typing or editing
       before the text is read will not be seen by the program reading it.  If
       the program in the window does not read the terminal, for example if it
       is a long-running computation, there may accumulate multiple  lines  of
       text after the output point; changes made to all this text will be seen
       when the text is eventually read.  This means, for  example,  that  one
       may  edit  out newlines in unread text to forestall the associated text
       being read when the program finishes computing.	This behavior is  very
       different from most systems.

       Even  when  there  are  newlines in the output text, rio will not honor
       reads if the window is in hold mode, which is indicated by a white cur‐
       sor  and	 blue  text  and border.  The ESC character toggles hold mode.
       Some programs, such as mail(1), automatically turn on hold mode to sim‐
       plify  the editing of multi-line text; type ESC when done to allow mail
       to read the text.

       An EOT character (control-D) behaves exactly like newline  except  that
       it  is  not delivered to a program when read.  Thus on an empty line an
       EOT serves to deliver an end-of-file indication: the read  will	return
       zero characters.	 Like newlines, unread EOTs may be successfully edited
       out of the text.	 The BS character  (control-H)	erases	the  character
       before  the  selected  text.   The ETB character (control-W) erases any
       nonalphanumeric characters, then the alphanumeric word just before  the
       selected	 text.	 `Alphanumeric' here means non-blanks and non-punctua‐
       tion.  The NAK character (control-U) erases the text after  the	output
       point,  and not yet read by a program, but not more than one line.  All
       these characters are typed  on  the  keyboard  and  hence  replace  the
       selected text; for example, typing a BS with a word selected places the
       word in the snarf buffer, removes it from the screen,  and  erases  the
       character before the word.

       An  ACK	character  (control-F)	or Insert character triggers file name
       completion for the preceding string (see complete(2)).

       Typing a left or right arrow moves the cursor  one  character  in  that
       direction.  Typing an SOH character (control-A) moves the cursor to the
       beginning of the current line; an ENQ character	(control-E)  moves  to
       the end.

       Text  may  be  moved vertically within the window.  A scroll bar on the
       left of the window shows in its clear  portion  what  fragment  of  the
       total  output  text is visible on the screen, and in its gray part what
       is above or below view; it measures  characters,	 not  lines.   Mousing
       inside  the  scroll  bar	 moves	text: clicking button 1 with the mouse
       pointing inside the scroll bar brings the line at the top of the window
       to  the cursor's vertical location; button 3 takes the line at the cur‐
       sor to the top of the window; button 2, treating the scroll  bar	 as  a
       ruler,  jumps  to  the indicated portion of the stored text.  Holding a
       button pressed in the scroll bar will cause the text to scroll continu‐
       ously  until  the  button is released.  Also, a page down or down-arrow
       scrolls forward half a window, and page up or  up-arrow	scrolls	 back.
       Typing  the  home  key scrolls to the top of the window; typing the end
       key scrolls to the bottom.

       The DEL character sends an  note	 to  all  processes  in	 the  window's
       process group.  Unlike the other characters, the DEL, VIEW, and up- and
       down-arrow keys do not affect the  selected  text.   The	 left  (right)
       arrow  key moves the selection to one character before (after) the cur‐
       rent selection.

       Normally, written output to a window blocks when the text  reaches  the
       end of the screen; a button 2 menu item toggles scrolling.

       Other editing operations are selected from a menu on button 2.  The cut
       operation deletes the selected text from the screen and puts it in  the
       snarf  buffer;  snarf  copies  the  selected text to the buffer without
       deleting it; paste replaces the selected text with the contents of  the
       buffer;	and  send  copies  the	snarf  buffer to just after the output
       point, adding a final newline if missing.   Paste  will	sometimes  and
       send  will always place text after the output point; the text so placed
       will behave exactly as described above.	Therefore  when	 pasting  text
       containing  newlines  after the output point, it may be prudent to turn
       on hold mode first.

       The plumb menu item sends the contents of the selection (not the	 snarf
       buffer)	to  the	 plumber(4).   If the selection is empty, it sends the
       white-space-delimited text containing the selection (typing cursor).  A
       typical use of this feature is to tell the editor to find the source of
       an error by plumbing the file and  line	information  in	 a  compiler's

   Raw text windows
       Opening	or manipulating certain files served by rio suppresses some of
       the services  supplied  to  ordinary  text  windows.   While  the  file
       /dev/mouse  is  open,  any  mouse  operations are the responsibility of
       another program running in the window.  Thus, rio refrains  from	 main‐
       taining	the  scroll bar, supplying text editing or menus, interpreting
       the VIEW key as a request to scroll, and also turns scrolling on.

       The file /dev/consctl controls interpretation of	 keyboard  input.   In
       particular, a raw mode may be set: in a raw-input window, no typed key‐
       board characters are special, they are not echoed to  the  screen,  and
       all  are passed to a program immediately upon reading, instead of being
       gathered into lines.

   Graphics windows
       A program that holds /dev/mouse and /dev/consctl open after putting the
       console	in  raw mode has complete control of the window: it interprets
       all mouse events, gets all keyboard  characters,	 and  determines  what
       appears on the screen.

	      font directories

	      Files  served  by	 rio  (also unioned in /dev in a window's name
	      space, before the terminal's real /dev files)

	      Server end of rio.

	      Named pipe for wctl messages.





       rio(4),	rc(1),	cpu(1),	 sam(1),   mail(1),   proof(1),	  graphics(2),
       frame(2), window(2), notify(2), cons(3), draw(3), mouse(3), keyboard(6)

       The standard input of window is redirected to the newly created window,
       so there is no way to pipe the output of	 a  program  to	 the  standard
       input  of  the new window.  In some cases, plumb(1) can be used to work
       around this limitation.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net