~pixelherodev/ANTS

820ddee32aa71625823def5797dc43a90cda07bc — Noam Preil 1 year, 12 days ago a345b9e
add missing docs
4 files changed, 671 insertions(+), 0 deletions(-)

A sys/man/1/chat
A sys/man/1/grio
A sys/man/1/hubfs
A sys/man/1/rerootwin
A sys/man/1/chat => sys/man/1/chat +77 -0
@@ 0,0 1,77 @@
.TH CHAT 1
.SH NAME
chat \- simple chat client for hubfs
.SH SYNOPSIS
.B chat
[
.RB -n
.IR nick
]
[
.RB -j
.IR channel
]
[
.I chatsrv
]
.PP
.SH DESCRIPTION
.I chat
is a simple client script for using
.IR hubfs (4)
as an irc-like chat service.
.B /srv/chat
is the default target service file, which must have been created by a previously started hubfs.
.PP
The
.I -n nick
option sets user nickname, otherwise they will be prompted for one on connection. The
.I -j channel
option chooses a channel to connect to, otherwise the default
.B /n/chat/chat
channel will be targeted. The optional
.I chatsrv
parameter specifies a different file in
.B /srv
rather than the default
/B /srv/chat
.PP
.SH OPERATION 
If invoked with no options the script will mount the hubfs at
.B /n/chat
and prompt for a user nickname, then begin reading and writing messages to
.B /n/chat/chat
in the manner of an irc session. The following commands are available during use:
.I /n nick
change user nickname.
.I /j channel
change the target of the chat to the specified channel.
.I /c
list the available channels within the server.
.I /h
print the help message and command list.
.I /q
quit the chat.
.SH EXAMPLES
Connect to a chat service and begin chatting:
.IP
.EX
srv tcp!chat.9gridchan.org!9997 chat
chat
.EE
.PP
Start a new hubfs providing chat service and allow remote users to connect
.IP
.EX
hubfs -s chat
mount -c /srv/chat /n/chat
touch /n/chat/chat
chmod 666 /srv/chat
aux/listen1 tcp!*!9997 /bin/exportfs -S /srv/chat &
.EE
.SH SOURCE
.B /sys/src/ants/hubfs/chat
.SH SEE ALSO
.IR hubfs (4)
.SH BUGS
All chat logic is handled client side, so there is little protection from abuse.

A sys/man/1/grio => sys/man/1/grio +157 -0
@@ 0,0 1,157 @@
.TH GRIO 1
.SH NAME
grio \- customizable rio
.SH SYNOPSIS
.B grio
[
.B -x
.BI ' menu_cmd '
]
[
.B -a
.BI ' cmd_argument '
]
[
.B -e
]
[
.B -c
.I background color
]
[
.B -t
.I text color
]
[
.B -u
.I window color
]
[
.B -y
.I active bordercolor
]
[
.B -z
.I bkground bordercolor
]
[
.B -l
.I scrollbar color
]
[
.B -B
.I bkground image
]
[
.B -w
.I border width
]
.SH DESCRIPTION
Rio with hubfs integration, command menu customization, selectable colors.
.I Grio
is a modified version of 
.IR rio (1)
All rio options are supported. Integration with
.IR hubfs (4)
and a user-selectable command is provided via the right mouse button menu. This manpage describes only the new features.
.SS Menu Options
.I Grio
provides an 'exit' command in the right button menu, because it is often run nested. The
.B -e
option removes the 'exit' command from the menu. A user-selected command (or
.B /bin/acme
by default) is added to the menu via the
.B -x
option. The command must include the full path, for instance
.B /bin/stats
rather than simply 'stats'. A single argument containing no spaces may be passed with the
.B -a
argument option. If the argument is a set of flags, the - needs to be included. For instance,
.B -lems
as an argument to stats. The argument may not contain any spaces, and quoting does not enable the use of multi-part arguments. 
.SS Color Selection
Most of the colors used by 
.I grio
are now user-selectable via 8 digit hex codes. See 
.IR colors (1)
to inspect sample colors and their codes.
.B -c
.I colorcode
sets the background color.
.B -t
.I textcolor
sets the color of text in windows.
.B -u
.I windowcolor
sets the color the windows themselves.
.B -y
.I bordercolor
sets the color of the border of the currently active window, and
.B -z
.I bordercolor
sets the color of the border of the unselected windows. The width of borders is set with an integer parameter to
.B -w
.I borderpixels
with 2 as the minimum for visible window borders. If no theming parameters are provided, the appearance defaults to standard.
.SS Background Image
.B -B
.I backimg
sets an image for use as the background. The image must be in Plan 9 Image format. You can use the tools such as
.IR jpg(1)
or
.IR png(1)
with the
.B -c
option to convert other images to Plan 9 format. The image will be tiled to fill the available background space.
.SS Hubfs integration
Another menu option,
.B Hub
is present in the right mouse button menu. This provides integration with
.IR Hubfs (4)
such that after this command is selected, the window swept out will automatically be connected to the hubfs mounted at
.B /n/hubfs.
On startup, if there is not already a mounted hubfs at /n/hubfs, 
.I grio
will launch a new instance of 
.I hubfs
with the srv file posted at 
.B /srv/riohubfs.username.
It is often useful to import the /srv of a remote machine and mount a hubfs from it to /n/hubfs prior to starting 
.I grio
.
.SH EXAMPLES
Start with no exit command in the menu, and the ability to create a subgrio with its windows set to scroll mode. (Windows of hosting grio will not be in scroll mode because the -s option is "consumed" by the -a argument.)
.IP
.EX
grio -e -x /bin/grio -a -s
.EE
.PP
Start with a tasteful light purple theme and thin black borders
.IP
.EX
grio -c 0xffaaffff -y 0 -w 2
.EE
.PP
Import and mount a hubfs already running on a remote machine for easy use from the menu
.IP
.EX
rimport kremvax /srv
mount -c /srv/kremhub /n/hubfs
grio
.EE
.PP
Start with a theme of bold and breathtaking beauty
.IP
.EX
grio -c 0xff0000ff -u 0x00ccff -y 0x00ff00ff -t 0xffff00ff -z 0xffaa00ff
.EE
.EX
-w 10 -x /bin/games/catclock -f /lib/font/bit/times/latin1.bold.10.font
.EE
.PP
.SH SOURCE
.B /sys/src/ants/frontmods/grio
.SH BUGS
It would be nice if the
.B -a
argument option could parse and separate multipart arguments.

A sys/man/1/hubfs => sys/man/1/hubfs +321 -0
@@ 0,0 1,321 @@
.TH HUBFS 4
.SH NAME
hub, hubfs, hubshell  \- persistent multiplexed i/o and shells
.SH SYNOPSIS
.B hub
[
.B -b
]
[
.B -t
]
[
.BI srvname
]
[
.BI hubgroup
]
.PP
.B hubshell
.BI attachstring
.PP
.B hubfs
[
.B -Dt
]
[
.B -q
.BI bytequantity
]
[
.B -l
.BI maxmsglen
]
[
.B -b
.BI bytespersecond
]
[
.B -i
.BI mininterval
]
[
.B -r
.BI resettime
]
[
.B -a
.BI address
]
[
.B -m
.BI mountpoint
]
[
.B -s
.BI srvname
]
.PP
.SH DESCRIPTION
.I Hubfs
is a 9p server which creates buffered multiplexing pipelike files with
several applications.  One use is a plan9 equivalent of programs such
as screen/tmux for detachable persistent shells.  Another is as the
server-side of an irc-like application.  Another is as the "broadcast
station" for streaming audio.  It can be thought of as a lightweight
"pub-sub" service with a filesystem interface.
.I Hub
invokes 
.I hubfs
to create a 9p filesystem of pipe-like Hubs available as a /srv and starts an 
.IR rc (1)
shell with its file descriptors redirected to these hubs, then uses 
.I hubshell
as a client for these connections. The overall usage model is somewhat similar to screen/tmux
but without the additional complexities of TTY management.
.PP
The base behavior of 
.I hub
.I srvname
is bimodal, and will function as either a client or server depending on whether 
.I /srv/srvname
exists. If no name is provided, 
.IR hub
will create or attach to a 
.I /srv
named 
.I /srv/hubfs
containing a persistent 
.IR rc (1)
session. Thus, the simplest possible model of use is:
.IP
.EX
hub
.EE
.PP
to start a 
.IR hubfs 
hosted persistent 
.IR rc (1)
shell. Another invocation of 
.IP
.EX
hub
.EE
.PP
from any window with access to that 
.I /srv
will connect to it. The
.B -b
flag to 
.IR hub
backgrounds the initially created 
.IR rc (1)
instead of attaching to it. The
.B -t
flag starts the hubfs in trunc mode, which means clients will not be sent the previously buffered data upon connection.
.PP
.IR Hubfs 
can be used to provide general purpose pipes locally or across a network, with some special features. Most notably, echoing
.I freeze
to the
.B ctl
file will change the behavior of the hub files from pipe-like with blocking reads to simple static files that can be viewed and edited with normal tools. Writing
.I melt
to
.B ctl
will restore pipe-like behavior and resume the normal flow of data.
.PP
While connected via a
.IR hubshell
input beginning with a %symbol will be checked for matching command strings. These commands are used to create new subshells within the
.IR hubfs
session and move between them. A distinctive feature is the ability for remote clients to share a local shell with other clients of the hubfs. The
.B %local NAME
command does this. The more traditional mode of starting new shells on the remote host is done with the
.B %remote NAME
command. Note that 'remote' is the machine hosting the shell you are connected to currently, and the active hubs must be running a shell, not another application.
.B %detach
terminates the 
.IR hubshell
and returns control to the user's original shell.
.SS Hubfs options
The only mandatory option is a parameter to specify a srvname or mountpoint. The following parameters are not generally relevant or used for screen/tmux style usage, but are useful if 
.I hubfs
is being used for irc-like chat service or audio streaming. The default size of a hubfile buffer is 777777 bytes, chosen to approximately match the scrollback buffer of a rio window. The 
.B -q
.BI bytequantity
parameter sets this to a different size. For applications such as audio streaming, a buffer of several megabytes is probably preferable. The default maximum size of a single write is 666666 bytes. The 
.B -l
.BI maxmsglen
parameter selects a different maximum message input size. By default, no rate-limiting of writes is applied, but can be activated by supplying any or all of the -b -i or -r parameters. 
.B -b
.BI bytespersec 
sets the maximum number of bytes per second that can be written, 
.B -i 
.BI mininterval
sets the minimum interval in nanoseconds between writes to the fs. There are 1000000000 (one billion) nanoseconds per second. The 
.B -r 
.BI resettime
parameter sets an interval in seconds after which the ratelimiting resets the timers.
.B -D
is for chatty9p debugging output, and the 
.B -t
flag mentioned above means clients do not receive the previously buffered data when they connect.
.PP
.SH EXAMPLES
.Starting and connecting with the 
.IR hub
wrapper script:
.PP
start and connect to a new hubfs and post /srv/aug5
.IP
.EX
hub aug5
.EE
.PP
connects a new client to the rc shell started by the previous command
.PP
.IP
.EX
hub aug5
.EE
.PP
start and connects to new rc named rctwo within the aug5 hubfs
.PP
.IP
.EX
hub aug5 rctwo
.EE
.PP
Making new shells and moving in hubshell:
.PP
-all commands begin with '%' as first character-
.PP
.IP
.EX
%detach  # disconnect from attached shell
.EE
.PP
.IP
.EX
%remote NAME # start shell on remote machine
.EE
.PP
.IP
.EX
%local NAME # start shell on local machine shared to hubfs
.EE
.PP
.IP
.EX
%attach NAME # move to an existing hubfs shell
.EE
.PP
.IP
.EX
%err TIME, %in TIME, %out TIME # time in ms for delay loop
.EE
.PP
.IP
.EX
%status # basic hubfs connection info
.EE
.PP
.IP
.EX
%list # lc of connected hubfs hubs
.EE
.PP
.IP
.EX
%fear # paranoid mode, %calm to return to normal operation
.EE
.PP
.IP
.EX
%trunc # don't send buffered data, %notrunc reactivates
.EE
.PP
.IP
.EX
%echoes # turn on echo flush, %unecho to turn off
.EE
.PP
.IP
.EX
%fortun # turn on fortune flush, %unfort to deactivate
.EE
.PP
.IP
.PP
Controlling 
.IR hubfs 
via the ctl file (reading from ctl file returns status):
.PP
.IP
.EX
echo eof >/n/hubfs/ctl # send eof to all readers on all hubs
.EE
.PP
.IP
.EX
echo eof NAME >/n/hubfs/ctl # send eof to the named hub
.EE
.PP
.IP
.EX
echo freeze >/n/hubfs/ctl # freeze Hubs as static files
.EE
.PP
.IP
.EX
echo melt >/n/hubfs/ctl # resume normal flow of data
.EE
.PP
.IP
.EX
echo fear >/n/hubfs/ctl # paranoid, writers wait for readers
.EE
.PP
.IP
.EX
echo calm >/n/hubfs/ctl # resume non-paranoid mode
.EE
.PP
.IP
.EX
echo trunc >/n/hubfs/ctl # don't send buffered data
.EE
.PP
.IP
.EX
echo notrunc >/n/hubfs/ctl # send buffer to new clients
.EE
.PP
.IP
.EX
echo quit >/n/hubfs/ctl # kill the fs
.EE
.PP
.SH SOURCE
.B https://bitbucket.org/mycroftiv/hubfs
.SH "SEE ALSO"
UNIX pipes,
.IR pipe (3)
,
.IR srv (3)
and
.IR aux/consolefs (4)
.SH BUGS
Hubs must be given alphabetic names within the ascii subset of unicode.
.PP
In the standard mode of use for interactive rc shells, the synchronization between stdout and stderr is not maintained. The symptom is prompts appearing in seemingly the wrong place. To fix this, enter a command like %err 300 to set 300 milliseconds of delay before data from stderr is printed.
.PP
Because hubfs maintains static buffers and always allows clients to write to avoid loss of interactivity, slow readers may experience data loss while reading output larger than the size of the static buffer if the output was also transmitted fast enough to "wrap around" the location of the reader in the data buffer. The purpose of "paranoid" mode is to restrict the speed of writers if this is a concern. Another option is to make use of the rate-limiting options to throttle the speed of writes.
.PP
"Doug had for years and years, and he talked to us continually about it, a notion of interconnecting computers in grids, and arrays, very complex, and there were always problems in his proposals. That what you would type would be linear and what he wanted was three-dimensional, n-dimensional...I mean he wanted just topological connection of programs and to build programs with loops and and horrid things. He had such grandiose ideas and we were saying, the complexity you're generating just can't be fathomed. You don't sit down and you don't type these kind of connections together. And he persisted with the grandiose ideas where you get into Kirchoff's law problems...what happens if you have a feedback loop and every program doubles the number of characters, it reads one and writes two? It's got to go somewhere - synchronization - there's just no way to implement his ideas and we kept trying to pare him down and weed him down and get something useful and distill it. What was needed, was real ideas...and there were constant discussions all through this period, and it hit just one night, it just hit, and they went in instantly."
.PP
.I ~Ken Thompson on UNIX pipes' origins
.PP
.B http://www.princeton.edu/~hos/mike/transcripts/thompson.htm

A sys/man/1/rerootwin => sys/man/1/rerootwin +116 -0
@@ 0,0 1,116 @@
.TH REROOTWIN 1
.SH NAME
rerootwin, savedevs, getdevs \- change root and keep devices
.SH SYNOPSIS
.B rerootwin
[
.I -f -u -n -t nsfile
]
.I newroot
[
authagent
]
.PP
.B savedevs
[
.I srvname
]
.PP
.B getdevs
[
.I srvname
]
.PP
.B /lib/namespace.saveterm
.SH DESCRIPTION
.I rerootwin
creates a new namespace using
.IR newns (8)
but retains connection to the current interactive window
by using
.IR srvfs (4)
to save the devices from 
.I /mnt/term 
and 
.I /mnt/wsys 
and
remount them inside the new namespace.
.PP
.I newroot
is expected to exist as 
.I /srv/newroot
or be a dialable IP or system name serving 9p on port 564 suitable for a root filesystem. The script attempts to check the current namespace and issue any preparatory binds necessary to make the devices available to 
.I /srv. 
.PP
The file
.I /lib/namespace.saveterm
or
.I /boot/namespace.saveterm
must be available, unless the 
.I -t nsfile
option is given, in which case that file must be a correctly constructed namespace file. By default the 
.I /net.alt 
directory is used as a
pivot point for the remount of the user's devices. The
.B -n
and 
.B -u
flags change this pivot point to 
.I /n 
or 
.I /u 
respectively. (
.I /u 
will only exist on systems running the Bell Labs rootless kernel.) The
.B -f
option changes the namespace file used to
.I /lib/namespace.save9front
or the analog in 
.I boot.
This alternative file follows the 9front namespace conventions and should be used when stepping into a 9front namespace.
.I authagent
is set to "factotum" by default. Another value can be chosen if the user is running a personal factotum in 
.I /srv 
under a different name
.PP
.I getdevs
and
.I savedevs
make use of the same device-saving
.IR srvfs (4)
but do not enter an entirely new namespace. 
.IR savedevs 
saves the current
console and window system devices under a given
.I srvname
or under a pid identity if no name is provided. 
.IR getdevs
.I srvname
issues mount and 
.IR bind (1)
commands to reattach to the saved devices.
.SH EXAMPLES
To enter a fossil-root namespace from within a rootless service namespace:
.IP
.EX
cpu -h tcp!fileserver!17060 -u bootes
rerootwin boot
grio
.EE
.PP
To let a shell within 
.IR hubfs (4)
correctly track window size and run gui programs:
.IP
.EX
savedevs prehub
hub hubfs oldshell
getdevs prehub
.EE
.SH SOURCE
.B /sys/src/ants/scripts/rerootwin
.SH SEE ALSO
.IR bind (1),
.IR srvfs (4)
.SH BUGS
It is not always possible to analyze the originating namespace in detail to determine how the current devices are attached.