Text preview for : FTP_Functional_Specification_Nov77.pdf part of xerox FTP Functional Specification Nov77 xerox sdd memos_1977 FTP_Functional_Specification_Nov77.pdf



Back to : FTP_Functional_Specificat | Home

This document is for Xerox internal use only.




Ftp Functional Specification

Version 2.0
November, 1977




XEr.JX SDD ARCHIVES
II have read and understoo Pages
----To - - - - , '\
Beviewer
f
------- --------
D~te

of Pages _ _,Ref115Df>3t,'8


,




XEROX
SYSTEMS DEVELOPMENT DIVISION
3408 Hillview Avenue / Palo Alto / California 94304




This document is for Xerox internal use only.
ftp FUIICtioll3 I Specification 2


Table of Contents


Preface 4

1. Introduction 5
1.1 Purpose 5
1.2 Program structure 5
1.3 File naming conventions 5
1.4 Exception handling 6
FTPError

2. Ftp 8
2.1 Program management primitives 8
FTPlnitialize, FTPFinalize

3. Ftp User 8
3.1 Program management primitives 8
FTPCreateUser, FTPDestroyUser
3.2 Connection management primitives 9
FTPOpenConnection, FTPRenewConnection, FTPCloseConnection
3.3 File access and specification primitives 10
FTPSetCredentials, FTPSetFilenameDefaults
3.4 File enumeration primitives 11
FTPEnumerateFiles
3.5 File transfer primitives 12
FTPStoreFile. FTPRetrieveFile
3.6 File manipulation primitives 14
FTPDeleteFile. FTPRenameFile

4. Ftp Listener 14
4.1 Program management primitives 14
FTPCreateListener, FTPDestroyListener



References 16

Appendix A: Additional Primitives 17
A.l Introduction 17
A.2 Infrequently used connection management primitives 17
FTPSetConlactSocket, FTPEnableTrace, FTPDisableTrace
A.3 Dump file primitives 17
FTPlnventoryDumpFile, FTPBeginDumpFile, FTPEndDumpFile

Appendix B: Mail Primitives 20
8.1 Introduction 20
8.2 Delivery primitives 20
FTPBeginDeliveryOfMessage, FTPSendBlockOfMessage, FTPEndDeliveryOfMessage
8.3 Retrieval primitives 21
FTPBeginRetrievalOfMessages, FTPldentifyNextMessage. FTPRelrieveBlockOfMessage,
FTPEndRetrievalOfMessages
Ftp Functional Specification 3

Appendix C: Client Listener Appendages 24
C.l Description of the option 24
C.2 Exercising the option 24
C.3 General characteristics 25
CA Server encapsulation appendages 25
NoteServerCrealion, NoteServerError, NoteServerDestruction

Appendix 0: Client File Primitives 27
0.1 Description of the option 27
0.2 Exercising the option 27
0.3 General characteristics 28
0.4 Filename manipulation primitives 29
DecomposeFilename, ComposeFilename
0.5 Access control primitives 30
InspectCredentials
0.6 File enumeration primitives 30
EnumerateFiles
0.7 File transfer primitives 31
OpenFile, ReadFile, WriteFile, CloseFile
0.8 File manipulation primitives 32
DeleteFile, RenameFile

Appendix E: Sample Configuration and Program 33
E.l I ntrod uction 33
E.2 Sample configuration 33
E.3 Sample program 33

Appendix F: Production Configurations and File Locations 35
Ftp Functional Specification 4


Preface
This document details the procedural interface to the recently completed Mesa Ftp Package,
Ftp 2.0, an outgrowth of earlier work by Smokey Wallace and Hal Murray. This document
obsoletes the author's two previous design documents, [1, 2]. The code described herein is
currently running and available. The reader is referred to Appendices E and F for file
locations and other details concerning its use. Comments, bug reports, suggestions for
change or addition, and cries for help should be addressed to the implementor, Jim White
(Wh ite@Maxc).
Ftp Functional Specification 5


1. Introduction
1.1. I~urpose


The File Transfer Package (Ftp) is one means of several for accessing and manipulating
remote files via the network. Ftp provides primitives for storing. retrieving, deleting,
renaming, and enumerating remote files. Ftp trades in whole files, in contrast to a page-
level access package, for example, which trades in smaller units (i.e. pages of files). or
CopyDisk, which trades in larger ones (i.e. an entire disk).

Ftp provides an interface to Alto, Maxc. IFS, and Juniper file systems, and any others that
implement the long-standing File Transfer Protocol (FrP) described in [3].

In addition to providing file-related services, Ftp 2.0 provides primitives for delivering mail
to and retrieving mail from remote mailboxes. Ftp is thus also a means for accessing
mailboxes on Maxc or any other host that implements the recently specified Mail Transfer
Protocol (MTP) described in [4].

1.2. I~rogram Structure

Every Ftp dialogue involves two parties, designated user and server, which are linked by a
network connection. In point of fact, file and mail operations are implemented by separate servers and
hence a dialogue in which operations of both types are carried out actually involves three parties: the local user.
the remote file server, and the remote mail server. The Ftp implementation, however. disguises the distinction
between the two servers and presents to the client the illusion of a single server capable of handling both types
of requests. At one end, a client program initiates and controls the dialogue by calling
procedures provided by a local Ftp User. At the other end, a passive Ftp Server responds
and replies to requests it receives from the distant Ftp User. Several Servers can coexist
within a single host and hence several independent file transfers can proceed concurrently.
Ftp Servers are created by a single, resident Ftp Listener in response to connection requests
from distant Ftp Users. Each Server is spawned as a separate process and competes for
system resources with other local processes under the control of a scheduler. When the
distant Ftp User terminates its dialogue with the local Ftp Server, the Server destroys itself.

The remainder of this document describes the client's interface to the Ftp User and Listener;
the Ftp Server, having no external interface, is not discussed further. In the procedure
descriptions presented later in this document, the terms local and remote distinguish the
host containing the described procedure from the distant host to which that host is
connected, respectively.

1.3. File Naming Conventions

Ftp provides the client with two separate mechanisms for designating remote files: absolute
filenames, which must conform to the file naming conventions of the remote file system;
and virtual filenames, having a host-independent structure, which are mapped into absolute
filenames by the remote file system. The purpose of this two-fold scheme is, on the one
hand, to permit the exact specification of remote filenames by human users familiar with
remote file naming conventions and, on the other, to permit the mechanical generation of
Ftp Functional Specification 6


filenames by clients ignorant of such conventions.

Absolute filenames are STRINGs. Any internal structure an absolute filename might possess
is indicated by delimiters embedded in the STRING. Virtual filenames, on the other hand,
have four components--device, directory, name, and version--each of which is a STRINO:

VirtualFilename: TYPI~ =
POINTER TO VirtualFilenameObject;
VirtualFilenameObject: TYPE =
RECORO [device, directory, name, version: STRING];

As part of its mapping operation, the remote file system combines these components to
form a legal absolute filename (using appropriate field delimiters where necessary). The Maxc
file system maps the device, directory, and version components of a virtual filename into the corresponding
Tenex filename fields and maps the name component into the name and extension fields. The Alto file system
ignores the device and directory components, maps the name component into the name and extension fields, and
maps the version component into the corresponding Alto filename field. IFS ignores the device component,
maps the directory component into the directory and subdirectory fields, and maps the name and version
components into the corresponding IFS filename fields.

The client may use either or both of the file naming schemes outlined above. or a
combination of the two. Whenever the local Ftp User communicates a remote filename to
the remote Ftp Server. it sends both an absolute filename and a virtual filename. The
absolute filename is that supplied by the client as a parameter to the Ftp User procedure
that initiates the exchange. The virtual filename is that supplied by the client in a previous
call to the FTPSetFilenameDefaults procedure described in Section 3.3. If all components of
the virtual filename are NIL (e.g. before FTPSetFilenameDefaults is called), the remote file is
completely specified by the absolute filename. If the absolute filename is NIL, the remote
file is completely specified by the virtual filename. If both the absolute and virtual
filenames are non-NIL, the remote Ftp Server has the option of lIsing the virtual filename to
default unspecified fields in the absolute filename.

The term file group designator denotes a filename, either absolute or virtual or both, that
names a group of files, rather than a single file. File group designators often contain special
characters that indicate wild or unspecified portions of the filename. The Maxc file system
recognizes as a legitimate value for the device, directory, name, version, and/or extension field, the special
character, asterisk ('*), denoting an arbitrary field value. The Alto file system recognizes the two special
characters, asterisk COo), denoting zero or more arbitrary characters, and pound sign ('#), denoting exactly one
arbitrary character. IFS recogniZes the special character, asterisk ('*), denoting zero or more arbitrary characters.

1.4. Exception Handling

Exceptional conditions encountered by Ftp are reported to the client by means of a single
ERROR signal. FTPError; its one parameter, an enumerated type, pinpoints the error.
Exceptional conditions reported in this way include not only those explicitly detected by Ftp
but also those that originate as signals within the Pup package, as well as some that originate
as signals within the Alto file package. Ftp restores itself to a consistent state after every error (in
response to the UNWIND signal). Therefore, for example, if the client's connection to a remote Ftp Server
breaks (e.g. because the remote host breaks), the client can close the connection and open a new one (in this
case, to another host) without first having to destroy and recreate the local Ftp User.
Ftp Functional Specification 7

The errors that Ftp may report to the client are summarized below. The most prominent of
the errors generated by particular procedures are listed (using a notation something like that
used for Mesa declarations) with the descriptions of those procedures later in this document.
The errors classed below as implementation or unidentified errors can be generated (at least
in principle) by nearly every procedure. Because they are so pervasive in principle and rare
in practice, such errors are excluded from the descriptions of the individual procedures to
which they nevertheless apply:

FTPError: F.RROR [ftpError: FtpError];

FtpError: TYI)F. ={

-- credential errors
missingCredentials, noSuchPrimaryUser, noSuchSecondaryUser,
incorrectPrimaryPassword, incorrectSecondaryPassword, requestedAccessDenied,

-- communication errors
noSuchHost, connectionTimedOut, connectionRejected, connectionClosed,
noRouteToNetwork,

-- file errors
iIIegalFilename, noSuchFile, noRoomForFile, fileDataError, unexpectedEOF,

-- dump errors
errorBlocklnDumpFile. unrecognizedBlocklnDumpFile, blocklnDumpFileTooLong,
dumpFileCheckSumlnError,

-- mail errors
noValidRecipients, noSuchMailbox, noSuchForwardingHost, noSuchDmsName,
maiJboxlsBusy,

-- client state errors
duplicateListener, filesModuleNotLoaded, mailModuleNotLoaded, missingConnection,
duplicateConnection, busyConnection, unopenedForFiles, unopenedForMail,
enumeratedFileProcessedOutOfSequence,

-- implementation errors
protocolVersionMismatch, notlmplementedLocally, notlmplementedRemotely,
unrecognizedMarkByte, unexpectedMark, inappropriateMarkByte, stringTooLong,
missingPropertyList, malformedPropertyList, unrecognizedProperty,
duplicateProperty, iIIegalBooleanProperty, iIIegalExceptionlndex,
duplicateMailboxException.illegaIExceptionErrorCode. missingMessageLength,
inappropriateCommandReported, malformedPropertyListReported,
illegalFileCharacteristicReported, pupGlitch,
Ftp Functional Specification 8

-- unidentified errors
unidentifiedTransientError, unidentifiedPermanentError. unidentifiedError};


2. Ftp
2.1. I)rogram Management Primitives

Ftp provides two procedures for controlling its overall operation. The first, FTPlnitia)ize.
initializes Ftp for operation by preparing the necessary internal data structures and
initializing the Pup Package (via a call to PupDefs.PupPackageMake). The client must call
this procedure before calling any other Ftp procedures. Redundant calls simply increment
a use count:

FTPlnitialize: PROCEOURE;


The second procedure, FTPFinalize, finalizes Ftp's operation by finalizing the Pup Package
(via a call to PupDefs.PupPackageDestroy) and disposing of Ftp's internal data structures.
Before calling this procedure, the client should destroy any Users and Listener that may
exist. The client must call no other Ftp procedures (except FTPlnitialize) once this
procedure has been invoked. Calls corresponding to redundant calls to FTPlnitialize simply
decrement the use count:

FTPFinalize: PROCEOURE;



3. Ftp User
3.1. Program Management Primitives

Ftp provides two procedures for controlling Ftp Users, several of which can coexist within a
single host. The first procedure, FTPCreateUser, creates a new Ftp User:

FTPCreateUser: PROClmu RIi: [clientFilePrimitives: ClientFilePrimitives, clientData:
UNSPECIFIF.O] RETURNS [ftpuser: FTPUser];

=
ClientFilePrimitives: TYPE POINTER TO ClientFilePrimitivesObject;
ClientFiJePrimitivesObject: TYPE =R(;;CORf) [