@chapter Generic Networking Applications
@label[chapter-doc-generic-applications]

This chapter documents the networking functions and applications
that are ``generic'', that is, not associated with a particular network interface.
These applications function equivalently, for the most part,
using either Chaosnet or TCP/IP.

@section File Access

An outstanding feature of the LISP machine software is its relatively transparent
integration of local and remote host types for file access and transfer mechanisms.
The @b(pathname) scheme on the Lambda allows the specification of both physical and logical hosts
which may be remotely accessed by either Chaosnet or TCP/IP.

The primary references on the pathname system are the @LMM@  and
@i(Common LISP - The Language).

Briefly, a pathname may generally be specified as either a string or as a pathname object
constructed by functions such as @l(make-pathname).
A pathname is always parsed with respect to the physical host type indicated 
by the host portion of the pathname.
These physical host types are specified in the site files;
see Section @ref[section-host-types].

It is important to note that (with the exception of @see[ftp:ftp][fun]), pathnames are
parsed by the Lambda software according to its rules for the respective host type.
These parsing rules approximate, as well as possible, the native pathname syntax
that applies on the remote host.

Also, pathnames are generally parsed with respect to a current set of
pathname defaults (such as the most recently specified host)
that are appropriate to the environment the user is in.

Pathnames are generally specified with the host name first, followed by
the directory and file specifications.
A colon ``:'' is appended to the host name to distinguish it from other
pathname components.
For each host type, various other conventions must be followed.
Below are some examples with comments on pertinent features of the host-pathname type.

@subsection Unix Pathnames

@enumerate
@item
Because the @i(slash character) ``@b[/]'' is used in ZetaLISP mode as the ``character quote'',
it is necessary to double-quote it by specifying the @b[/] twice where Unix requires it once.
In CommonLISP mode this double-quoting is not necessary.
For example,

@lisp
In ZetaLISP:     "unix-a: //etc//rc2"
In CommonLISP:   "unix-a: /etc/rc2"
@end(lisp)

@item
Unix pathname specifications that are intended to apply to a directory,
but not to the directory @i(as a file),
must generally have a ``/'' character appended.
For example, @l(listf "unix-a:/usr/keith") will list the presence of
the directory file @l(keith), but will not list out the files contained in
that directory.
The correct specification in this instance would be "unix-a:/usr/keith/", which
is parsed into the wild-carded specification "unix-a:/usr/keith/*".

@item
Unix pathnames are not generally parsed on the Lambda with respect to a current
``working directory'', as in the Unix shells.
Instead, the current pathname defaults are applied as needed, and they
may change from one context to another.
Unless you are certain of the current pathname defaults,
specify directories completely, i.e. from the ``/'' file-system level.

@item
Some special character specifications,
such as ``..'' and ``~'', are not parsed by the Lambda.

@end(enumerate)

@subsection VMS Pathnames

Generally, VMS pathnames are parsed in accordance with VMS Version 4.0 rules.
It is generally important, however, to specify the disk/device portion of the pathname.
The default host device for each remote host is specified by the site option
@l[:HOST-DEFAULT-DEVICE-ALIST] (see Section @ref[site-option-host-device]).
For example, given the following site option entry,

@lisp
  :
(:HOST-DEFAULT-DEVICE-ALIST '(("LMI-VAX" . "USER_DISK")))
  :
@end(lisp)

pathnames on "LMI-VAX" will include the default (logical) disk device ``USER_DISK''.
Here are two examples of pathnames on LMI-VAX, with defaulted and specified devices:

@lisp
(pathname "lmi-vax:[keith]foo.com;")
#<FS::VMS-PATHNAME "VAX:USER_DISK:[KEITH]FOO.COM">
(pathname "lmi-vax:dba0:[system]sysexe.exe;*")
#<FS::VMS-PATHNAME "VAX:DBA0:[SYSTEM]SYSEXE.EXE;*">
@end(lisp)

@subsection Specifying an Unknown Host

When an unknown host is specified to @l(make-pathame), an error is signalled.
However, when an invalid host name is specified in a string that is parsed
(e.g. by @l(fs:parse-pathname)),
the parsing mechanism interprets it as a device specification.
Thus, a pathname will be returned which includes a valid host (taken from the
current defaults) and a device specification taken from the intended host.

For example,

@lisp
(make-pathname :host "unknown-host"
	       :directory "TEMP" :name :wild :type :lisp)
>>ERROR: "unknown-host" is not the name of a known file host ...

(pathname "unknown-host:temp;*.lisp")
#<FS::LM-PATHNAME "OPUS: TEMP; UNKNOWN-HOST: *.LISP">
@end(lisp)

If a program must be written so as to prevent this kind of confusion,
it should prompt for the intended host name separately from the rest of the pathname.
Then, @l(make-pathname) can be called to construct the desired pathname,
and an error will be signalled in the event of an unknown host.

@section DISK Functions
@label[section-generic-disk]

The DISK protocols of Chaosnet and TCP are provided to support disk functions such as
@l(print-disk-label) and @l(si:copy-disk-partition) over the network.
This protocol is supported @b(between Lambdas only).

The @l(UNIT) argument(s) taken by these functions allows the user to specify
a particular disk unit on the local system or a remote host.
@cindex disk unit
A disk unit can be specified as either a number or a string.
A number (0 or 1) is interpreted as a disk unit on the local system;
a string specifies a host name and, optionally, a disk unit on the
remote system.
Disk unit 0 is the main disk; this is the default in most cases.
On systems with dual-disk configurations the second disk is considered unit 1.

@defun si:copy-disk-partition from-unit from-part to-unit to-part &optional &key (pages-at-a-time (min page-rqb-size 85)) (verbose t) (starting-hundred 0) whole-thing-p delay

Copy partition FROM-PART on FROM-UNIT to partition TO-PART on TO-UNIT.

Here are some examples:

@lisp
;Copy on main disk
(si:copy-disk-partition 0 'lod1 0 'lod3)
;Copy to 2nd disk
(si:copy-disk-partition 0 'lod1 1 'sav1)
;Copy to OTHER-HOST
(si:copy-disk-partition 0 'lod1 "other-host" 'lod3)
@end(lisp)
@end(defun)

@defun print-disk-label &optional (unit nil) (stream standard-output)

Display the disk label for UNIT, outputting to STREAM.

For example:

@lisp
(print-disk-label)            ;print local main disk
(print-disk-label 1)          ;print local auxiliary disk
(print-disk-label "lama")     ;print LAMA's main disk
(print-disk-label "lamc 1")   ;print LAMC's auxiliary disk
@end(lisp)

@end(defun)

















@c end gen-apps