Some man pages.

6 files changed, 711 insertions, 0 deletions

diff --git a/man/man4/0intro.4 b/man/man4/0intro.4
new file mode 100644
index 00000000..1e4c81d2
--- /dev/null
+++ b/man/man4/0intro.4
@@ -0,0 +1,82 @@
+.TH INTRO 4
+.SH NAME
+intro \- introduction to file servers
+.SH DESCRIPTION
+A Plan 9
+.I "file server"
+provides a file tree to processes.
+This section of the manual describes servers that can be
+mounted in a name space to give a file-like interface to interesting services.
+A file server may be a provider of a conventional file system,
+with files maintained on permanent storage,
+or it may also be a process that synthesizes files in some manner.
+.PP
+In Plan 9, the kernel mount device
+\fImnt\fR(3)
+acts as a client to the 9P servers mounted in the current name space,
+translating system calls such as
+.IR open (2)
+into 9P transactions such as
+.IR open (9p).
+The kernel also multiplexes the potentially many processes onto a single 9P conversation
+with each server.
+Finally, the kernel provides each process with its own private
+.I name space
+which it can customize at will.
+Modern Unix systems do not provide these niceties, so 
+the Unix port of these Plan 9 file servers provides them via other means.
+.PP
+On Unix, 9P clients do not access servers via the traditional
+file system call interface.  Only the Unix name space can be accessed
+that way.
+Instead, 9P clients use the
+.IR 9pclient (3)
+library to connect and interact directly with particular 9P servers.
+The
+.IR 9p (1)
+command-line client is useful for interactive use and in shell scripts.
+.PP
+To preserve the façade of a single 9P conversation with each server,
+9P servers invoke
+.IR 9pserve (4),
+typically via
+.IR post9pservice (3).
+.I 9pserve
+announces a 9P service at a particular
+network address and multiplexes the clients that connect to
+that address onto a single 9P conversation with the server.
+.PP
+Each ported program operates in a pseudo-name space
+that determines which 9P servers it is using.
+The name space of a ported program is represented by a 
+directory containing Unix domain sockets, one for each 9P server.
+The directory defaults to
+.BR /tmp/ns.$USER.$DISPLAY ,
+meaning that all programs in an X Windows login session 
+share a single name space.
+Setting the
+.B $NAMESPACE
+environment variable overrides this default.
+The
+.IR namespace (1)
+command prints the current name space directory.
+.PP
+Occasionally it is useful to be able to connect the input or output
+of a standard Unix program to a file served by a 9P server.
+The new
+.IR openfd (9p)
+9P transaction, which depends on file descriptor passing,
+provides a sufficient workaround in many cases. 
+.IR 9pserve 's
+implementation of
+.I openfd
+(see also
+.I fsopenfd
+in
+.IR 9pclient (3))
+returns the read or write end of a pipe;
+a helper process transfers data between the other end of the pipe
+and the 9P server.
+Note that since the data is being transferred via a pipe,
+9P read and write errors cannot be passed on to the Unix program.
+The Unix program sees only end-of-file or a closed pipe.
diff --git a/man/man4/9pserve.4 b/man/man4/9pserve.4
new file mode 100644
index 00000000..81cfc262
--- /dev/null
+++ b/man/man4/9pserve.4
@@ -0,0 +1,46 @@
+.TH 9PSERVE 4
+.SH NAME
+9pserve \- announce and multiplex 9P service
+.SH SYNOPSIS
+.B 9pserve
+[
+.B -v
+]
+.I addr
+.SH DESCRIPTION
+On Plan 9, when a user-level file server mounts itself into a name space
+or posts itself in 
+.BR /srv ,
+the Plan 9 kernel multiplexes the potentially many processes 
+accessing the server into a single 9P conversation.
+The user-level server need not concern itself with how many
+processes are accessing it or with cleaning up after a process when it
+exits unexpectedly.
+On Unix,
+.I 9pserve
+takes the place of the Plan 9 kernel, multiplexing clients onto
+a single server conversation and cleaning up after clients when
+they hang up unexpectedly.
+.PP
+.I 9pserve
+announces a 9P service on
+.I addr
+and multiplexes any 9P clients connecting to
+.I addr
+into a single conversation with a 9P server on
+.IR 9pserve 's
+standard input and output.
+When a client hangs up, 
+.I 9pserve
+flushes any outstanding 9P transactions 
+and clunks any outstanding fids belonging to the client.
+.PP
+.I 9pserve
+is typically not invoked directly; use
+.IR post9pservice (3)
+instead.
+.SH "SEE ALSO
+.IR intro (4),
+.IR intro (9p)
+.SH SOURCE
+.B /usr/local/plan9/src/cmd/9pserve.c
diff --git a/man/man4/INDEX b/man/man4/INDEX
new file mode 100644
index 00000000..bd0f7bc1
--- /dev/null
+++ b/man/man4/INDEX
@@ -0,0 +1,6 @@
+0intro 0intro.4
+intro 0intro.4
+9pserve 9pserve.4
+acme acme.4
+plumber plumber.4
+ramfs ramfs.4
diff --git a/man/man4/acme.4 b/man/man4/acme.4
new file mode 100644
index 00000000..f6a48538
--- /dev/null
+++ b/man/man4/acme.4
@@ -0,0 +1,406 @@
+.TH ACME 4
+.SH NAME
+acme \- control files for text windows
+.SH SYNOPSIS
+.B acme
+[
+.B -f
+.I varfont
+] [
+.B -F
+.I fixfont
+]
+[
+.I file
+\&... ]
+.SH DESCRIPTION
+The text window system
+.IR 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 operations
+of 
+.I acme
+itself.
+When a command is run under
+.IR acme ,
+a directory holding these files is mounted on
+.B /mnt/acme
+(also bound to
+.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 in Plan 9's
+\fIcons\fR(3).
+(Unlike in Plan 9's \fIrio\fR(1),
+each command under
+.I acme
+sees the same set of files; there is not a distinct
+.B /dev/cons
+for each window.)
+Other files are unique to
+.IR acme .
+.TP
+.B acme
+is a subdirectory used by
+.B win
+(see
+.IR acme (1))
+as a mount point for the
+.I acme
+files associated with the window in which
+.B win
+is running.
+It has no specific function under
+.I acme
+itself.
+.TP
+.B cons
+is the standard and diagnostic output file for all commands
+run under
+.IR acme .
+(Input for commands is redirected to
+.BR /dev/null .)
+Text written to
+.B cons
+appears in a window labeled
+.IB dir /+Errors\f1,
+where
+.I dir
+is the directory in which the command
+was run.
+The window is created if necessary, but not until text is actually written.
+.TP
+.B consctl
+Is an empty unwritable file present only for compatibility; there is no way
+to turn off `echo', for example, under
+.IR acme .
+.TP
+.B 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\(emthe window ID;
+number of characters (runes) in the tag;
+number of characters in the body;
+a 1 if the window is a directory, 0 otherwise;
+and a 1 if the window is modified, 0
+otherwise\(emfollowed by the tag up to a newline if present.
+Thus at character position 5×12 starts the name of the window.
+If a file has multiple zeroxed windows open,
+only the most recently used will appear in the
+.B index
+file.
+.TP
+.B label
+is an empty file, writable without effect, present only for compatibility with
+.BR rio .
+.TP
+.B new
+A directory analogous to the numbered directories
+.RI ( q.v. ).
+Accessing any
+file in
+.B new
+creates a new window.  Thus to cause text to appear in a new window,
+write it to
+.BR /dev/new/body .
+For more control, open
+.BR /dev/new/ctl
+and use the interface described below.
+.LP
+.PP
+Each
+.I acme
+window has associated a directory numbered by its ID.
+Window IDs are chosen sequentially and may be discovered by the
+.B ID
+command, by
+reading the
+.B ctl
+file, or
+indirectly through the
+.B index
+file.  The files in the numbered directories are as follows.
+.TP
+.B 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
+.B data
+file.
+When read, it returns the value of the address that would next be read
+or written through the
+.B data
+file, in the format
+.BI # m ,# n
+where
+.I m
+and
+.I n
+are character (not byte) offsets.  If
+.I m
+and
+.I n
+are identical, the format is just
+.BI # m\f1.
+Thus a regular expression may be evaluated by writing it to
+.B addr
+and reading it back.
+The
+.B addr
+address has no effect on the user's selection of text.
+.TP
+.B body
+holds contents of the window body.  It may be read at any byte offset.
+Text written to
+.B body
+is always appended; the file offset is ignored.
+.TP
+.B ctl
+may be read to recover the five numbers as held in the
+.B index
+file, described above, plus two more fields: the width of the
+window in pixels and the name of the font used in the window.
+Text messages may be written to
+.B ctl
+to affect the window.
+Each message is terminated by a newline and multiple
+messages may be sent in a single write.
+.RS .5i
+.TF limit=addr
+.TP
+.B addr=dot
+Set the
+.B addr
+address to that of the user's selected text in the window.
+.TP
+.B clean
+Mark the window clean as though it has just been written.
+.TP
+.B dirty
+Mark the window dirty, the opposite of clean.
+.TP
+.B cleartag
+Remove all text in the tag after the vertical bar.
+.TP
+.B del
+Equivalent to the
+.B Del
+interactive command.
+.TP
+.B delete
+Equivalent to the
+.B Delete
+interactive command.
+.TP
+.B dot=addr
+Set the user's selected text in the window to the text addressed by the
+.B addr
+address.
+.TP
+.BI dump " command
+Set the command string to recreate the window from a dump file.
+.TP
+.BI dumpdir " directory
+Set the directory in which to run the command to recreate the window from a dump file.
+.TP
+.B get
+Equivalent to the
+.B Get
+interactive command with no arguments; accepts no arguments.
+.TP
+.B limit=addr
+When the
+.B ctl
+file is first opened, regular expression context searches in
+.B addr
+addresses examine the whole file; this message restricts subsequent
+searches to the current
+.B addr
+address.
+.TP
+.B mark
+Cancel
+.BR nomark ,
+returning the window to the usual state wherein each modification to the
+body must be undone individually.
+.TP
+.BI name " name
+Set the name of the window to
+.IR name .
+.TP
+.B nomark
+Turn off automatic `marking' of changes, so a set of related changes
+may be undone in a single
+.B Undo
+interactive command.
+.TP
+.B noscroll
+Turn off automatic `scrolling' of the window to show text written to the body.
+.TP
+.B put
+Equivalent to the
+.B Put
+interactive command with no arguments; accepts no arguments.
+.TP
+.B scroll
+Cancel a
+.B noscroll
+message, returning the window to the default state wherein each write
+to the
+.B body
+file causes the window to `scroll' to display the new text.
+.TP
+.B show
+Guarantee at least some of the selected text is visible on the display.
+.RE
+.PD
+.TP
+.B data
+is used in conjunction with
+.B addr
+for random access to the contents of the body.
+The file offset is ignored when writing the
+.B data
+file; instead the location of the data to be read or written is determined by the state of the
+.B addr
+file.
+Text, which must contain only whole characters (no `partial runes'),
+written to
+.B data
+replaces the characters addressed by the
+.B addr
+file and sets the address to the null string at the end of the written text.
+A read from
+.B data
+returns as many whole characters as the read count will permit starting
+at the beginning of the
+.B addr
+address (the end of the address has no effect)
+and sets the address to the null string at the end of the returned
+characters.
+.TP
+.B event
+When a window's
+.B 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
+.B Cut
+and
+.BR Paste ,
+which behave normally) have no immediate effect on the window;
+it is expected that the program reading the
+.B 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 character 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
+.B E
+for writes to the
+.B body
+or
+.B tag
+file,
+.B F
+for actions through the window's other files,
+.B K
+for the keyboard, and
+.B M
+for the mouse.
+The type characters are
+.B D
+for text deleted from the body,
+.B d
+for text deleted from the tag,
+.B I
+for text inserted to the body,
+.B i
+for text inserted to the tag,
+.B L
+for a button 3 action in the body,
+.B l
+for a button 3 action in the tag,
+.B X
+for a button 2 action in the body, and
+.B x
+for a button 2 action in the tag.
+.IP
+If the relevant text has less than 256 characters, it is included in the message;
+otherwise it is elided, the fourth number is 0, and the program must read
+it from the
+.B data
+file if needed.  No text is sent on a
+.B D
+or
+.B d
+message.
+.IP
+For
+.BR D ,
+.BR d ,
+.BR I ,
+and
+.BR i
+the flag is always zero.
+For
+.BR X
+and
+.BR x ,
+the flag is a bitwise OR (reported decimally) of the following:
+1 if the text indicated is recognized as an
+.I 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 describing 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 follow reporting the argument (with
+all numbers 0 except the character count) and where it originated, in the form of
+a fully-qualified button 3 style address.
+.IP
+For
+.B L
+and
+.BR l ,
+the flag is the bitwise OR of the following:
+1 if
+.I acme
+can interpret the action without loading a new file;
+2 if a second (post-expansion) message follows, analogous to that with
+.B X
+messages;
+4 if the text is a file or window name (perhaps with address) rather than
+plain literal text.
+.IP
+For messages with the 1 bit on in the flag,
+writing the message back to the
+.B event
+file, but with the flag, count, and text omitted,
+will cause the action to be applied to the file exactly as it would
+have been if the
+.B event
+file had not been open.
+.TP
+.B tag
+holds contents of the window tag.  It may be read at any byte offset.
+Text written to
+.B tag
+is always appended; the file offset is ignored.
+.SH SOURCE
+.B /usr/local/plan9/src/cmd/acme
+.SH SEE ALSO
+.IR rio (1),
+.IR acme (1)
diff --git a/man/man4/plumber.4 b/man/man4/plumber.4
new file mode 100644
index 00000000..681bd5e2
--- /dev/null
+++ b/man/man4/plumber.4
@@ -0,0 +1,121 @@
+.TH PLUMBER 4
+.SH NAME
+plumber \- file system for interprocess messaging
+.SH SYNOPSIS
+.B plumber
+[
+.B -p
+.I plumbing
+]
+.SH DESCRIPTION
+The
+.I plumber
+is a user-level file server that receives, examines, rewrites, and dispatches
+.IR plumb (7)
+messages between programs.
+Its behavior is programmed by a
+.I plumbing
+file (default
+.BR /usr/$user/lib/plumbing )
+in the format of
+.IR plumb (7).
+.PP
+Its services are posted via
+.IR 9pserve (4)
+as
+.BR plumb .
+and consist of two
+pre-defined files,
+.B plumb/send
+and
+.BR plumb/rules ,
+and a set of output
+.I ports
+for dispatching messages to applications.
+.PP
+Programs use
+.B fswrite
+(see
+.IR 9pclient (3))
+to deliver messages to the
+.B send
+file, and
+.I fsread
+to receive them from the corresponding port.
+For example,
+.IR sam (1)'s
+.B plumb
+menu item or the
+.B B
+command cause a message to be sent to
+.BR plumb/send ;
+.B sam
+in turn reads from, by convention,
+.B plumb/edit
+to receive messages about files to open.
+.PP
+A copy of each message is sent to each client that has the corresponding port open.
+If none has it open, and the rule has a
+.B plumb
+.B client
+or
+.B plumb
+.B start
+rule, that rule is applied.
+A
+.B plumb
+.B client
+rule causes the specified command to be run
+and the message to be held for delivery when the port is opened.
+A
+.B plumb
+.B start
+rule runs the command but discards the message.
+If neither
+.B start
+or
+.B client
+is specified and the port is not open,
+the message is discarded and a write error is returned to the sender.
+.PP
+The set of output ports is determined dynamically by the
+specification in the plumbing rules file: a port is created for each unique
+destination of a
+.B plumb
+.B to
+rule.
+.PP
+The set of rules currently active may be examined by reading the file
+.BR plumb/rules ;
+appending to this file adds new rules to the set, while
+creating it (opening it with
+.BR OTRUNC )
+clears the rule set.
+Thus the rule set may be edited dynamically with a traditional text editor.
+However, ports are never deleted dynamically; if a new set of rules does not
+include a port that was defined in earlier rules, that port will still exist (although
+no new messages will be delivered there).
+.SH FILES
+.TF /usr/$user/lib/plumbing
+.TP
+.B /usr/$user/lib/plumbing
+default rules file
+.TP
+.B /usr/local/plan9/plumb
+directory to search for files in
+.B include
+statements
+.TP
+.B plumb
+mount name for
+.IR plumber (4).
+.SH SOURCE
+.B /usr/local/plan9/src/cmd/plumb
+.SH "SEE ALSO"
+.IR plumb (1),
+.IR plumb (3),
+.IR plumb (7)
+.\" .SH BUGS
+.\" .IR Plumber 's
+.\" file name space is fixed, so it is difficult to plumb
+.\" messages that involve files in newly mounted services.
diff --git a/man/man4/ramfs.4 b/man/man4/ramfs.4
new file mode 100644
index 00000000..32405de1
--- /dev/null
+++ b/man/man4/ramfs.4
@@ -0,0 +1,50 @@
+.TH RAMFS 4
+.SH NAME
+ramfs  \- memory file system
+.SH SYNOPSIS
+.B ramfs
+[
+.B -i
+]
+[
+.B -S
+.I service
+]
+.SH DESCRIPTION
+.I Ramfs
+starts a 9P file server 
+keeping all files in memory.
+Initially the file tree is empty.
+.PP
+By default
+.I ramfs
+posts its service as
+.B ramfs
+using
+.IR 9pserve (4).
+.PP
+The
+.B -S
+flag specifies an alternate service name for ramfs to use.
+.PP
+The
+.B -i
+flag tells
+.I ramfs
+to use file descriptors 0 and 1 for its communication channel
+rather than create a pipe.
+This makes it possible to use
+.I ramfs
+as a file server on a remote machine: the file descriptors 0
+and 1 will be the network channel from
+.I ramfs
+to the client machine.
+.PP
+This program is useful mainly as an example of how
+to write a user-level file server.
+It can also be used to provide high-performance temporary files.
+.SH SOURCE
+.B /usr/local/plan9/src/cmd/ramfs.c
+.SH "SEE ALSO"
+.IR 9p (3),
+.IR 9pserve (4)