Heading:

Pup File Transfer Protocol Specification—5th edition

Page Numbers: Yes X: 527 Y: 10.5"

Copyright Xerox Corporation 1982, 1983

XEROX Palo Alto Research Center

September 29, 1983; 7th edition

To:Communication Protocols

From:John Shoch and Ed Taft

Subject:Pup File Transfer Protocol Specification—5th edition

File:<Pup>FTPSpec.press

This document represents an attempt to define a simple protocol for the movement of files among the many different computers currently connected to the PARC communications networks.

This document provides a general explanation and overview of the full range of the File Transfer Protocol, as well as a specification for the protocol. Specific details of the actual FTP implemented for Maxc or the Alto may be found in the appropriate documentation.

All previous versions of this memo are now obsolete. Material in a small font concerns facilities whose design is incomplete and which have never been implemented.

The development and refinement of the protocol have benefited greatly from comments and ideas originally provided by Bob Metcalfe, Ed Taft, David Boggs, Bill Duvall, Bob Sproull, and others; and supplemented by later experience in Mesa by Smokey Wallace, Jim White, and Hal Murray.

1. Companion documents

Background information on Pup and BSP (on-line versions are available on many public file servers):

—Bob Metcalfe and Ed Taft, ‘‘Pup Specification’’, file <Pup>PupSpec.press.

—D. Boggs, J. Shoch, E. Taft, and R. Metcalfe, ‘‘Pup: an Internetwork Architecture’’, IEEE Transactions on Communications, COM-28 4, April 1980, file <Pup>PupPaper.press.

Detailed description of particular FTP implementations:

—Ed Taft, ‘‘PUPFTP—Maxc Pup File Transfer Program’’, file <Pup>PUPFTP.press.

—Dave Boggs and Ed Taft, ‘‘BCPL FTP Package’’, in the Alto Subsystems manual or file <AltoDocs>FTPPackage.tty.

—Jim White and Hal Murray, ‘‘Mesa FTP Functional Specification’’, file <Mesa>Doc>FTP.press.

A related protocol:

—Ed Taft, ‘‘Pup Mail Transfer Protocol’’, file <Pup>MailTransfer.press.

2. Assumptions and basic principles

If you are reading this document, it is assumed that you are familiar with the contents of ‘‘Pup Specification’’ by Bob Metcalfe and Ed Taft.

We are talking about files transmitted from one logical process to another logical process, and not necessarily from one file system to another file system. It is possible, for example, to generate a file ‘on the fly’ with one process and then have it consumed by another process, without it ever residing on a physical disk.

We are not discussing particular programs which might chose to use the File Transfer Protocol, nor are we concerned here with implementation questions. Programs such as a File Transfer Program, a BCPL remote-stream facility, mail systems, or an automatic disk update program can make use of the File Transfer Protocol; but that is a matter of convention.

It should be possible to construct a simple file transfer protocol as a thin veneer placed over the Byte Stream Protocol (BSP). While the mix of machines and networks is very heterogeneous, these differences are subsumed by the definition of Pups and the Byte Stream Protocol. The BSP is designed to provide ‘‘...error- and flow-controlled byte streams between cooperating processes.’’ Thus, the only parts of the ‘outside world’ which the FTP will ever see—or use—are the facilities provided by the BSP.

The File Transfer Protocol only comes into play after a BSP stream has been established. That is, actual programs will use the Rendevous and Termination Protocol (or some other means) to establish a connection between two ports. The FTP does not define this mechanism.

One BSP connection is sufficient for transmitting a file. Unlike the Arpanet protocol, both command information and data pass through the same bi-directional BSP stream.

The two parties to a file transfer are named the user and the server: the user initiates actions and the server responds. Actual files, however, may move in either direction: a user process may try to store a file upon the server system, or try to retrieve a file from the server.

The File Transfer Protocol generally prescribes the behavior of the server process; the user process is merely one that presents requests to the server in accordance with the server’s described format, and follows the command/response sequence.

3. On the nature of files

It is common to say that a file is merely a collection of bits, but that is, of course, over simplified. A file is a collection of bits viewed in a particular way within a specified context. Much of the work involved in transferring files from one machine to another over some number of different networks is the result of attempting to resolve conflicting contextual representations of a file: 7, 8, or 36 bit, ASCII or binary, naming conventions, CR or EOL, ad infinitum.

In addition, such contextual differences make it hard to add a new machine or different network to a multi-network system without redoing the resolution matrix; and it is also important to avoid reformatting data to conform to local conventions at every step through a collection of networks.

To simplify the situation, this contextual information may be viewed as an adjunct part of a file, which might migrate with the file, as necessary. This information, or file property list, may be used to describe different kinds of ‘‘files’’, including those:

—residing on a physical disk;

—in transit, on a BSP connection;

—being sought by a particular user; or,

—being generated by a server.

The properties of a file are, in general, contained either explicitly or implicitly within an operating system on a particular machine. An actual property list may contain information provided by the user, from the file system, or from specialized information about the environment. Consider a typical scenario: moving a text file from a file server to an Alto:

1.The server can generate a property list including the file name, date last written, author, protection, byte size, etc.

2.This information, along with the file, is transmitted to the Alto.

3.The Alto process does its best to map the property list into its environment: the file name is used, perhaps without the version number; protection information is discarded; the end of line indication may be changed, if necessary; etc.

There is no guarantee that a receiving process will be able to properly encode all properties.

A file could, however, attempt to preserve some of its original context by including as one of its properties an extraordinary request to maintain the property list. For example, an Alto might be willing to save a property list on an auxiliary file, and use some of that information to regenerate a property list when the file is returned to the server.

A property list may be generated by any process which desires to transmit a file. Similarly, any process receiving a file and its property list can use that information to interpret the contents of the file. (Remember that all data moved under the BSP are sent as 8-bit bytes, and the property list will indicate any unusual packing of data.)

The property list might also be used to merely provide information about one or more files (where they are, when last written, etc.) In addition, a file property list can provide a partial description for a file which you are trying to find, or which you would like to create.

This notion of a file property list is central to the file transfer protocol.

4. Summary of the File Transfer Protocol

There are three major elements defined in the protocol: syntax of a property list, typical property/value pairs, and command sequences. A general description of each is provided here as an introduction; the completely specified details can be found in subsequent sections.

4.1. Syntax of a file property list

A file property list consists of a string of ASCII characters, beginning with a left parenthesis and ending with a matching right parenthesis. Within that list, each property is represented similarly as a parenthesized list. For example:

((Server-Filename TESTFILE.7)(Byte-Size 36))

4.2. Typical properties and their values

One can reasonably expect to find properties such as these in a file property list:

Server-Filename<SUBSYS>PUPFTP.SAV;3
<Alto>Bravo.dm
Bravo.dm
My.Funny.But.Legal.Alto.Name

Byte-Size7, 8, 36

TypeText, Binary

AuthorPanchoVilla, System

Date-Written23-Jan-76 11:30:22 PST

4.3. Commands and command/response sequences

In every FTP connection, one party is the User and the other party is the Server: the User initiates commands, while the Server provides replies. In general, there will be some form of reply generated in answer to every command.

Every transaction in the FTP consists of a BSP Mark Byte, followed by a piece of data, and terminated at the next BSP Mark Byte encountered. The data thus enclosed might be one or more file property lists, a text string, or a file. A command might simply be terminated by the arrival of the next Mark Byte command, or by an End-of-Command Mark Byte (essentially a no-op). All of the Mark Byte codes used in the FTP are listed at the end of this document.

For example, a simple retrieval of a file would include:

1.User sends the Server a command requesting the retrieval, with a file property list describing the desired file.

2.Server responds with an appropriate message.

3.If the Server said Yes, then the file is placed into the byte stream.

If a process replies with a No, the first byte of the following data is a numeric code for possible machine processing, and the remaining bytes are a comment for the user. (The correct functioning of the protocol, however, does not depend upon the many possible numeric codes; the simple Yes and No messages are sufficient for using the protocol.)

Once again, particular implementations of the FTP may not support all possible commands. The protocol provides a standard response (the No message with a specific code) by which a server may indicate that a requested command is not implemented. This must be the server’s sole response to an unimplemented command; it must not take more drastic action such as breaking the connection.

5. Details of the File Transfer Protocol

This section specifies the minimum conventions required to use the FTP, as well as many optional features which have been found useful. Any FTP server intended for general use is expected to respond properly to the minimum set of commands; any of the optional facilities included will increase the utility of the server. Any implementation of a user process is free to select those features deemed useful, but the minimal set should seem evident from the discussion below.

5.1. Syntax of a file property list

A file property list consists of a string of ASCII characters, beginning with a left parenthesis and ending with a matching right parenthesis. Within that list, each property is represented similarly as a parenthesized list. For example:

((Server-Filename TESTFILE.7)(Byte-Size 36))

This scheme has the advantage of being human readable, although it will require some form of scanner or interpreter. Nevertheless, this is a rigid format, with minimum flexibility in form; FTP is a machine-to-machine protocol, not a programming language.

The first item in each property (delimited by a left parenthesis and a space) is the property name, taken from a fixed but extensible set. Upper- and lower-case letters are considered equivalent in the property name. The text between the first space and the right parenthesis is the property value. All characters in the property value are taken literally, except in accordance with the quoting convention described below.

All spaces are significant, and multiple spaces may not be arbitrarily included. There should be no space between the two leading parentheses, for example, and a single space separates a property name from the property value. Other spaces in a property value will become part of that value, so that the following example will work properly:

((Server-Filename xxxxx)(Read-Date 23-Jan-76 11:30:22 PST))

A single apostrophe is used as the quote character in a property value, and should be used before a parenthesis or a desired apostrophe:

Don’t(!)Goof ==> (PropertyName Don’’t’(!’)Goof)

FTP implementations are required to ignore properties whose names they don’t know. This enables extensions to be introduced to the set of defined properties without invalidating existing programs.

FTP implementations are expected to send as complete a set of properties as is possible in every message. However, the FTP user may instruct the server to send only a specific subset of the file properties, using the Desired-Property property described below.

5.2. Defined properties and their values

5.2.1. Mandatory properties. An FTP server must be able to respond to these elements in a file property list. These properties may or may not be required in all property lists; this is discussed in the individual descriptions.

(Server-Filename filename)

In commands from user to server (such as Store, Retrieve, and Enumerate), specifies the name of the file to be manipulated. This filename must conform to the conventions of the server system (unlike the more machine-independent name convention to be described as options below). This need not be an exact filename; it may be a pattern (possibly matching multiple filenames) or contain defaulted fields—whatever is supported by the server’s file system.

In responses from server to user, specifies the exact, complete name of the file presently under consideration.

(Type Text|Binary)

Specifies the type of data to be transferred (no default). Text data is 7-bit ASCII (right-justified in 8-bit bytes) conforming to the End-of-Line-Convention (see below). Binary data consists of bytes conforming to the Byte-Size property (see below). If the type is not specified by the user in a Retrieve command (the usual case), the server should determine the appropriate type based on local information about the file being retrieved, if possible.

(End-of-Line-Convention CR|CRLF|Transparent)

Specifies the representation for end-of-line in files transmitted as type Text (default is CR). This specification is meaningless for Binary files and is ignored. Both server and user are expected to convert between local end-of-line conventions and the agreed-upon network convention. (In general, the FTP server never independently decides on an end-of-line convention but rather always heeds the convention specified by the FTP user.) Transparent means that the server is not to perform a conversion even if local and network conventions differ. All implementations are required to support end-of-line conventions CR and Transparent; implementing CRLF is optional.

(Byte-Size decimal-number)

Specifies the logical byte size of files of type Binary (meaningless and ignored if the type is Text). There is no default. Binary data consists of bytes of the specified number of bits, right-justified in 8-bit bytes or multiples thereof. (While there is no inherent limit to the byte size, some implementations may not accept byte sizes larger than the word size of the machine on which they are running.) During a Store, the byte size must be specified by the FTP user, and it determines the byte size of the file written at the server end. During a Retrieve, the user may leave the byte size unspecified; in this case, the server chooses a suitable byte size based on local information (if possible). If the user requests retrieval of a file using a byte size different from that which the server believes is appropriate for the file, an error results.

(Device device-name)
(Directory directory-name)
(Name-Body name-body)
(Version version-string)

Specifies the separate components of a filename in a manner intended to facilitate transfer of files between hosts whose file systems lack one or more of these concepts or have different conventions for punctuating them. The values of these properties should not include the surrounding punctuation characters.

A filename property sent from user to server may be given either as a Server-Filename or as separate components. If it is supplied as separate components, then the server is expected, where possible, to default missing components and to map locally illegal characters into legal ones. If, however, it is specified as a Server-Filename, then it is expected to conform exactly to the server’s file naming conventions (including avoiding or quoting illegal characters as required). If both a Server-Filename and separate components are supplied, the individual components may be used by the server to default unspecified fields in the Server-Filename. (In effect, this might allow a user program to specify a default directory, unless overruled by the human user.)

A filename property sent from server to user is required to be specified as separate components, though optionally it may also be specified by a Server-Filename property (generally just for information purposes). This allows a user who sent an incomplete specification (e.g., a pattern) to then interpret the complete specification that comes back.

The purpose of having two filename conventions is on the one hand to permit mechanical processing of filenames by processes ignorant of other than local naming conventions, and on the other hand to permit exact specification of foreign filenames by (human) users who are cognizant of foreign naming conventions.

5.2.2. Optional properties. There are other properties which are considered, in general, to be optional; but all FTP servers are encouraged to implement those which may be appropriate. A server may consider some of these to be mandatory components of a file property list (e.g., User-Name, User-Password), although other servers may not utilize them.

(Size decimal-number)

Specifies the number of bytes in the file. (These bytes are of the size specified by the Byte-Size property.) The value is not required to be correct. The recipient of this property may treat it as a hint (e.g., to control preallocation of file space); but the true length of the file is defined solely by the number of bytes actually transferred when the file is stored or retrieved.

(User-Name user-name)

Specifies a legal user name on the server system, for the purpose of access checking and accounting, if required.

(User-Password password)

Supplies the user password, if required for logging in under the specified User-Name.

(User-Account account-designator)

Specifies the user ‘‘account’’ (in the Tenex sense), if required. If this is not specified, the user is logged in under his default account (assuming there is one).

(Connect-Name directory-name)

Specifies that the user is to be ‘‘connected’’ (in the Tenex sense) to the specified directory, i.e., to be given temporary owner-like access to that directory. The default connected directory is the user’s login directory.

(Connect-Password password)

Supplies the password for connecting to a directory, if required.

(Creation-Date date-and-time)
(Write-Date date-and-time)
(Read-Date date-and-time)

Supplies the respective date property of the file. The syntax of date-and-time is ‘‘dd-mmm-yy hh:mm:ss zzz’’, where zzz is a standard North American time zone (e.g., PST, EDT), GMT, or a sign followed by a numeric time zone (e.g., +3 or +3:00, meaning 3 hours west of Greenwich). Inclusion of the zone is mandatory for all new implementations; however, for compatibility with older programs, all implementations must be able to consume date properties with or without time zones.

The precise semantics of the date properties are file system specific; however, adherence to the ‘‘Alto File Date Standard’’ (<AltoDocs>FileDates.press) is strongly encouraged. In particular, the Creation-Date is defined to be the date on which the information in a file was created; when a file’s contents are copied without change, its creation date should be copied with it.

(Author user-name)

Supplies the name (e.g., Grapevine registered name) of the user who created the file.

(Checksum decimal-number)

Supplies an optional checksum over the file. The checksum is computed over the file’s data in the form in which it flows over the BSP stream, but treating it as a sequence of 16-bit words (with the left byte of each word first, and with the leftover byte assumed to be zero if the file consists of an odd number of bytes). It is a 16-bit number computed by applying the Pup checksum algorithm over all words of the file and then adding 1 (modulo 216). This means the ‘‘no checksum’’ value is zero rather than 177777B. Sending a value of zero is equivalent to not sending a Checksum property at all.

The protocol does not require the recipient to check the checksum, nor does it specify what action to take if the checksum is found to be incorrect. In general, producers and consumers of files will (optionally) generate and check Checksum properties. File servers, on the other hand, will simply store the property along with the file and give it back when the file is retrieved, and will neither generate nor check Checksum properties.

(Desired-Property property-name)

In a command from user to server, requests that the server supply the specified property in all file property lists it generates in response to that command. (That is, property-name should be one of Author, Byte-Size, Checksum, Creation-Date, Device, Directory, Name-body, Read-Date, Server-Filename, Size, Type, Version, or Write-Date.)

If no Desired-Property property is present in the property list of a file-related command sent from user to server, the server must send all known properties of each file enumerated. But if one or more Desired-Property properties are present, the server may send only the specified properties and omit the rest. The server may choose to ignore Desired-Property requests altogether and instead send all known properties; it may also ignore Desired-Property requests for properties it cannot send or doesn’t know about.

5.3. Defined commands

5.3.1. Basic FTP command messages. Commands (and responses) are given by means of Mark bytes of specified types, followed (in some cases) by a single data byte containing a machine-readable code, followed (in most cases) by a property list or a human-readable string. The command terminates at the next Mark.

In the descriptions below, the mnemonic for the Mark is given in square brackets, followed by code if a machine-readable code is used in that command, followed by a description of the data that follows. Mark types are given in decimal. Correct command/reply sequences will be given in the next section.

[Retrieve] property-list[Mark type 1]

Issued by the FTP user, requests that the server send to the user the file(s) described by the supplied property list.

[Store] property-list[Mark type 2]

Issued by the FTP user, requests that the server prepare to accept the file described by the property list. This command is obsolete, having been supplanted by [New-Store]; however, for compatibility with older software, FTP user implementations should be prepared for [New-Store] to fail and to retry the operation using [Store].

[New-Store] property-list[Mark type 9]

Issued by the FTP user, requests that the server prepare to accept the file described by the property list. (The forms of the [Store] and [New-Store] commands are the same; the distinction lies in the form of the server’s response.)

[Yes] code human-readable-string[Mark type 3]

A positive acknowledgment that some previous action has completed successfully. This may be generated by either the server or the user as appropriate (see below). The code may supply additional machine-readable information of possible interest to the receiver, or it may be zero; however, the meaning of a Yes in terms of the FTP command/response sequence is determined entirely by context and not by the code.

[No] code human-readable-string[Mark type 4]

A negative acknowledgment for some previous action. This may be generated by either the server or the user as appropriate (see below). The code may supply additional machine-readable information of possible interest to the receiver, or it may be zero; however, the meaning of a No in terms of the FTP command/response sequence is determined entirely by context and not by the code.

[Here-is-Property-List] property-list[Mark type 11]

Supplies the file property list in the server-to-user direction (in Retrieve, New-Store, Enumerate, and New-Enumerate commands). This command is not used in the user-to-server direction since the property list is specified directly in the commands used to initiate operations.

[Here-is-File] file-data[Mark type 5]

Effects the actual file transfer in either direction. The file-data physically consists of a stream of 8-bit bytes, but its logical interpretation is dependent on the Type and Byte-Size properties currently in effect.

[Version] code human-readable-string[Mark type 8]

Identifies the sender’s protocol version. Code denotes the protocol version, which is currently 1, and human-readable-string is arbitrary identifying text. The FTP user should issue this command immediately upon opening a connection, and the server should respond with a Version reply. It is the responsibility of the user to check for compatible protocol versions.

[Comment] human-readable-string[Mark type 7]

Used to supply commentary, indicate non-fatal errors, etc. It is a no-op with respect to protocol interactions and need not be acknowledged. The FTP user program should probably display for the human user any such comments it receives from the server.

[End-of-Command][Mark type 6]

This command (hereafter abbreviated EOC) informs the receiver that the sender has generated a complete command or command sequence and now cannot proceed until some response is returned. In other words, EOC is used to ‘‘give control’’ to the other party. In general, each command issued by the user should be followed by EOC, and the end of the server’s response to a command-EOC sequence should in turn be marked by EOC. There is no data following the EOC: it is followed immediately in the data stream (though perhaps after an arbitrary interval of time) by another Mark.

5.3.2. Optional FTP command messages

[Enumerate] property-list[Mark type 10]

Issued by the FTP user, requests the server to generate a complete property list for each of the files denoted by property-list. If the file name submitted is interpreted by the server to denote multiple files, the server may generate multiple property lists in response (each preceded by a [Here-is-Property-List] Mark byte). This command is obsolete, having been supplanted by [New-Enumerate]; however, for compatibility with older software, FTP user implementations should be prepared for [New-Enumerate] to fail and to retry the operation using [Enumerate].

[New-Enumerate] property-list[Mark type 12]

Issued by the FTP user, requests the server to generate a complete property list for each of the files denoted by property-list. If the file name submitted is interpreted by the server to denote multiple files, the server may generate multiple property lists in response (concatenated together in a single [Here-is-Property-List] message). (The forms of the [Enumerate] and [New-Enumerate] commands are the same; the distinction lies in the form of the server’s response.)

[Delete] property-list[Mark type 14]

Issued by the FTP user, requests the server to delete the specified file(s).

[Rename] old-property-list new-property-list[Mark type 15]

Issued by the FTP user, asking the server to rename the file specified in the first property list, to match the name (and perhaps other properties) specified in the second.

5.4. Command-Response sequences

The complete user-server protocols for each command are documented in the flowcharts attached to this specification. Commands from user to server are prefixed by ‘‘U:’’; from server to user by ‘‘S:’’. Commentary is included in italics.

These flowcharts describe only the protocols themselves, and do not show any local actions that the two parties must take. Such actions are necessarily file system or application dependent.

Each sequence begins with the FTP user in control, and ends with the user again in control. A party sends messages only when it is in control. Sending [EOC] switches control to the other party. Where a branch occurs in the flowchart, the party then in control may follow either branch and send the message shown at the end of that branch. The normal flow of control is straight down from the top (and looping back up at the left in those protocols that contain loops); errors and other exceptions branch off to the right.

At any point in the protocol, the party then in control may insert a [Comment] message immediately preceding its next command; such a message does not alter the flow of control. Apart from Comments, an occurrence of a command-response sequence other than those shown in the flowcharts is a violation of the protocol and is grounds for aborting the connection.

The command at the beginning of every sequence includes a property list designating some file (or potential file) on the server. The file may be described by Server-Filename, Device, Directory, Name-Body, and Version properties in any combination permitted by the server (as was discussed in section 5.2.1). The property list must include not only filename information but also any credentials required to gain access to the server (User-Name, User-Password, etc.), and also any additional properties intended to modify the server’s subsequent actions (Desired-Property).

5.4.1. Retrieve and Delete. These two commands have similar protocols. Each is initiated with a property list designating one or more existing files on the server. If no such file exists, or the command is otherwise unacceptable (e.g., invalid User-Name and User-Password), then the server rejects the entire command with a [No] and the command terminates with the user again in control.

Otherwise, the remainder of the protocol is executed for each file matching the initial request. The main loop is not left until all such files have been enumerated; any error that occurs applies only to an individual file.

The server returns a [Here-is-Property-List] message describing as completely as possible the specific file under consideration. Unless otherwise specified by the user (by Desired-Property properties), the Server-Filename, Name-Body, Type, and (if Type is Binary) Byte-Size properties are mandatory, as are Directory and Version if the server file system has such things. The server is strongly encouraged to include all other known file properties that are representable as FTP properties.

At this point, the FTP user process examines the server’s property list (possibly interacting with a human user), and then commands the server either to carry out the operation (Retrieve or Delete) or to skip to the next file.

In the case of Retrieve, the server now sends the contents of the file, followed by a [Yes] message to mark the end of data. There are two possible points of failure. If the server cannot begin transmission (e.g., because the file is read-protected against the user), then it sends a [No] message in response to the user’s [Yes]. If the server detects a failure in mid-transmission, it sends a [No] following the (possibly truncated) file data. (A user-detected transmission failure results only in user-local recovery actions and requires no provisions in the protocol.)

In any event, the server is now in control (since its last [Yes] or [No] was not terminated by [EOC]), and proceeds either to send a [Here-is-Property-List] message for the next file or to send an [EOC] to terminate the Retrieve protocol.

5.4.2. Store and New-Store. These commands are initiated with a property list designating some file (existing or new) into which the user desires to store data. This property list should be as complete as possible; in particular, the Type and (if Type is Binary) Byte-Size properties are mandatory. The user is strongly encouraged to include all other known file properties that are representable as FTP properties.

If the file cannot be stored into (e.g., write protected, no disk space available, etc.), or the command is otherwise unacceptable (e.g., invalid User-Name and User-Password), then the server rejects the entire command with a [No] and the command terminates with the user again in control.

In the case of [New-Store], the server now returns as complete a property list as is possible before the file data has actually been transferred. Unless otherwise specified by the user (by Desired-Property properties), this must include the Server-Filename and all filename properties implemented by the server. The user may now examine this property list and choose not to store the file after all.

In the normal situation, the user now sends the contents of the file, followed by a [Yes] message to mark the end of data. If the file is stored successfully, the server responds with a [Yes], and the Store or New-Store protocol terminates.

There are two possible points of failure. If the user detects a failure in mid-transmission, it sends a [No] following the (possibly truncated) file data. If the server detects a failure in mid-transmission, it consumes and discards the remainder of the file data and then responds with [No] to indicate failure.

5.4.3. Enumerate and New-Enumerate. These commands are initiated with a property list designating one or more existing files on the server. If no such file exists, or the command is otherwise unacceptable (e.g., invalid User-Name and User-Password), then the server rejects the entire command with a [No] and the command terminates with the user again in control.

Otherwise, the server sends a property list for each file matching the initial request. In [Enumerate], each property list is sent as a separate [Here-is-Property-List] message, whereas in [New-Enumerate] all the property lists are concatenated and sent as a single [Here-is-Property-List] message.

Unless otherwise specified by the user (by Desired-Property properties), these property lists should be as complete as possible. In particular, the Server-Filename, Name-Body, Type, and (if Type is Binary) Byte-Size properties are mandatory, as are Directory and Version if the server file system has such things. The server is strongly encouraged to include all other known file properties that are representable as FTP properties.

5.4.4. Rename. This command is initiated with two property lists designating an existing file and a new file on the server. Any required non-file-related properties (e.g., User-Name) must be present in the first property list but need not be in the second. The server’s response is straightforward: either it carries out the request and responds [Yes] or it responds [No].

If the second property list contains any file properties in addition to the new file name, the server may change those properties to the specified values. (This is implemented in IFS release 1.38 but in no other FTP servers at the time of this writing.) The second file name may also be the same as the first; this is useful both for changing file properties and for changing the capitalization of a file name.

5.5. Yes and No reply code assignments

A machine-readable argument may optionally be supplied with Yes and No replies. Zero should be supplied in the absence of any such code. The intent of these codes is to facilitate mechanical handling of certain exceptional conditions; however, both generation and interpretation of reply codes is entirely optional, and the command/reply sequence is unaffected by them. The inclusion of informative human-readable strings is strongly encouraged.

Codes have not been assigned to Yes replies, so Yes code bytes should always be zero. Assigned No code bytes are listed in the appendix.

5.6. Examples

These are examples of normal cases of the New-Store, Delete, Retrieve, and New-Enumerate commands.

U: [Version] <1> BCPL Pup FTP User, 14 May 82
U: [End-of-Command]
S: [Version] <1> PARC Ivy IFS 1.35.4L, File Server of May 11, 1982; 2 users out of 9
S: [End-of-Command]
U: [New-Store] ((Creation-date 14-May-82 15:26:45 PDT) (Desired-property Server-filename) (End-of-line-convention CR) (Read-date 25-May-82 14:08:01 PDT) (Server-filename User.cm) (Size 2113) (Type Text) (User-name Taft.PA) (User-password xxxxxx) (Write-date 14-May-82 15:26:45 PDT))
U: [End-of-Command]
S: [Here-is-Property-List] ((Server-filename <Taft>User.cm!1))
S: [End-of-Command]
U: [Here-is-File] ..............
U: [Yes] <0> Transfer Complete
U: [End-of-Command]
S: [Yes] <0> Store completed
S: [End-of-Command]
U: [Delete] ((Desired-property Server-filename) (Desired-property Name-body) (Server-filename User.cm) (User-name Taft.PA) (User-password xxxxxx))
U: [End-of-Command]
S: [Here-is-Property-List] ((Name-body User.cm) (Server-filename <Taft>User.cm!1))
S: [End-of-Command]
U: [Yes] <0> Please delete that file
U: [End-of-Command]
S: [Yes] <0> File Deleted
S: [End-of-Command]
U: [Retrieve] ((Desired-property Server-filename) (Desired-property Name-body) (Desired-property Type) (Desired-property Byte-size) (Desired-property Creation-date) (Directory Mesa>FTP) (Server-filename FTPDefs.*) (User-name Taft.PA) (User-password xxxxxx))
U: [End-of-Command]
S: [Here-is-Property-List] ((Byte-size 8) (Creation-date 4-Sep-80 22:14:08 PDT) (Name-body FTPDefs.bcd) (Server-filename <Mesa>FTP>FTPDefs.bcd!1) (Type Binary))
S: [End-of-Command]
U: [No] <0> No thanks
U: [End-of-Command]
S: [Here-is-Property-List] ((Creation-date 28-Jul-80 20:38:58 PDT) (End-of-line-convention CR) (Name-body FTPDefs.mesa) (Server-filename <Mesa>FTP>FTPDefs.mesa!1) (Type Text))
S: [End-of-Command]
U: [Yes] <0> File open, ready for data
U: [End-of-Command]
S: [Here-is-File] ..............
S: [Yes] <0> Transfer complete
S: [End-of-Command]
U: [New-Enumerate] ((Desired-property Server-filename) (Directory Mesa>FTP) (Server-filename FTPUser.*) (User-name Taft.PA) (User-password xxxxxx))
U: [End-of-Command]
S: [Here-is-Property-List] ((Server-filename <Mesa>FTP>FTPUser.bcd!1)) ((Server-filename <Mesa>FTP>FTPUser.config!1))
S: [End-of-Command]
U: [New-Enumerate] ((Directory Mesa>FTP) (Server-filename FTPUser.*) (User-name Taft.PA) (User-password xxxxxx))
U: [End-of-Command]
S: [Here-is-Property-List] ((Author Johnsson) (Byte-size 8) (Creation-date 13-Oct-80 20:16:58 PDT) (Device Primary) (Directory Mesa>FTP) (Name-body FTPUser.bcd) (Read-date 14-Apr-82 14:49:11 PST) (Server-filename <Mesa>FTP>FTPUser.bcd!1) (Size 25600) (Type Binary) (Version 1) (Write-date 30-Oct-80 5:30:03 PST)) ((Author Johnsson) (Creation-date 3-Aug-80 18:14:36 PDT) (Device Primary) (Directory Mesa>FTP) (Name-body FTPUser.config) (Read-date 21-Mar-82 20:05:33 PST) (Server-filename <Mesa>FTP>FTPUser.config!1) (Size 973) (Type Text) (Version 1) (Write-date 30-Oct-80 5:30:32 PST))
S: [End-of-Command]

6. File formats and conversion

When a file property list is sent to a server as part of an FTP command, it describes the file as the user would like to have it moved. The user may be willing to do some subsequent conversions, or may ask the server to perform the conversion.

For example, if a user wants to retrieve a text file from a server, and have the server convert the file to End-of-Line-Convention CRLF, then the user might send the command:

[Retrieve]((Server-Filename Foo.text)(Type Text)(End-of-Line-Convention CRLF)...)

The server might respond with a [Here-is-Property-List], indicating willingness to provide the file in that form; or it might refuse to do the conversion. Similarly, if a user storing a file wants to transmit it with End-of-Line-Convention CRLF, and have the server convert the file (if necessary) to a different internal convention, then the user might send the command:

[New-Store]((Server-Filename Foo.text)(Type Text)(End-of-Line-Convention CRLF)...)

The server might respond with a [Here-is-Property-List], indicating willingness to accept the file in that form; or it might refuse to do the conversion.

It is expected that all implementations of the FTP should at least be able to store and retrieve ASCII text files according to one standard convention:

(...(Type Text)(End-of-Line-Convention CR)..)

and to store and retrieve 8-bit Binary files:

(...(Type Binary)(Byte-Size 8)..)

7. Interrupts, restarts, and aborts

Either process may, if necessary, use the BSP convention for interrupting a byte stream: place an [Abort] Mark Byte in the stream at the current position, and then signal a BSP Interrupt. This will clear out all pending data, and re-establish control at the top level of the protocol.

A process receiving an interrupt can then look for the corresponding Mark Byte in the incoming byte stream, but must also indicate the reset position in its outgoing byte stream, so that the two may regain synchronization. Thus, upon receiving a BSP Interrupt a process must signal a corresponding BSP Interrupt-reply, and drop an [Abort] Mark Byte into the stream.

The details of this mechanism have not been resolved, and the Abort has not generally been implemented.

Remember that the protocol relies upon the BSP for establishing, terminating, or aborting all connections.

8. Other remarks

1.Note that most implementations of the BSP provide buffering of the outgoing bytes, so it may be necessary to poke the Byte Stream in an appropriate manner in order to send a complete command.

2.All BSP connections are full-duplex; however, the FTP protocol constrains the user and server to take turns transmitting. To avoid deadlocks, each party must wait until it receives an [EOC] from the other party before beginning to transmit. In exceptional situations, this may require the party not in control to consume and discard data until an [EOC] is received.

3.In future programs, a user process might request a transfer of only part of a file:

((Name BACKUP.1)(Starting-position 2000)(Number-of-bytes 512)...)

The first byte of a file is always byte 0. Issues such as positioning backwards, leaving files open for efficiency, etc. are left to the program, and are not part of the protocol.

4.In general, third party transfers are not supported. There are several situations which we believe can be handled adequately within the current protocol:

a.A user asks a server for a file, but the server knows that the file is actually backed up on an archive facility. The server can then 1) invisibly fetch the file from the archive, and then transmit it to the user; or 2) send a [No] to the user indicating that the file lives elsewhere, allowing the user to ask for the full property list (including the file’s actual location) and then establish a new connection to the archive. In either case, the server will not try to magically force a connection between the user and the archive.

b.A user wants to take a file from the server and print it on a different printing facility. The user can then 1) fetch the file from the server, and then send it to the printer; or 2) ask the server to send the file to the printer in an appropriate way.

5.There are additional commands to another file system that are not currently part of the protocol, but which might prove useful:

[Create] property-list

[Append] property-list property-list

[Reset-properties] property-list property-list

[Copy] property-list property-list

9. FTP and the Pup Mail Transfer Protocol

The File Transfer Protocol has also been used as the foundation for a Pup-based Mail Transfer Protocol; the FTP command/response framework has been augmented with a set of commands and responses to manipulate mailboxes (i.e., message files). The Mail-related commands and error codes are disjoint from the ones selected for the FTP; care must be taken, however, to ensure that any new FTP or Mail codes are not already used by the companion protocol. For further information, see Ed Taft’s memo cited in section 1.

10. Revision history

September 29, 1983:
—[Rename] may change file properties besides the name.

September 12, 1983:
—Corrected error in flowcharts for [Store] and [New-Store].

May 25, 1982:
—Renamed [Directory] command to [Enumerate] to avoid confusion with Directory property.
—Removed [You-Are-User] and added [New-Enumerate] command.
—Added Checksum and Desired-Property properties.
—Drew complete protocol flowcharts as a substitute for the numerous examples formerly included to document the command-response sequences; added some actual examples.
—Made all numbers decimal.
—Made extensive minor edits, corrections, clarifications, etc.

July 15, 1978:
—Changed to press format.
—Extraneous [No] removed from [Delete] specification.

April 15, 1978:
—Added commands to [Delete] and [Rename] files at the server.
—Added [NewStore] command, which replies not with [No]/[Yes], but with [No]/[Here-is-Property-List] (thus providing the fully qualified name under which the file is stored).
—New error codes for file access: 107, 110, 111.
—Added section 9 on FTP and the Pup Mail Transfer Protocol.
—Discussion of timeouts.
—Other minor corrections.

June 15, 1976:
—Optional file property (Size <decimal number>) incorporated; generated by Maxc in response to a [Directory] command.
—Multiple responses to [Directory] command provided, with each property list in the response preceded by [Here-is-Property-List].
—A few other small typographical errors have been corrected.

May 19, 1976:
—A major re-write, incorporating detailed examples of command/response sequences.

Appendix I: Registry of FTP mark byte commands

CommandValue (decimal)

[Retrieve]1

[Store]2

[Yes]3

[No]4

[Here-is-the-file] 5

[End-of-Command] 6

[Comment] 7

[Version] 8

[New-Store]9

[Enumerate]10

[Here-is-Property-List]11

[New-Enumerate]12

[Delete]14

[Rename]15

Mark bytes 16-31 are reserved for use in the Mail Transfer Protocol, including:

[Store-Mail]16

[Retrieve-Mail]17

[Flush-Mailbox]18

[Mailbox-Exception]19

Unimplemented commands:

[Abort]

[Reset]

[Reset-Reply]

[Create]

[Append]

[Reset-Properties]

[Copy]

Appendix II: Reply codes within [Yes] and [No]

A machine-readable argument may optionally be supplied with [Yes] and [No] replies. Zero should be supplied in the absence of any such code. The intent of these codes is to facilitate mechanical handling of certain exceptional conditions; however, both generation and interpretation of reply codes is entirely optional, and the command/reply sequence is unaffected by them. The inclusion of informative human-readable strings is strongly encouraged.

Codes have not been assigned to [Yes] replies, so [Yes] code bytes should always be zero. Assigned No code bytes are as follows (all numbers decimal).

General:
1Last command undefined or unimplemented.
2Command requires User-Name to be supplied, and it wasn’t.
3Last command illegal in present context.

Property list errors:
8Malformed property list.
9Illegal Server-Filename.
10Illegal Directory.
11Illegal Name-Body.
12Illegal Version.
13Illegal Type.
14Illegal Byte-Size.
15Illegal End-of-Line-Convention.
16Illegal User-Name.
17Illegal or incorrect User-Password.
18Illegal or incorrect User-Account.
19Illegal Connect-Name.
20Illegal or incorrect Connect-Password.
21Illegal Creation-Date.
22Illegal Write-Date.
23Illegal Read-Date.
24Illegal Author.
25Illegal Device.

Specific to file-access commands:
64File not found
65Requested access denied to file
66Transfer parameters inconsistent with file parameters
67File data error
68File too long or storage full
69Do not send the file (user to server during Retrieve)
70Store not completed (due to No from user)
71Transient, non-specific server or file-system failure
72Permanent, non-specific server or file-system failure
73File busy
74Rename destination file already exists

Specific to the Mail Transfer Protocol:
32No valid Mailbox in property list
33Illegal Mailbox property syntax
34Illegal Sender property