inferno-os/doc/changes.ms

.\"<-xtx-*> tbl changes.ms | troff -ms | lp -d stdout
.FP palatino
.ps 9
.nr PS 9
.vs 11
.nr VS 11
.nr dP 1
.nr dV 1p
.nr dT 4m
.nr XT 4
.TL
System and Interface Changes to Inferno
.AU
C H Forsyth
.br
Vita Nuova
.br
forsyth@vitanuova.com
.br
9 June 2003
.SH
Overview
.LP
This paper describes some of the changes made to Inferno
interfaces as they stood in the published Third Edition manuals,
to form the current Fourth Edition of the system,
and the broad effects on internal and external interfaces.
Changes include: extensions to the Limbo language;
new instructions in Dis and the virtual machine; extra content
in Dis object files; structure of the source tree; configuration of
.CW emu ;
replacement of the window system with changes to the client interface;
commands renamed, replaced, and removed;
revised support for network booting;
9P2000 becomes the basis for Styx;
a graphics model offering alpha-blended compositing and general pixel structure;
and improvements to Tk.
.NH 1
Limbo
.LP
Exceptions and fixed point have been added to the Limbo language.
They are described in more detail in separate notes by John Firth,
shortly to be available on the Vita Nuova web site
.CW www.vitanuova.com .
Channels can now be buffered.
A form of polymorphism is now available in Limbo.
.NH 2
Exceptions
.LP
Discussion of exceptions will be restricted here to implications for existing source code.
The most obvious changes are that
.CW Sys->rescue ,
.CW Sys->rescued ,
.CW Sys->unrescue
and
.CW Sys->raise
have vanished.
Instead the exception handling is expressed using constructions in the Limbo language.
Named exceptions can be declared and used (these are described in the note by Firth), and
they are declared as part of the type of functions that raise them.
There is also a general `failure' exception that effectively subsumes the old
.CW Sys->rescue
scheme, including run-time errors such as `out of memory' that can happen in almost any function.
Unlike named exceptions a `failure' exception can be raised or caught by any function,
and its value is a string.
The
.CW raise
statement raises an exception.
This is most obvious in commands that wish to produce an `exit status'.
Instead of
.P1
sys->raise("fail:usage");
.P2
one must now write
.P1
raise "fail:usage";
.P2
(That is one of the more common source changes required to Third Edition Limbo commands,
since that was the most common use of exceptions before.)
A block can have an
.CW exception
handler:
.P1
{
	a := array[128] of byte;
	dosomething(a);
} exception e {
"out of memory:*" =>
	sys->print("i need more space: %s\en", e);
"fail:*" =>
	sys->print("exit status: %s\en", e);
"*" =>
	sys->print("unexpected error: %s\en", e);
	raise;	# propagate it
}
.P2
If an exception is raised during the execution of the block (including functions it calls),
execution of the block is abandoned, and control transfers to the appropriate exception handler
(which is outside the block).
Because the compiler and run-time system know the scope of the exception,
values such as
.CW a
above are correctly reclaimed on exit from the faulty block.
Unhandled failures are propagated to callers; unhandled named exceptions (currently) become failures.
.LP
A process group can cause unhandled exceptions in any process in the group either to
propagate to all members of the group, or to be propagated to the process group leader
after destroying the other processes in the group.
This makes it easier to program recovery from exceptions within a group of concurrent processes.
For instance, if a process is expected to send to another on a channel, but fails unexpectedly instead
(eg, because memory was exhausted),
instead of leaving the intended recipient blocked on a receive operation, it can be sent
an exception to notify it of the failure of the other process, allowing it to take appropriate recovery action.
(This could sometimes be programmed using the
.CW wait
file of
.I prog (3),
but not always.)
.LP
Exception handling is intended for recovering from disaster.
We still think it is better Limbo style
to use tuples, channels and processes to make ordinary error handling explicit.
The few attempts to use failure exceptions to achieve `pretty' but peculiar control flow have had exactly the usual
effect of making the code hard to follow and error-prone.
.NH 2
Channels
.LP
Buffered channels have been added:
.P1
c := chan [N] of int;
.P2
where
.I N
is an integer value,
creates a channel that will allow up to
.I N
integer values to be sent to it without an intervening receive without blocking the sender.
If
.I N
is zero, the channel is unbuffered, equivalent to plain
.CW "chan of int" ,
and synchronises sender and receiver as before.
.LP
The restriction that a given channel value could not be sent to or received from in two
.CW alt
statements simultaneously has been removed.
.NH 2
Polymorphism
.LP
John Firth has implemented a form of parametric polymorphism in Limbo.
It too will be described in a separate note.
Currently we are still fussing over aspects of the constraint syntax
and some other implications of the most general form, and since some aspects are
therefore subject to change, including syntax, we have not yet published the details.
We think it is possible to use the following subset without having to change the code later:
.IP 1.
Function declarations can be parametrised by one or more type variables:
For example:
.RS
.P1
reverse[T](l: list of T): list of T
{
	rl: list of T;
	for(; l != nil; l = tl l)
		rl = hd l :: rl;
	return rl;
}
.P2
Such a function can then be invoked on any compatible set of values.
The function invocation does not specify the type (the compiler does type unification on the parameters).
Thus the above can be used as:
.P1
l1: list of string;
l2: list of ref Item;
l3: list of list of string;
l1 = reverse(l1);
l2 = reverse(l2);
l3 = reverse(l3);
.P2
.RE
.IP 2.
ADTs can also be parametrised:
.P1
Tree: adt[T] {
	v: T;
	l, r: cyclic ref Tree[T];
};
.P2
allowing declaration of
.CW "Tree[ref Item]"
and
.CW "Tree[string]"
for instance.
.IP 3.
Values of the parametrised type can only be declared, assigned, passed as parameters, returned,
or sent down channels.
The only types that can be used as actual parameter types are reference types (ie,
.CW ref " ADT,"
.CW array ,
.CW chan ,
.CW list
and
.CW module ),
and
.CW string
(which is a value type but is implemented using a reference).
At some point we shall allow a function such as
.CW reverse
above to be invoked with any compatible type (not just reference types) but
that requires changes to Dis and the virtual machine not yet made.
.LP
The formal type parameters can be further constrained by listing a set
of operations that they must have (which currently implies the actual parameters
must be ADT types with compatible operations).
We are not completely happy with the current constraint syntax, and some other
aspects of the scheme, and so that
be described here later once we have settled it.
.NH 1
Dis and virtual machine
.LP
To make the Limbo changes and extensions some new operators were added to
the virtual machine.
(We also added a
.CW casel
operator to allow
.CW case
statements to work on
.CW big
values.)
Modules that have exception handlers also have a (new) exception table,
added to the Dis object format.
Furthermore, we moved the import table used by the
.CW load
operator out of the Dis data space into the object format
(which also makes it available for inspection by
.CW wm/rt
amongst others).
.LP
There is now an internal interface to set conditions under
which modules must be signed to be loaded, and to check a signature on a module.
Appropriate stubs are defined when module signing is not configured; if
.I sign (3)
is configured, however, it replaces them by ones that enforce its signing policy.
.NH 1
Window manager
.LP
The window manager
.I wm (1)
has been reimplemented by Roger Peppe.
It now multiplexes pointer and keyboard input to applications,
and manages windows on the display.
.I Tk (2)
no longer manages windows from inside the kernel.
In some ways the structure is closer to that of
.I mux (1)
and more specifically the design described in Rob Pike's paper ``A Concurrent Window System''.
It is possible to import and export window system environments between hosts.
.LP
This is one of the bigger causes of source file changes, although many of them
can be done by global substitutions (eg, using
.I acme (1)).
Appendix A gives details.
.CW Wmlib
is no longer the application's interface to the window system.
Instead that is done through a new
.CW Tkclient
module; see
.I tkclient (2).
(It uses a different
.CW Wmlib
as an auxiliary module,
and also uses a new
.CW Titlebar
module to allow the look of the window decoration to be changed more easily).
An application acquires a window by a call to
.CW Tkclient->toplevel ;
starts pointer or keyboard input if desired by calling
.CW Tkclient->startinput ;
and puts the window on screen (after sending it Tk configuration commands)
using
.CW Tkclient->onscreen .
Nothing appears on screen until that is called (which amongst other things avoids the resizing on start up that afflicted
the original scheme).
.CW Onscreen
gives it a connection to the window manager for pointer, keyboard and control input,
with a separate channel for each.
When it receives data from any of the channels
(typically using
.CW alt )
it must pass it to Tk using calls to appropriate
.CW Tkclient
functions.
.LP
The toolbar used by the old
.I wm
is now provided by a separate program
.CW wm/toolbar
(see
.I toolbar (1)),
and it is
.CW toolbar
that interprets the
.CW /lib/wmsetup
file.
.CW Wm
invokes
.CW wm/toolbar
by default so most users will see no difference, but it does make it easier to develop alternative interfaces.
More visible is that
.CW wm/logon
is now a
.I client
of the window manager, and must be invoked as follows:
.P1
wm/wm wm/logon
.P2
.LP
Applications need not even use
.I tk (2).
There is an interface for
.CW draw -only
clients,
.I wmclient (2).
.NH 1
Inferno source tree
.LP
The structure of the Inferno source tree has changed in the following ways.
.NH 2
Library source
.LP
The
.CW image
and
.CW memimage
directories have gone, replaced by
.CW libdraw
and
.CW libmemdraw .
The directories in the Inferno root that contain the source for libraries
now
always have names starting `\f5lib\f1':
.CW libcrypt ,
.CW libinterp ,
.CW libkeyring ,
.CW libmath ,
etc.
.NH 2
Emu source
.LP
The
.CW emu
directory now contains a subdirectory structure similar to the
.CW os
kernels, and uses a similar configuration file (parts list) to say what goes in
a given instance of
.CW emu .
This allows platform-dependent selection of drivers, libraries and even
.CW #/
(ie,
.I root (3))
contents to be done easily.
.LP
The top directory,
.CW /emu ,
contains:
.CW mkfile
that simply moves to the platform configured by
.CW /mkconfig ,
allowing builds in the Inferno root as before;
a subdirectory
.CW port
containing portable code (including some code shared by several platforms, such as
.CW devfs-posix.c );
and a subdirectory for each hosting platform, distinguished by an upper-case initial letter.
Current platforms include
.CW FreeBSD ,
.CW Irix ,
.CW Linux ,
.CW Nt
(for all Windows platforms after 95),
.CW Plan9 ,
.CW Solaris ,
and several others.
.NH 2
Emu configuration
.LP
Each platform-specific directory contains a configuration file with the
same structure and indeed similar contents to the ones used for the native kernel.
The default configuration file is called
.CW emu .
Another can be chosen, again in a similar way to the native kernel, by using
.P1
mk 'CONF=\fIcfile\fP'
.P2
where
.I cfile
is the name of the configuration file.
The name of the resulting executable file contains the configuration file name but depends on the platform:
it is \fIcfile\fP\f5.exe\fP on Windows, \f5o.\fP\fIcfile\fP on Unix systems, and \f58.\fP\fIcfile\fP on 386 Plan 9 systems.
The configuration file format and contents is documented for all types of kernels by
.I conf (10.6).
.NH 2
Tk source
.LP
The Tk implementation in
.CW libtk
has been made more modular.
It allows a significantly different `style' to be implemented,
and although that is by no means trivial to do, there is at least an interface to do it.
We hope to change various aspects of the standard style further, but that has not yet been done.
.NH 1
Commands and modules
.LP
There are new commands and library modules, others have become obsolete and been removed,
and a few existing ones have been given new names (typically when ones with similar function have been
collected together).
The biggest change has been to
.I wm (1),
which retains the same name but slightly different invocation and completely different
implementation,
as discussed above.
Here I shall simply note the bigger changes, rather than discuss new functionality.
.NH 2
Renamed commands
.LP
As part of a mild reorganisation of the
.CW /appl
and
.CW /dis
trees, we have moved commands out of
.CW /dis/lib
so that it now contains only library modules except for a few commands left
there temporarily for compatibility.
Commands themselves have sometimes been shuffled to subdirectories,
often copying seemingly better structure from Plan 9,
so that authentication commands are
.CW auth/ ...,
naming service commands are
.CW ndb/ ...,
and
IP-specific commands are
.CW ip/ "... ."
.LP
One noticeable change is that
.CW lib/cs
is now
.CW ndb/cs .
More dramatically, the command
.CW lib/srv
(ie,
.I srv (8))
has been replaced by
.I sh (1)
scripts, all described by
.I svc (8),
that contain appropriate calls to
.I listen (1)
after setting up any locally-desired environment.
.LP
Other commands have also moved:
.IP •
.CW lib/plumber
is now simply
.CW plumber
.IP •
.CW lib/bootp
and
.CW lib/tfptd
have become
.CW ip/bootpd
and
.CW ip/tftpd ,
documented in
.I bootpd (8)
.IP •
.CW lib/virgild
has become
.CW ip/virgild
(see
.I virgild (8))
.IP •
.CW lib/chatsrv ,
.CW lib/rdbgsrv
and
.CW cpuslave
have moved to
.CW auxi
(ie,
.CW /dis/auxi
and
.CW /appl/cmd/auxi)
.IP •
.CW csquery
has become
.CW ndb/csquery
.NH 2
New or newly-documented commands
.IP •
an authentication server (signer) can use
.I keyfs (4)
to store its keys securely in the encrypted file
.CW /keydb/keys
(instead of the unencrypted
.CW /keydb/password ),
and run
.I keysrv (4)
to offer secure change of password remotely.
They are typically started, with other signing services, by
.CW svc/auth
described in
.I svc (8).
.IP •
.CW /dis/auth
and
.CW /appl/cmd/auth
contain commands related to authentication;
they rely on
.I keyfs (4)
in most cases.
The older ones that use
.CW /keydb/passwd
are still in
.CW /dis/lib
and
.CW /appl/lib
during the transition
.IP •
.I dns (8)
has replaced the
.CW lib/ipsrv
implementation of
.I srv (2);
when used, it must be started before
.CW ndb/cs .
.I Srv (2)
has reverted to being a hosted-only interface to the hosting system's native
DNS resolver.
It is automatically used by
.I cs (8)
if it cannot find
.I dns (8),
and
.I dns (8)
will also use it if available before consulting the DNS network.
.IP •
.I chgrp (1),
.I cpuview (1),
.I grid (1),
.I 9660srv (4),
.I cpuslave (4),
.I dossrv (4),
.I keyfs (4),
.I keysrv (4),
.I nsslave (4),
.I palmsrv (4),
.I registry (4),
.I rioimport ,
.I styxchat (1),
.I styxlisten ,
.I wmexport ,
.I wmimport ,
and
.I uniq (1)
are new
.IP •
the multiplayer games software previously in
.CW /appl/games
has been replaced by a related but significantly different system in
.CW /appl/spree .
(Also see
.I spree (2)
for supporting modules.)
.IP •
.I Registry (4)
provides dynamic registration and location of services using sets of attributes/value pairs,
through a name space.
.I Registries (2)
provides a convenient Limbo interface for registration and query.
.NH 2
Commands removed
.IP •
.CW lib/csget
(see
.I cs (8)
for its replacement
.CW csquery )
.IP •
the undocumented and obsolete commands
.CW lib/isrv
and
.CW lib/istyxd
have been removed, since either the
.CW none
authentication protocol, or the
.CW -A
option to
.CW mount
can be used if no authentication is needed
.IP •
.CW lib/srv
has been replaced by
.I svc (8)
as mentioned above.
.IP •
.CW getenv
and
.CW setenv
have been removed since the Shell provides alternatives
.IP •
.CW wm/license
is no longer needed
.NH 2
New modules
.LP
There are library modules to support: registries and configuration files of attribute/value pairs;
Internet address parsing and manipulation; management of windows and subwindows (used by
.I wm (1)
itself); timers; Styx; Styx servers; exception handling; memory
and performance profiling; Freetype interface; parsing Palm databases; and navigating XML files (without reading them all into memory) and interpreting style sheets.
.NH 1
Styx
.LP
Styx was derived from the 9P protocol used by Plan 9 in 1995, with changes that reflected the requirements
of the Inferno project of the time, mainly by removing features that were thought too closely tied to the Plan 9
environment.
Some 9P messages were removed, particularly those
that incorporated details of the Plan 9 authentication methods;
Styx moved authentication outside the file service protocol.
Other changes eliminated file locking and append-only files.
Some restrictions that 9P imposed were retained, however, such as limiting file names to 27 bytes.
This last restriction is fine for synthetic network services, but
has been troublesome when trying to access Unix and Windows systems, amongst others.
.LP
A recent revision of 9P adds support for much longer file names
and takes the opportunity to improve other aspects of the protocol.
It also removes details of authentication algorithms from the protocol.
The Styx implementation now uses the new version of 9P as the default file service protocol.
(It is possible that for interoperation with older Inferno systems the system will be able to
interact with both old and new versions of Styx.)
.NH 2
Protocol changes
.LP
The messages
.CW Tauth
and
.CW Tversion
are new to Styx.
.CW Tversion
includes negotiation (at connection start) of the message size and protocol version;
it also introduces a new session.
.CW Tauth
obtains access to a special authentication file if the server requires
authentication within a Styx session.
.CW Tclone
has been replaced by a more elaborate form of
.CW Twalk
that allows zero to MAXWELEM (16) elements to be walked, perhaps to a new fid, in a single message,
returning a sequence of qid values in
.CW Rwalk .
(A clone is simply a walk of a fid to a new fid with zero elements.)
A walk of several elements can return partial results if the walk of the first element succeeds but
subsequent ones fail.
A partial walk leaves the state of the fids unchanged.
.CW Ropen
and
.CW Rcreate
return a suggested size for atomic I/O on the fid (0 means `not given').
All strings are variable length, and consequently
.CW Twstat
and
.CW Rstat
data is variable length and formatted differently.
Data returned from
.CW Tread
of a directory is similarly changed, because
directory entries are not fixed length.
.CW Tnop
has gone.
.LP
Tags remain 16-bit integers, but fids and counts
become 32-bit integers (mainly of interest to large systems),
and qids have a different structure.
Previously a qid was a pair of 32-bit integers, path and vers, where
path had the top bit set for a directory.
Now a qid is a triple: a 64-bit path, 32-bit vers, and 8-bit type.
The type is defined to be the top 8 bits of the file's mode.
The path does not have the top bit set for a directory, and indeed the
path value is not interpreted by the protocol.
There are now bits in the file mode for append-only and exclusive-use
files (new for Inferno), and for authentication files (new for both Plan 9 and Inferno).
The stat information includes the user name that last caused the file's mtime to be changed.
All strings in the protocol are variable length: file names, attach names, user names, and error text.
.LP
The message format on the wire is significantly different.
The message size is negotiated for a connection by
.CW Tversion ,
and messages can be large, allowing much more data to be sent in single
.CW Twrite
and
.CW Rread
messages.
The header includes a 32-bit message size, making it easy to find message boundaries without
parsing the contents.
Strings are
represented as a 16-bit size followed by the string's UTF-8 encoding (without zero byte).
R-messages do not carry a copy of the fid from the T-message.
Padding bytes have gone.
The order of some fields has changed of course to match message parameter changes.
.LP
Authentication of the connection itself, and optionally
establishing the keys for digesting and encryption,
is done before the protocol starts, in both Inferno and Plan 9.
Details will follow on the protocol for that, and Limbo interfaces.
For now, it can be assumed that the old authentication messages can still be used,
even after a more flexible protocol has been implemented.
.CW Tauth
can be used to authenticate particular accesses within such a session, but
implies trust by the server that the client system will not cheat its users.
(That trust is typically established by the connection level authentication which is needed
anyway for link encryption, and thus for single-user clients further authentication
seems extraneous in most cases.)
Most Inferno services that run as file servers within a system (eg,
.CW 9660srv )
will, like Plan 9's, reply to
.CW Tauth
with an
.CW Rerror
stating ``authentication not required''.
Access to them when exported is typically controlled as now by verifying the incoming connection.
.NH 2
Limbo interface changes
.LP
Because Limbo's interface to file service via
.CW Sys
and other modules uses Limbo
.CW string
for names, and that is inherently
variable length, there are no interface changes required for that aspect of the protocol change,
and consequently no source changes
(in contrast to the introduction of 9P2000 in C implementations).
Similarly the Inferno directory reading interfaces remain unchanged.
.LP
The `directory mode' bit previously called
.CW CHDIR
is now called
.CW DMDIR .
It is used
.I only
in
.CW Dir.mode .
.CW CHDIR
is no longer defined, partly because it was used both
in
.CW Dir.mode
and
.CW Qid.path ,
and the latter instances must change (discussed below).
There are bits (new to Inferno) for
.CW DMAPPEND
(append-only file),
.CW DMEXCL
(exclusive-use file),
and
.CW DMAUTH
(authentication file).
The protocol can return the user name of the user that caused
.CW mtime
to be changed on a file; that is now available as
.CW Dir.muid .
.LP
The structure of
.CW Qid
has changed.
Previously a Qid had a 32-bit
.CW path
and a 32-bit version number,
.CW vers .
The top bit
.CW CHDIR ) (
of
.CW path
was set iff the Qid was that of a directory.
The
.CW path
is now 64 bits (which is
.CW big
in Limbo and
.CW vlong
in the kernel), and there is no longer the convention that the top bit of
.CW path
must be 1 for a directory.
Instead, there is a new, separate
.CW type
field (called
.CW qtype
in Limbo)
that has the value of the top 8 bits of the file's mode.
Each bit \f5DM\fIx\f1 in
.CW Dir.mode ,
has got a corresponding bit \f5QT\fIx\f1
in
.CW Qid.qtype :
.CW QTDIR ,
.CW QTAPPEND ,
.CW QTEXCL
and
.CW QTAUTH .
The bit
.CW QTDIR
.I must
be set in the
.CW Qid.qtype
for a directory, and only then.
There is an extra constant
.CW QTFILE
that is defined to be zero, and is used for clarity when neither
.CW QTDIR
nor
.CW QTAUTH
is set.
.LP
In Styx file servers, changes are required to reflect the slightly different set of message types
and a few new parameters, but the main changes are:
handling zero or more name elements at once in
.CW Twalk
and
.CW Rwalk ;
changing
.CW CHDIR
to
.CW DMDIR
in
.CW Dir.mode
(easy);
the use of the new
.CW Qid.qtype
field
and
.CW QTDIR
instead of
.CW CHDIR
in
.CW Qid.path
(a little more effort);
and (typically) the insertion of casts to force
.CW Qid.path
to
.CW int
and thus ensure the use of 32-bit operations except where 64-bit paths really are needed
(hardly ever in synthetic file servers).
The new modules for use by file servers are discussed in the next section.
.LP
The revised definition of
.CW Twstat
in
.I stat (5),
and thus
.CW sys->wstat ,
provides for ``don't care'' values in
.CW Dir
that are tedious to provide directly; a new adt value
.CW Sys->nulldir
provides the right initial value for a
.CW Dir
which is then changed as needed for
.CW wstat .
.SH
.I "Examples"
.LP
Create a directory:
.P1
	\fIold:\f5
fd := sys->create(name, Sys->OREAD, Sys->CHDIR | 8r777);

	\fInew:\f5
fd := sys->create(name, Sys->OREAD, Sys->DMDIR | 8r777); # not CHDIR
.P2
.LP
Make Qids
for a file and a directory:
.P1
	\fIold:\f5
Qdir, Qdata: con iota;
qd := Sys->Qid(Sys->CHDIR | Qdir, 0);
qf := Sys->Qid(Qdata, 0);

	\fInew:\f5
Qdir, Qdata: con iota;
qd := Sys->Qid(big Qdir, 0, Sys->QTDIR);
qf := Sys->Qid(big Qdata, 0, Sys->QTFILE);
.P2
.LP
Test if a file is a directory:
.P1
	\fIold:\f5
isdir(d: Sys->Dir): int
{
	return (d.mode & Sys->CHDIR) != 0;
\fIOR:\f5
	return (d.qid.path & Sys->CHDIR) != 0;
}

	\fInew:\f5
isdir(d: Sys->Dir): int
{
	return (d.mode & Sys->DMDIR) != 0;
\fIOR:\f5
	return (d.qid.qtype & Sys->QTDIR) != 0;
}
.P2
.LP
If one wishes to have values
.CW big
only when required, one can write:
.P1
case int dir.qid.path {
Qdir =>
	...
Qdata =>
	...
Qctl =>
	...
}
.P2
Of course with the Dis change mentioned above,
.CW case
can now be applied to
.CW big
values, so it is no longer necessary to add the cast (as it once was).
Even so, 32-bit operations are faster when they suffice.
.NH 2
Styx protocol in Limbo: Styx and Styxservers
.LP
A new module
.CW Styx ,
defined by
.CW styx.m ,
provides access to the Styx protocol messages, as variants of pick adts
.CW Tmsg
and
.CW Rmsg .
(There was an old, undocumented
.CW Styx
module but this new interface is completely different.)
It is used by several file servers, such as
.CW dossrv ,
.CW cdfs ,
and the new
.CW logfs .
See the attached manual page.
There are several implementations with the same signature, covering different
combinations of old and new Inferno and old and new protocols, through
the same interface.
There are slight differences in the application code for old and new
systems because of the changed
type and structure of
.CW Qid .
The versions that talk the old protocol need to store some internal state,
and are intended only to meet compatibility requirements during the transition.
.LP
Many file service applications, however, serve a simple name space,
requiring more than can be done with
.CW file2chan ,
but wishing some help in handling the protocol details.
Two new modules
.CW Styxservers
and
.CW Nametree
are provided to make such applications easier to write.
They are closely related and thus both modules are defined by
.CW styxservers.m .
.LP
.CW Styxservers
provides help in handling fids and interpreting the Styx requests for navigating a
name space, and provides a reasonable set of default actions,
allowing the application to focus on implementing
read and write access to the files in the name space.
It uses
.CW Styx
to talk to the Styx client on a connection.
It interacts with the application through a channel interface and
the
.CW Navigator
adt to navigate an abstract
representation of the application's name space.
The module can be used on its own, with the application doing the work
of replying to those queries itself, or it can get extra help in the common cases from
.CW Nametree .
.CW Nametree
provides a
.CW Tree
adt and operations for the application to build an abstract representation of a name space
and maintain it dynamically quite simply, and it exports the channel interface used by
.CW Styxservers
for navigation, thus connecting the two, but leaving the application in complete
control of the name space contents viewed by Styx.
See the manual pages
.I styxservers (2)
and
.I styxservers-nametree (2),
attached.
The latter includes a short working example of combining the two modules.
.LP
The previous release of the system had a module
.CW Styxlib
that combined the functions of
.CW Styx
and
.CW Styxservers .
It remains for a time for transition, but newer applications should use either
.CW Styx
or
.CW Styxservers .
.LP
A new command
.I styxchat (8)
exchanges Styx messages with a server, reading a textual representation of T-messages
on standard input.
It can be helpful when testing a Styx server implementation.
(It was originally developed to test the
.CW Styx
module implementations in several configurations.)
See the attached manual page for details.
It also supports an option that allows it to act as a server,
printing T-messages as they are received from clients, and
reading R-messages in a textual form from standard input for replies.
.NH 2
Device driver changes
.LP
Most of the differences for most drivers are relatively minor
(in
.CW diff
terms).
.LP
Throughout the hosted and emulated kernels:
.IP \(bu
.CW Qid
now is the structure:
.RS
.P1
struct Qid {
    vlong   path;
    ulong   vers;
    uchar   type;
};
.P2
The
.CW type
field has values
.CW QTDIR ,
.CW QTFILE ,
.CW QTAPPEND ,
etc.
The test previously written
.P1
if(qid.path & CHDIR)
.P2
is now written
.P1
if(qid.type & QTDIR)
.P2
Because of that change, the various
.CW switch
statements in the drivers that previously read
.P1
switch(c->qid.path){
.P2
or
.P1
switch(c->qid.path & ~Sys->CHDIR){
.P2
now read
.P1
switch((ulong)c->qid.path){
.P2
to keep operations to 32 bits (except where otherwise required).
.RE
.IP \(bu
The first entry of a driver's
.CW Dirtab
.I must
be an entry for
\f5"."\fP,
if the driver uses
.CW devgen
to help implement
.I walk ,
.I stat ,
.I devdirread
or
.I open
operations.
.IP \(bu
Offsets passed to the driver's
.I read
and
.I write
entry points are
64-bit
.CW vlong ,
not 32-bit
.CW ulong .
.IP \(bu
The
.I stat
entry point has an extra buffer size parameter:
.RS
.P1
int \fIxyz\f5stat(Chan *c, uchar *dp, int n)
.P2
It also returns an integer: the size of the result.
.CW Devstat
accepts the extra parameter and returns an appropriate result:
.P1
static int
\fIxyz\f5stat(Chan *c, uchar *dp, int n)
{
	return devstat(c, dp, n, rtcdir, nelem(\fIxyz\f5dir), devgen);
}
.P2
.RE
.IP \(bu
The biggest change is to
.I walk .
It has the signature:
.RS
.P1
Walkqid *\fIxyz\f5walk(Chan *c, Chan *nc, char **names, int nname);
.P2
and it allows zero or more elements to be walked in a single call,
returning its result in a newly-allocated
.CW Walkqid
structure:
.P1
struct Walkqid {
	Chan*	clone;
	int	nqid;
	Qid	qid[1];
};
.P2
Note that the array
.CW Walkqid.qid
must actually hold up to
.I nname
Qids, and thus is allocated as follows:
.P1
wq = smalloc(sizeof(Walkqid)+(nname-1)*sizeof(Qid));
.P2
The driver must take care that the space is reclaimed if
.CW error
is called before its
.I walk
function returns, by using
.CW waserror
as required.
Fortunately,
.CW devwalk
looks after the details of
.I walk
and
.CW walkqid
for most drivers:
.P1
static Walkqid*	 
\fIxyz\f5walk(Chan* c, Chan *nc, char** name, int nname)
{
	return devwalk(c, nc, name, nname, \fIxyz\f5dir,
		nelem(\fIxyz\f5dir), devgen);
}
.P2
.RE
.IP \(bu
The
.I clone
entry point has gone, since cloning is seen by a driver as a particular form of call to its
.I walk
entry,
where the parameter values satisfy:
.RS
.P1
c != nc && nwname == 0
.P2
One difference is that a node can be cloned and walked in a single operation,
in other words
.CW nwname
can be non-zero,
and the incoming
.CW nc
is often nil and a new
.CW Chan
must be allocated.
Note that if the driver found it adequate to call
.CW devclone
previously, then
the new
.CW devwalk
will
generally look after it as well.
.CW Devclone
remains for use as a utility function for the few drivers that need to
clone a channel themselves,
in their
.I walk
operations or elsewhere.
.RE
.IP \(bu
The
.I detach
entry has been renamed
.I shutdown
(it was never the opposite of
.I attach ).
The stub
.CW devshutdown
can be used by devices that do not need it.
.LP
For drivers that serve a simple name space using the functions of
.CW dev.c
(described in
.I devattach (10.2)),
only a handful of simple changes are required.
Most are pointed out by the compilers as type clashes.
The main exception is the need for a
.CW Dirtab
to have its first entry be an entry for \f5"."\fP if the
.CW Dirtab
will be passed to
.CW devgen
via
.CW devwalk ,
.CW devstat
and
.CW devdirread .
.NH 1
Sys module changes
.LP
.NH 2
Sys: name change(s)
.LP
The name
.CW ERRLEN
has become
.CW ERRMAX
(since it is the limit to any error string, not its necessary length).
.CW NAMELEN
has been removed,
to allow each instance to be found (by compilation) and either removed
(where it was simply limiting the length of a file name), or replaced by
.CW NAMEMAX
where it was used as a buffer size to read in names such as
.CW /dev/sysname
or
.CW /dev/user .
.NH 2
Sys: file sizes
.LP
The Styx protocol has always supported 64-bit file sizes and file offsets.
The Inferno interface has not.
.CW Sys
has changed so that length and offset values become
.CW big ,
specifically:
file size
.CW Dir.length ,
the offset parameter to
.CW seek ,
and
.CW seek 's
result.
.LP
These and the Qid changes account for quite a few changes in
our own source tree.
Typically, applications did things like this:
.P1
	\fIold:\f5
buf := array[d.length] of byte;

sys->seek(fd, 0, Sys->SEEKSTART);
off := sys->seek(fd, 0, Sys->SEEKRELA);	rec := off + HDRLEN;
for(offset := 0; offset < d.length; offset += RECSIZE){
	sys->seek(fd, offset, Sys->SEEKSTART);
	...
}
.P2
The compiler now objects in each case because
.CW big
values are now appearing where
.CW int
is required, or conversely.
In some cases it is obvious that adding a cast is correct;
in others it is worth considering whether the calculation should indeed
be
.CW big
because file sizes for instance can in practice exceed the range of a
signed integer without too much trouble today, especially when the `file'
is a storage device.
The case that some people like and some dislike is:
.P1
if(sys->seek(fd, big offset, Sys->SEEKSTART) < big 0) ...
.P2
where the
.CW "big 0"
is needed because
.CW sys->seek
is
.CW big ,
and there are no `usual arithmetic conversions' as in C.
(Given the tangle that several languages have made of such conversions, perhaps
being strict is correct.)
.NH 2
Sys: export
.LP
.CW Sys->export
now has the signature:
.P1
export:	fn(c: ref Sys->FD, dir: string, flag: int): int;
.P2
allowing a directory
.I dir
other than \f5"/"\f1
to be exported.
It replaces the
.CW exportdir
function of (later) Third Edition.
.NH 2
Sys: Styx support
.LP
The revision of Styx has caused three calls to be added:
.P1
fauth:    fn(fd: ref Sys->FD, aname: string): ref Sys->FD;
fversion: fn(fd: ref Sys->FD, msize: int, version: string): (int, string);
iounit:   fn(fd: ref Sys->FD): int;
.P2
.CW Fversion
initialises a Styx session on connection
.I fd ,
sending the message size
.I msize
and protocol version string
.I version ;
it returns a tuple giving the message size and version returned by the Styx server.
It is rarely called directly; the
.CW mount
operation does it automatically on an uninitialised connection.
.LP
.CW Fauth
sends a Styx
.CW Tauth
message on connection
.I fd ,
and if successful, returns a file descriptor that
refers to an authentication file provided by the file server,
which may be read and written by
.CW Sys->read
and
.CW Sys->write
to implement the authentication protocol(s) supported by the server.
.CW Fauth
is needed only when the server requires authentication.
.LP
.CW Iounit
returns the `atomic IO unit' suggested for the file
.I fd
by its file server when it was opened.
.NH 2
Sys: mount
.LP
The
.CW mount
system call has acquired a second file descriptor parameter:
.P1
mount: fn(fd: ref Sys->FD, afd: ref Sys->FD, on: string,
          flags: int, spec: string): int;
.P2
.I Afd
is nil if the file server is known not to require authentication within a Styx session.
(The connection might itself have been authenticated previously, for instance,
and most file servers such as
.CW dossrv ,
.CW ftpfs
and
.CW dbfs
are invoked to provide services to an already-authenticated user, and therefore
do not require authentication within a session.)
If the server does require authentication,
.I afd
refers to a file descriptor returned by a previous
.CW fauth
on connection
.I fd ,
on which an authentication protocol has subsequently been executed as required by the file server connected to
.I fd .
.NH 2
Sys: other new system calls
.LP
There are two more new system calls:
.P1
fd2path: fn(fd: ref Sys->FD): string;
werrstr: fn(s: string): int;
.P2
.CW Fd2path
returns the path name under which the file descriptor
.I fd
was originally opened (if known).
One result is that
.I workdir (2)
produces reasonable results for the name of the current directory
in the presence of mounts and binds.
.LP
.CW Werrstr
sets the per-process system error string to
.I s ,
to allow a Limbo function to save and restore an error string over
other system calls, to present a similar interface
as the system calls on errors, or to annotate the error from a system call
for its own caller.
.NH 2
Sys: directory reading
.LP
The
.I sys-dirread (2)
system call's signature has changed:
.P1
dirread: fn(fd: ref Sys->FD): (int, array of Sys->Dir);
.P2
Previously it accepted an array of
.CW Dir
to fill and returned a count;
now it returns a tuple containing the count and the array of values read.
The change was needed because the representation of directory entries
is now variable length, and it is difficult to limit the number returned
(it is possible, but all the methods have disadvantages).
.CW Dirread
still reads a directory incrementally, requesting a block of directory entries
of reasonable size from the file server, and unpacking them into the returned array.
Use
.I readdir (2)
to read whole directories at once.
.NH 1
Bufio
.LP
There are several changes to
.CW Bufio :
.P1
Iobuf: adt {
	...
	seek:	fn(b: self ref Iobuf, n: big, where: int): big;
	offset:	fn(b: self ref Iobuf): big;
};
# flush: fn();	# deleted
.P2
The module-level function
.CW Bufio->flush
has been removed
(\fInot\fP
.CW Iobuf.flush ),
to allow concurrent use of a single
.CW Bufio
instance; applications must
.CW close
or
.CW flush
each output file explicitly.
.LP
As a result of the change to 64-bit offsets for
.CW Sys->seek ,
.CW Iobuf.seek
also accepts and returns
.CW big
offsets.
.CW Iobuf.offset
is new, and returns the current file offset in bytes, taking account of any buffering.
.LP
.CW Iobuf.flush
has been extended to flush any data buffered on input files.
.NH 1
Draw
.LP
The graphics model represented by the
.I draw (3)
device and the
.CW Draw
module is significantly different, including support for a range of pixel formats,
and compositing in the drawing operations.
Most source code that uses Images
directly will require some changes, but the scope of them is limited: needing only extra
or different parameter values to individual operations, not radical restructuring.
The following changes affect most non-Tk graphics application code:
.IP \(bu
Pixels in an
.CW Image
can now be more than 8 bits and have a more flexible structure
(eg, several colour channels, and an optional alpha channel, of up to 8 bits each).
To support that, the old
.CW ldepth
field has gone, replaced by a channel descriptor
.CW chans
of type
.CW Chans ,
which describes the pixel structure, and an integer
.CW depth
field, which gives the total pixel size (depth) in bits.
.IP \(bu
The colour parameters are now 32-bit RGBA values
(red, green, blue and alpha components, 8-bit each, and big-endian
only when an
.CW int ).
.IP \(bu
The graphics subsystem supports Porter-Duff compositing,
combining a destination image with a source image (within an optional matte)
according to a compositing operator.
The interpretation of the old `mask' Image parameter to
.CW draw
and
.CW gendraw
has changed.
Previously it provided a simple binary mask;
it now provides a `matte', and its
alpha channel shapes the source image and adds partial transparencies.
If the matte parameter is nil, the source image is used unmodified.
If it lacks an alpha channel, one is computed from the matte image colour channels.
The drawing operations
.CW draw ,
.CW gendraw ,
.CW line ,
.CW text ,
and so on,
have all got variants
.CW drawop ,
.CW gendrawop ,
.CW lineop ,
.CW textop ,
and so on,
each taking an extra final parameter that specifies a Porter-Duff
compositing operator from a set predefined by
.CW Draw :
.CW SoverD ,
.CW SinD ,
.CW DatopS ,
and so on.
In each case,
.CW S
refers to the source image (within a matte, if provided), and
.CW D
refers to the destination image.
Most of them are useful only when either or both source or destination images have got
alpha channels (or a matte is used to shape the source).
The old function names without the
.CW op
suffix use the most common compositing operation
.CW Draw->SoverD ,
drawing the source image over the destination,
taking account of the shaping of the source and destination images by their alpha channels,
with the source further shaped by the optional matte.
Thus
.CW Image.draw
continues to do the `obvious' thing.
.IP \(bu
There are new colour map conversion functions.
.LP
The
.CW Chans
adt is the following:
.P1
Chans: adt
{
	# interpret standard channel string
	mk:    fn(s: string): Chans;
	# standard printable form
	text:  fn(c: self Chans): string;
	# equality
	eq:    fn(c: self Chans, d: Chans): int;
	# bits per pixel
	depth: fn(c: self Chans): int;
};
.P2
Values are created by
.CW Chans.mk ,
which accepts a string that is a sequence of channel descriptors,
each being a letter representing a channel type followed by an integer giving the channel's size (depth, width) in bits.
The letters include:
.CW r ,
.CW g
and
.CW b
for red, green and blue;
.CW a
for alpha;
.CW k
(!) for greyscale; and
.CW x
for padding (``unspecified'', ``don't care'').
Thus
.CW Chans.mk("r8g8b8a8")
produces a descriptor for a 32-bit pixel with 8-bit colour and alpha components.
The same descriptor is used in the revised
.I image (6)
format, although the older image file format with ldepth only is still recognised.
Given a Chans value
.I c ,
\fIc\fP\f5.text()\fP returns such a descriptor for it as a string.
.LP
When
.CW newimage
previously was called with a specific value for
.CW ldepth ,
an appropriate
.CW Chans
value must replace it.
A few common variants are defined as constants of type
.CW Chans
in
.CW Draw .
(We extended the Limbo compiler last year to support the use of
.CW con
with adt and tuple constants with this use in mind.)
For example, the value
.CW Draw->CMAP8
is the descriptor for the 8-bit deep
.I rgbv
colour-mapped Image format previously used by Inferno.
The list of predefined channels includes:
.TS
center;
cfI cfI cfI cfI
n lf(CW) n lw(3i) .
Old ldepth	Name	Bit depth	Description
0	GREY1	1	single 1-bit deep greyscale channel
1	GREY2	2	single 2-bit deep greyscale
2	GREY4	4	single 4-bit deep greyscale
\-	GREY8	8	single 8-bit deep greyscale
3	CMAP8	8	single 8-bit deep \fIrgbv\f1 colour-mapped channel
\-	RGB15	15	three channels RGB: r5g5b5
\-	RGB16	16	three channels RGB: r5g6b5
\-	RGB24	24	three channels RGB: r8g8b8
\-	RGBA32	32	four channels: RGB and alpha: r8g8b8a8
.TE
.LP
The use of
.CW Chans
instead of
.CW ldepth
means that calls to
.CW Display.newimage
must be changed.
For instance:
.P1
\fI(old)\f5
buffer := display.newimage(r.inset(3), t.image.ldepth, 0, Draw->White);
.P2
becomes
.P1
\fI(new)\f5
buffer := display.newimage(r.inset(3), t.image.chans, 0, Draw->White);
.P2
There is an obvious difference: the
use of
.CW t.image.chans
instead of
.CW t.image.ldepth
to create a buffer Image with the same pixel structure as
.CW t .
There is, however, another difference.
The final colour parameter to
.CW newimage
is also different in structure: in the new graphics model, it is a 32-bit integer value giving RGBA
components,
not a colour map index, and the name
.CW Draw->White
has the value
.CW 16rFFFFFFFF
not
.CW 0 .
Because a symbolic name was used, however, the source need not change.
As another example,
.CW Draw->Palegreyblue
is
.CW "int 16r4993DDFF" .
Note the final
.CW FF
for the alpha component (creating a fully opaque colour).
When the top bit is set, the
.CW int
cast shown here is needed to force the otherwise
.CW big
value to 32 bits.
.LP
The values of colour components are now uniformly expressed as
intensity, so that a pixel with all zero colour components is black and
one with all colour components at maximum (all ones, full intensity)
is white.
The
.I rgbv
map has therefore been reversed.
Given a map index,
.CW Display.cmap2rgba
returns the 32-bit RGBA format used as a parameter in other calls.
All colour components are
.I linear
values, as required for compositing to work properly;
gamma correction is done as required by the display subsystem.
.LP
The colour components of a pixel with an alpha component are always
.I pre-multiplied
by the alpha value, following Porter and Duff, as further justified by Alvy Ray Smith and Jim Blinn.
``Thus a 50% red is
.CW 16r7F00007F
not
.CW 16rFF00007F .''
The function
.CW Draw->setalpha
does the computation.
.LP
Because of the changes to colours and the replacement of simple masks by mattes, the Images
.CW Display.ones
and
.CW Display.zeros
are no longer defined.
Instead, when they were intended to represent colours, the new Images
.CW Display.black
and
.CW Display.white
provide the obvious colours.
When
.CW ones
and
.CW zeros
were used as masks, the new predefined Images
.CW Display.opaque
and
.CW Display.transparent
are used instead as constant mattes, with alpha channels (fully opaque and fully transparent, respectively).
As noted above, where
.CW Display.ones
was used as a mask parameter in drawing operations, one can
simply specify a nil Image as a matte (`no matte') instead.
(That has been allowed for quite some time and is in use but might not be widely known.)
.LP
For example, Charon allocated a mask using:
.P1
dpicmask = display.newimage(pic.r, 0, 0, Draw->White);
.P2
which becomes
.P1
dpicmask = display.newimage(pic.r, Draw->GREY1, 0, Draw->Opaque);
.P2
where
.CW GREY1
is a constant value of the
.CW Chans
adt type, predefined by Draw, for Images that have a single 1-bit deep grey channel (ie, a bitmap).
(Note that to form a fully-opaque matte,
.CW Draw->Opaque
was used for clarity, not
.CW Draw->White ;
.CW Draw->Transparent
could also be used, as the basis for building a matte with transparency.)
.LP
A small if obscure change is that
.CW Display.newwindow
has a new parameter:
.P1
newwindow:	fn(screen: self ref Screen, r: Rect,
	backing: int, color: int): ref Image;
.P2
The
.I backing
parameter should usually be
.CW Draw->Refbackup ,
except for windows allocated on an image that already has got backing store
assigned, for instance because it is an image on a screen on an existing window image, in which case it should be
.CW Draw->Refnone ,
because the parent window already provides the backing.
.LP
As a small but helpful change, the adt
.CW Draw->Pointer
has a new element
.CW msec
that reports a
relative time stamp in milliseconds.
.LP
The
.CW Draw->Context
content is significantly different, for the benefit of the new
window system implementation.
.NH 1
Tk module
.LP
There is a new function in
.CW Tk :
.P1
quote:   fn(s: string): string;
.P2
.CW Quote
returns string
.I s
quoted according to Tk's `\f5{}\f1' quoting conventions.
It replaces
.CW Wmlib->tkquote .
.LP
There is a new widget type:
.I panel (9).
A panel instance can be packed and otherwise manipulated in the same way as any other Tk widget.
An image is associated with it by calling
.CW Tk->putimage
defined in
.I tk (2).
The associated images can be drawn on directly by the application, using all the operations provided by
.CW Draw .
The coordinates of the changed rectangle must be given to Tk
using the
.CW panel
widget command
.CW dirty ;
that part of the image will be redrawn if necessary at the next Tk
.CW update .
A panel has no default bindings.
See
.I panel (9)
for details.
.LP
For example,
.CW wm/coffee
now uses the following:
.P1
r := Rect((0, 0), (400, 300));
buffer := display.newimage(r, t.image.chans, 0, Draw->Black);
tk->cmd(t, "panel .f.p -bd 3 -relief flat");
tk->cmd(t, "pack .f.p -fill both -expand 1");
tk->cmd(t, "update");
org := buffer.r.min;
tk->putimage(t, ".f.p", buffer, nil);
.P2
When it has updated the
.CW buffer ,
it tells Tk:
.P1
tk->cmd(t, ".f.p dirty; update");
.P2
In this case the whole image is marked dirty, but
.CW dirty
can be given an optional rectangle parameter to restrict redrawing.
.LP
.CW Tk->putimage
and
.CW Tk->getimage
replace
.CW imageput
and
.CW imageget .
.NH 1
Selectfile, Tabs and Dialog
.LP
The functions
.CW filename ,
.CW mktabs
(and
.CW tabsctl ),
.CW dialog
and
.CW getstring
have been moved to separate new modules, to allow those aspects of the
user interface to be changed by replacing the implementations,
and to allow standard modules to be provided for picking colours (for instance).
.CW Selectfile
acquires
.CW filename ,
.CW Tabs
acquires the `tabs' Tk pseudo-widget, and
.CW Dialog
acquires
.CW dialog ,
which is renamed
.CW prompt ,
and
.CW getstring .
In cases where the functions took a
.CW Tk->Toplevel
as a parameter to specify a
.CW parent
window,
they now take a
.CW Draw->Context
and (parent)
.CW Image
parameter;
given a Toplevel
.CW t ,
use
.CW t.image .
See
.I dialog (2),
.I selectfile (2)
and
.I tabs (2).
.TL
Appendix A: Tk client conversion
.LP
.I Wm (1)
applications now have to feed their own pointer and keyboard
input to Tk. The window manager is now kept informed about the placement
of windows.
.LP
A Tk toplevel now holds a window manager context:
.P1
Wmcontext: adt
{
	kbd: 		chan of int;		# incoming characters from keyboard
	ptr: 		chan of ref Pointer;	# incoming stream of mouse positions
	ctl:		chan of string;		# commands from wm to application
	wctl:		chan of string;		# commands from application to wm
	images:	chan of ref Image;	# exchange of images
	connfd:	ref Sys->FD;		# connection control
	ctxt:		ref Context;
};
.P2
It contains some channels on which the window manager
sends information to the application, and a file
descriptor that can be used to write requests to the window
manager.
The channels used directly by the application are:
.RS
.IP \f(CWkbd\fP
characters typed by the user (pass them to
.CW Tk->pointer )
.IP \f(CWptr\fP
pointer events (pass them to
.CW Tk->keyboard )
.IP \f(CWctl\fP
application control requests.
Passing these to
.CW Tkclient->wmctl
will do the default action.
Requests starting with an exclamation mark
.CW ! ) (
can cause the application's image to change.
.RE
.LP
The toplevel also holds a channel
.CW wreq
on which it sends application
control requests; these have the same form as those
sent on
.CW Wmcontext.ctl ,
and can be forwarded to
.CW Tkclient->wmctl
in the same way.
.LP
Control requests currently understood by
.I wm (1)
are:
.RS
.IP "\f(CW!reshape \fItag\fP \fIreqid\fP \fIminx\fP \fIminy\fP \fImaxx\fP \fImaxy\fP [\fIhow\fP]\fR
.br
Reshape the window referenced by
.I tag ,
creating a new image if
.I tag
did not previously exist.
.I Reqid
is ignored.
.I How
can be one of:
.RS
.IP \f(CWplace\fP 15
.I Wm
attempts to find a suitable patch of screen real estate on which to place
the window; the size of the given rectangle
is taken to be the minimum size for that window.
.IP \f(CWexact\fP
Reshape to the exact rectangle requested.
This is the default if
.I how
is not given.
.IP \f(CWonscreen\fP
The given rectangle is adjusted so that it is no bigger than the available
screen space, and is entirely on screen.
.RE
.IP "\f(CWdelete \fItag\fP\fR
.br
Delete the image associated with
.I tag .
.IP "\f(CWraise\fP
.br
Raise the window
.IP "\f(CWlower\fP
.br
Lower the window
.IP "\f(CW!move \fItag\fP \fIreqid\fP \fIstartx\fP \fIstarty\fP\fR
.br
Request the user to move the window to a new place.
.I Startx
and
.I starty
are the coordinates of the pointer when the request was initiated.
.IP "\f(CW!size \fItag\fP\fR
.br
Request the user to resize the window.
.RE
.LP
To convert a typical Tk application, do the following.
.IP 1.
Use an editor to make the following changes:
.RS
.TS
cfI cfI
lf(CW) lf(CW) .
Old	New
Wmlib	Tkclient
wmlib	tkclient
tkclient->titlebar	tkclient->toplevel
tkclient->titlectl	tkclient->wmctl
tkclient->taskbar	tkclient->settitle
tk->imageput	tk->putimage
tk->imageget	tk->getimage
.TE
.RE
.IP 2.
Insert the following code at the top of the central
.CW alt
statement.
The names
.CW wmctl ' `
and
.CW top ` '
will need changing to the appropriate variables in the program:
.RS
.P1
s := <-top.ctxt.kbd =>
	tk->keyboard(top, s);
s := <-top.ctxt.ptr =>
	tk->pointer(top, *s);
s := <-top.ctxt.ctl or
s = <-top.wreq or
s = <-wmctl =>
	tkclient->wmctl(top, s);
.P2
.RE
.IP 3.
Add the following just after the Tk configuration code and
before the main processing starts:
.RS
.P1
tkclient->onscreen(top, nil);
tkclient->startinput(top, "kbd"::"ptr"::nil);
.P2
This is possibly the easiest part to forget.
.RE
.LP
Be careful of cases where a blocking function is called
from the main loop that relies on keyboard/mouse input.
The easiest solution can be to spawn a thread to handle the
keyboard and mouse independently.