Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ACME(4)			   Kernel Interfaces Manual		       ACME(4)

       acme - control files for	text windows

       acme [ -f varfont ] [ -F	fixfont	] [ file ... ]

       The  text  window system	acme(1)	serves a variety of files for reading,
       writing,	and controlling	windows.  Some of them are virtual versions of
       system files for	dealing	with the virtual console; others control oper-
       ations of acme itself.  When a command is run under acme,  a  directory
       holding	 these	 files	is  posted  as	the  9P	 service  acme	(using

       Some of these files supply virtual versions of services available  from
       the  underlying environment, in particular the character	terminal files
       in Plan 9's cons(3).  (Unlike in	Plan 9's rio(1),  each	command	 under
       acme  sees the same set of files; there is not a	distinct /dev/cons for
       each window.)  Other files are unique to	acme.

       acme   is a subdirectory	used by	win (see acme(1)) as a mount point for
	      the  acme	 files associated with the window in which win is run-
	      ning.  It	has no specific	function under acme itself.

       cons   is the standard and diagnostic output file for all commands  run
	      under  acme.   (Input  for commands is redirected	to /dev/null.)
	      Text written to cons appears in a	 window	 labeled  dir/+Errors,
	      where  dir  is  the directory in which the command was run.  The
	      window is	created	if necessary, but not until text  is  actually

	      is  an  empty  unwritable	 file  present only for	compatibility;
	      there is no way to turn off `echo', for example, under acme.

       index  holds a sequence of lines	of text, one per  window.   Each  line
	      has  5  decimal  numbers,	each formatted in 11 characters	plus a
	      blank--the window	ID; number of characters (runes) in  the  tag;
	      number  of characters in the body; a 1 if	the window is a	direc-
	      tory, 0 otherwise; and a 1 if the	window is modified,  0	other-
	      wise--followed  by  the tag up to	a newline if present.  Thus at
	      character	position 5A12 starts the name of  the  window.	 If  a
	      file  has	 multiple zeroxed windows open,	only the most recently
	      used will	appear in the index file.

       label  is an empty file,	writable without effect, present only for com-
	      patibility with rio.

       log    reports  a log of	window operations since	the opening of the log
	      file.  Each line describes a single operation using three	fields
	      separated	 by  single  spaces: the decimal window	ID, the	opera-
	      tion, and	the window name.  Reading from log blocks until	 there
	      is  an  operation	 to report, so reading the file	can be used to
	      monitor editor activity and  react  to  changes.	 The  reported
	      operations  are  (window creation), (window creation via zerox),
	      and (window deletion).  The window name can be the empty string;
	      in  particular  it is empty in log entries corresponding to win-
	      dows created by external programs.

       new    is a directory analogous to  the	numbered  directories  (q.v.).
	      Accessing	 any  file in new creates a new	window.	 Thus to cause
	      text to appear in	a new window, write it to /dev/new/body.   For
	      more  control, open /dev/new/ctl and use the interface described

       Each acme window	has associated a directory numbered by its ID.	Window
       IDs are chosen sequentially and may be discovered by the	ID command, by
       reading the ctl file, or	indirectly through the index file.  The	 files
       in the numbered directories are as follows.

       addr   may  be  written	with any textual address (line number, regular
	      expression, etc.), in the	format	understood  by	button	3  but
	      without  the initial colon, including compound addresses,	to set
	      the address for text accessed through the	data file.  When read,
	      it  returns  the value of	the address that would next be read or
	      written through the data file, in	the format #m,#n where m and n
	      are character (not byte) offsets.	 If m and n are	identical, the
	      format is	just #m.  Thus a regular expression may	 be  evaluated
	      by writing it to addr and	reading	it back.  The addr address has
	      no effect	on the user's selection	of text.

       body   holds contents of	the window body.  It may be read at  any  byte
	      offset.	Text written to	body is	always appended; the file off-
	      set is ignored.

       ctl    may be read to recover the five numbers as  held	in  the	 index
	      file,  described above, plus three more fields: the width	of the
	      window in	pixels,	the name of the	font used in the  window,  and
	      the  width  of  a	tab character in pixels.  Text messages	may be
	      written to ctl to	affect the window.  Each message is terminated
	      by  a  newline  and  multiple  messages  may be sent in a	single

		   Set the addr	address	to that	of the user's selected text in
		   the window.

	    clean  Mark	the window clean as though it has just been written.

	    dirty  Mark	the window dirty, the opposite of clean.

		   Remove all text in the tag after the	vertical bar.

	    del	   Equivalent to the Del interactive command.

	    delete Equivalent to the Delete interactive	command.

		   Set	the  user's  selected  text  in	the window to the text
		   addressed by	the addr address.

	    dump command
		   Set the command string to recreate the window from  a  dump

	    dumpdir directory
		   Set	the  directory in which	to run the command to recreate
		   the window from a dump file.

	    get	   Equivalent to the Get interactive  command  with  no	 argu-
		   ments; accepts no arguments.

		   When	 the ctl file is first opened, regular expression con-
		   text	searches in addr addresses  examine  the  whole	 file;
		   this	 message  restricts subsequent searches	to the current
		   addr	address.

	    mark   Cancel nomark, returning the	 window	 to  the  usual	 state
		   wherein  each modification to the body must be undone indi-

	    name name
		   Set the name	of the window to name.

	    nomark Turn	off automatic  `marking'  of  changes,	so  a  set  of
		   related  changes may	be undone in a single Undo interactive

	    put	   Equivalent to the Put interactive  command  with  no	 argu-
		   ments; accepts no arguments.

	    show   Guarantee  at least some of the selected text is visible on
		   the display.

       data   is used in conjunction with addr for random access to  the  con-
	      tents  of	the body.  The file offset is ignored when writing the
	      data file; instead the location of the data to be	read or	 writ-
	      ten  is  determined  by the state	of the addr file.  Text, which
	      must contain only	whole characters (no `partial runes'), written
	      to  data	replaces the characters	addressed by the addr file and
	      sets the address to the null string at the end  of  the  written
	      text.   A	read from data returns as many whole characters	as the
	      read count will permit starting at the  beginning	 of  the  addr
	      address  (the  end  of  the  address has no effect) and sets the
	      address to the null string at the	end of	the  returned  charac-

       errors Writing	to  the	 errors	 file  appends	to  the	 body  of  the
	      dir/+Errors window, where	dir is the directory  currently	 named
	      in  the  tag.  The window	is created if necessary, but not until
	      text is actually written.

       event  When a window's event file is open, changes to the window	 occur
	      as  always  but the actions are also reported as messages	to the
	      reader of	the file.  Also, user actions with  buttons  2	and  3
	      (other  than  chorded Cut	and Paste, which behave	normally) have
	      no immediate effect on the window; it is expected	that the  pro-
	      gram  reading  the event file will interpret them.  The messages
	      have a fixed format: a character indicating the origin or	 cause
	      of  the  action,	a character indicating the type	of the action,
	      four  free-format	 blank-terminated  decimal  numbers,  optional
	      text, and	a newline.  The	first and second numbers are the char-
	      acter addresses of the action, the third	is  a  flag,  and  the
	      final  is	 a count of the	characters in the optional text, which
	      may itself contain newlines.  The	origin characters  are	E  for
	      writes  to  the body or tag file,	F for actions through the win-
	      dow's other files, K for the keyboard, and M for the mouse.  The
	      type characters are D for	text deleted from the body, d for text
	      deleted from the tag, I for text inserted	to  the	 body,	i  for
	      text inserted to the tag,	L for a	button 3 action	in the body, l
	      for a button 3 action in the tag,	X for a	button 2 action	in the
	      body, and	x for a	button 2 action	in the tag.

	      If  the  relevant	 text  has  less  than	256  characters, it is
	      included in the message; otherwise it is elided, the fourth num-
	      ber  is  0,  and	the program must read it from the data file if
	      needed.  No text is sent on a D or d message.

	      For D, d,	I, and i the flag is always zero.  For X  and  x,  the
	      flag is a	bitwise	OR (reported decimally)	of the following: 1 if
	      the text indicated is recognized as an acme built-in command;  2
	      if  the  text  indicated	is  a  null string that	has a non-null
	      expansion; if so,	another	complete message will follow  describ-
	      ing the expansion	exactly	as if it had been indicated explicitly
	      (its flag	will always be 0); 8  if  the  command	has  an	 extra
	      (chorded)	 argument; if so, two more complete messages will fol-
	      low reporting the	argument (with all numbers 0 except the	 char-
	      acter  count)  and  where	it originated, in the form of a	fully-
	      qualified	button 3 style address.

	      For L and	l, the flag is the bitwise OR of the following:	 1  if
	      acme can interpret the action without loading a new file;	2 if a
	      second (post-expansion) message follows, analogous to that  with
	      X	messages; 4 if the text	is a file or window name (perhaps with
	      address) rather than plain literal text.

	      For messages with	the 1 bit on in	the flag, writing the  message
	      back to the event	file, but with the flag, count,	and text omit-
	      ted, will	cause the action to be applied to the file exactly  as
	      it would have been if the	event file had not been	open.

       tag    holds  contents  of  the window tag.  It may be read at any byte
	      offset.  Text written to tag is always appended; the file	offset
	      is ignored.

       xdata  The  xdata  file	like  data  except  that reads stop at the end


       rio(1), acme(1)



Want to link to this manual page? Use this URL:

home | help