RFC 3659
Extensions to FTP
Network Working Group P. Hethmon Request for Comments: 3659 Hethmon Software Updates: 959 March 2007 Category: Standards Track Extensions to FTP Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The IETF Trust (2007).Abstract
This document specifies new FTP commands to obtain listings of remote directories in a defined format, and to permit restarts of interrupted data transfers in STREAM mode. It allows character sets other than US-ASCII, and also defines an optional virtual file storage structure.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Document Conventions . . . . . . . . . . . . . . . . . . . . . 3 2.1. Basic Tokens . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Pathnames. . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Times. . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Server Replies . . . . . . . . . . . . . . . . . . . . . 7 2.5. Interpreting Examples. . . . . . . . . . . . . . . . . . 8 3. File Modification Time (MDTM). . . . . . . . . . . . . . . . . 8 3.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Error Responses. . . . . . . . . . . . . . . . . . . . . 9 3.3. FEAT Response for MDTM . . . . . . . . . . . . . . . . . 10 3.4. MDTM Examples. . . . . . . . . . . . . . . . . . . . . . 10 4. File SIZE. . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. Error Responses. . . . . . . . . . . . . . . . . . . . . 12 4.3. FEAT Response for SIZE . . . . . . . . . . . . . . . . . 12 4.4. Size Examples. . . . . . . . . . . . . . . . . . . . . . 12 5. Restart of Interrupted Transfer (REST) . . . . . . . . . . . . 13 5.1. Restarting in STREAM Mode. . . . . . . . . . . . . . . . 14 5.2. Error Recovery and Restart . . . . . . . . . . . . . . . 14 5.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.4. FEAT Response for REST . . . . . . . . . . . . . . . . . 16 5.5. REST Example . . . . . . . . . . . . . . . . . . . . . . 17 6. A Trivial Virtual File Store (TVFS). . . . . . . . . . . . . . 17 6.1. TVFS File Names. . . . . . . . . . . . . . . . . . . . . 18 6.2. TVFS Pathnames . . . . . . . . . . . . . . . . . . . . . 18 6.3. FEAT Response for TVFS . . . . . . . . . . . . . . . . . 20 6.4. OPTS for TVFS. . . . . . . . . . . . . . . . . . . . . . 21 6.5. TVFS Examples. . . . . . . . . . . . . . . . . . . . . . 21 7. Listings for Machine Processing (MLST and MLSD). . . . . . . . 23 7.1. Format of MLSx Requests. . . . . . . . . . . . . . . . . 23 7.2. Format of MLSx Response. . . . . . . . . . . . . . . . . 24 7.3. File Name Encoding . . . . . . . . . . . . . . . . . . . 26 7.4. Format of Facts. . . . . . . . . . . . . . . . . . . . . 28 7.5. Standard Facts . . . . . . . . . . . . . . . . . . . . . 28 7.6. System Dependent and Local Facts . . . . . . . . . . . . 36 7.7. MLSx Examples. . . . . . . . . . . . . . . . . . . . . . 37 7.8. FEAT Response for MLSx . . . . . . . . . . . . . . . . . 49 7.9. OPTS Parameters for MLST . . . . . . . . . . . . . . . . 51 8. Impact on Other FTP Commands . . . . . . . . . . . . . . . . . 54 9. Character Sets and Internationalization. . . . . . . . . . . . 55 10. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 55 10.1. The OS Specific Fact Registry. . . . . . . . . . . . . . 56 10.2. The OS Specific Filetype Registry. . . . . . . . . . . . 56
11. Security Considerations. . . . . . . . . . . . . . . . . . . . 57 12. Normative References . . . . . . . . . . . . . . . . . . . . . 58 Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . 591. Introduction
This document updates the File Transfer Protocol (FTP) [3]. Four new commands are added: "SIZE", "MDTM", "MLST", and "MLSD". The existing command "REST" is modified. Of those, the "SIZE" and "MDTM" commands, and the modifications to "REST" have been in wide use for many years. The others are new. These commands allow a client to restart an interrupted transfer in transfer modes not previously supported in any documented way, and to obtain a directory listing in a machine friendly, predictable, format. An optional structure for the server's file store (NVFS) is also defined, allowing servers that support such a structure to convey that information to clients in a standard way, thus allowing clients more certainty in constructing and interpreting pathnames.2. Document Conventions
This document makes use of the document conventions defined in BCP 14, RFC 2119 [4]. That provides the interpretation of capitalized imperative words like MUST, SHOULD, etc. This document also uses notation defined in STD 9, RFC 959 [3]. In particular, the terms "reply", "user", "NVFS" (Network Virtual File System), "file", "pathname", "FTP commands", "DTP" (data transfer process), "user-FTP process", "user-PI" (user protocol interpreter), "user-DTP", "server-FTP process", "server-PI", "server-DTP", "mode", "type", "NVT" (Network Virtual Terminal), "control connection", "data connection", and "ASCII", are all used here as defined there. Syntax required is defined using the Augmented BNF defined in [5]. Some general ABNF definitions that are required throughout the document will be defined later in this section. At first reading, it may be wise to simply recall that these definitions exist here, and skip to the next section.
2.1. Basic Tokens
This document imports the core ABNF definitions given in Appendix A of [5]. There definitions will be found for basic ABNF elements like ALPHA, DIGIT, SP, etc. The following terms are added for use in this document. TCHAR = VCHAR / SP / HTAB ; visible plus white space RCHAR = ALPHA / DIGIT / "," / "." / ":" / "!" / "@" / "#" / "$" / "%" / "^" / "&" / "(" / ")" / "-" / "_" / "+" / "?" / "/" / "\" / "'" / DQUOTE ; <"> -- double quote character (%x22) SCHAR = RCHAR / "=" ; The VCHAR (from [5]), RCHAR, SCHAR, and TCHAR types give basic character types from varying sub-sets of the ASCII character set for use in various commands and responses. token = 1*RCHAR A "token" is a string whose precise meaning depends upon the context in which it is used. In some cases it will be a value from a set of possible values maintained elsewhere. In others it might be a string invented by one party to an FTP conversation from whatever sources it finds relevant. Note that in ABNF, string literals are case insensitive. That convention is preserved in this document, and implies that FTP commands added by this specification have names that can be represented in any case. That is, "MDTM" is the same as "mdtm", "Mdtm" and "MdTm" etc. However note that ALPHA, in particular, is case sensitive. That implies that a "token" is a case sensitive value. That implication is correct, except where explicitly stated to the contrary in this document, or in some other specification that defines the values this document specifies be used in a particular context.2.2. Pathnames
Various FTP commands take pathnames as arguments, or return pathnames in responses. When the MLST command is supported, as indicated in the response to the FEAT command [6], pathnames are to be transferred in one of the following two formats.
pathname = utf-8-name / raw
utf-8-name = <a UTF-8 encoded Unicode string>
raw = <any string that is not a valid UTF-8 encoding>
Which format is used is at the option of the user-PI or server-PI
sending the pathname. UTF-8 encodings [2] contain enough internal
structure that it is always, in practice, possible to determine
whether a UTF-8 or raw encoding has been used, in those cases where
it matters. While it is useful for the user-PI to be able to
correctly display a pathname received from the server-PI to the user,
it is far more important for the user-PI to be able to retain and
retransmit the identical pathname when required. Implementations are
advised against converting a UTF-8 pathname to a local charset that
isn't capable of representing the full Unicode character repertoire,
and then attempting to invert the charset translation later. Note
that ASCII is a subset of UTF-8. See also [1].
Unless otherwise specified, the pathname is terminated by the CRLF
that terminates the FTP command, or by the CRLF that ends a reply.
Any trailing spaces preceding that CRLF form part of the name.
Exactly one space will precede the pathname and serve as a separator
from the preceding syntax element. Any additional spaces form part
of the pathname. See [7] for a fuller explanation of the character
encoding issues. All implementations supporting MLST MUST support
[7].
Note: for pathnames transferred over a data connection, there is no
way to represent a pathname containing the characters CR and LF in
sequence, and distinguish that from the end of line indication.
Hence, pathnames containing the CRLF pair of characters cannot be
transmitted over a data connection. Data connections only contain
file names transmitted from server-FTP to user-FTP as the result of
one of the directory listing commands. Files with names containing
the CRLF sequence must either have that sequence converted to some
other form, such that the other form can be recognised and be
correctly converted back to CRLF, or be omitted from the listing.
Implementations should also beware that the FTP control connection
uses Telnet NVT conventions [8], and that the Telnet IAC character,
if part of a pathname sent over the control connection, MUST be
correctly escaped as defined by the Telnet protocol.
NVT also distinguishes between CR, LF, and the end of line CRLF, and
so would permit pathnames containing the pair of characters CR and LF
to be correctly transmitted. However, because such a sequence cannot
be transmitted over a data connection (as part of the result of a
LIST, NLST, or MLSD command), such pathnames are best avoided.
Implementors should also be aware that, although Telnet NVT conventions are used over the control connections, Telnet option negotiation MUST NOT be attempted. See section 4.1.2.12 of [9].2.2.1. Pathname Syntax
Except where TVFS is supported (see section 6), this specification imposes no syntax upon pathnames. Nor does it restrict the character set from which pathnames are created. This does not imply that the NVFS is required to make sense of all possible pathnames. Server-PIs may restrict the syntax of valid pathnames in their NVFS in any manner appropriate to their implementation or underlying file system. Similarly, a server-PI may parse the pathname and assign meaning to the components detected.2.2.2. Wildcarding
For the commands defined in this specification, all pathnames are to be treated literally. That is, for a pathname given as a parameter to a command, the file whose name is identical to the pathname given is implied. No characters from the pathname may be treated as special or "magic", thus no pattern matching (other than for exact equality) between the pathname given and the files present in the NVFS of the server-FTP is permitted. Clients that desire some form of pattern matching functionality must obtain a listing of the relevant directory, or directories, and implement their own file name selection procedures.2.3. Times
The syntax of a time value is: time-val = 14DIGIT [ "." 1*DIGIT ] The leading, mandatory, fourteen digits are to be interpreted as, in order from the leftmost, four digits giving the year, with a range of 1000--9999, two digits giving the month of the year, with a range of 01--12, two digits giving the day of the month, with a range of 01--31, two digits giving the hour of the day, with a range of 00--23, two digits giving minutes past the hour, with a range of 00--59, and finally, two digits giving seconds past the minute, with a range of 00--60 (with 60 being used only at a leap second). Years in the tenth century, and earlier, cannot be expressed. This is not considered a serious defect of the protocol.
The optional digits, which are preceded by a period, give decimal
fractions of a second. These may be given to whatever precision is
appropriate to the circumstance, however implementations MUST NOT add
precision to time-vals where that precision does not exist in the
underlying value being transmitted.
Symbolically, a time-val may be viewed as
YYYYMMDDHHMMSS.sss
The "." and subsequent digits ("sss") are optional. However the "."
MUST NOT appear unless at least one following digit also appears.
Time values are always represented in UTC (GMT), and in the Gregorian
calendar regardless of what calendar may have been in use at the date
and time indicated at the location of the server-PI.
The technical differences among GMT, TAI, UTC, UT1, UT2, etc., are
not considered here. A server-FTP process should always use the same
time reference, so the times it returns will be consistent. Clients
are not expected to be time synchronized with the server, so the
possible difference in times that might be reported by the different
time standards is not considered important.
2.4. Server Replies
Section 4.2 of [3] defines the format and meaning of replies by the
server-PI to FTP commands from the user-PI. Those reply conventions
are used here without change.
error-response = error-code SP *TCHAR CRLF
error-code = ("4" / "5") 2DIGIT
Implementors should note that the ABNF syntax used in this document
and in other FTP related documents (but not used in [3]), sometimes
shows replies using the one-line format. Unless otherwise explicitly
stated, that is not intended to imply that multi-line responses are
not permitted. Implementors should assume that, unless stated to the
contrary, any reply to any FTP command (including QUIT) may use the
multi-line format described in [3].
Throughout this document, replies will be identified by the three
digit code that is their first element. Thus the term "500 reply"
means a reply from the server-PI using the three digit code "500".
2.5. Interpreting Examples
In the examples of FTP dialogs presented in this document, lines that begin "C> " were sent over the control connection from the user-PI to the server-PI, lines that begin "S> " were sent over the control connection from the server-PI to the user-PI, and each sequence of lines that begin "D> " was sent from the server-PI to the user-PI over a data connection created just to send those lines and closed immediately after. No examples here show data transferred over a data connection from the client to the server. In all cases, the prefixes shown above, including the one space, have been added for the purposes of this document, and are not a part of the data exchanged between client and server.3. File Modification Time (MDTM)
The FTP command, MODIFICATION TIME (MDTM), can be used to determine when a file in the server NVFS was last modified. This command has existed in many FTP servers for many years, as an adjunct to the REST command for STREAM mode, thus is widely available. However, where supported, the "modify" fact that can be provided in the result from the new MLST command is recommended as a superior alternative. When attempting to restart a RETRieve, the user-FTP can use the MDTM command or the "modify" fact to check if the modification time of the source file is more recent than the modification time of the partially transferred file. If it is, then most likely the source file has changed, and it would be unsafe to restart the previously incomplete file transfer. Because the user- and server-FTPs' clocks are not necessarily synchronised, user-FTPs intending to use this method should usually obtain the modification time of the file from the server before the initial RETRieval, and compare that with the modification time before a RESTart. If they differ, the files may have changed, and RESTart would be inadvisable. Where this is not possible, the user-FTP should make sure to allow for possible clock skew when comparing times. When attempting to restart a STORe, the User FTP can use the MDTM command to discover the modification time of the partially transferred file. If it is older than the modification time of the file that is about to be STORed, then most likely the source file has changed, and it would be unsafe to restart the file transfer.
Note that using MLST (described below), where available, can provide this information and much more, thus giving an even better indication that a file has changed and that restarting a transfer would not give valid results. Note that this is applicable to any RESTart attempt, regardless of the mode of the file transfer.3.1. Syntax
The syntax for the MDTM command is: mdtm = "MdTm" SP pathname CRLF As with all FTP commands, the "MDTM" command label is interpreted in a case-insensitive manner. The "pathname" specifies an object in the NVFS that may be the object of a RETR command. Attempts to query the modification time of files that exist but are unable to be retrieved may generate an error- response, or can result in a positive response carrying a time-val with an unspecified value, the choice being made by the server-PI. The server-PI will respond to the MDTM command with a 213 reply giving the last modification time of the file whose pathname was supplied, or a 550 reply if the file does not exist, the modification time is unavailable, or some other error has occurred. mdtm-response = "213" SP time-val CRLF / error-response Note that when the 213 response is issued, that is, when there is no error, the format MUST be exactly as specified. Multi-line responses are not permitted.3.2. Error Responses
Where the command is correctly parsed but the modification time is not available, either because the pathname identifies no existing entity or because the information is not available for the entity named, then a 550 reply should be sent. Where the command cannot be correctly parsed, a 500 or 501 reply should be sent, as specified in [3]. Various 4xy replies are also possible in appropriate circumstances.
3.3. FEAT Response for MDTM
When replying to the FEAT command [6], a server-FTP process that supports the MDTM command MUST include a line containing the single word "MDTM". This MAY be sent in upper or lower case or a mixture of both (it is case insensitive), but SHOULD be transmitted in upper case only. That is, the response SHOULD be: C> Feat S> 211- <any descriptive text> S> ... S> MDTM S> ... S> 211 End The ellipses indicate place holders where other features may be included, but are not required. The one-space indentation of the feature lines is mandatory [6].3.4. MDTM Examples
If we assume the existence of three files, A B and C, a directory D, two files with names that end with the string "ile6", and no other files at all, then the MDTM command may behave as indicated. The "C>" lines are commands from user-PI to server-PI, the "S>" lines are server-PI replies. C> MDTM A S> 213 19980615100045.014 C> MDTM B S> 213 19980615100045.014 C> MDTM C S> 213 19980705132316 C> MDTM D S> 550 D is not retrievable C> MDTM E S> 550 No file named "E" C> mdtm file6 S> 213 19990929003355 C> MdTm 19990929043300 File6 S> 213 19991005213102 C> MdTm 19990929043300 file6 S> 550 19990929043300 file6: No such file or directory. From that we can conclude that both A and B were last modified at the same time (to the nearest millisecond), and that C was modified 20 days and several hours later.
The times are in GMT, so file A was modified on the 15th of June, 1998, at approximately 11am in London (summer time was then in effect), or perhaps at 8pm in Melbourne, Australia, or at 6am in New York. All of those represent the same absolute time, of course. The location where the file was modified, and consequently the local wall clock time at that location, is not available. There is no file named "E" in the current directory, but there are files named both "file6" and "19990929043300 File6". The modification times of those files were obtained. There is no file named "19990929043300 file6".4. File SIZE
The FTP command, SIZE OF FILE (SIZE), is used to obtain the transfer size of a file from the server-FTP process. This is the exact number of octets (8 bit bytes) that would be transmitted over the data connection should that file be transmitted. This value will change depending on the current STRUcture, MODE, and TYPE of the data connection or of a data connection that would be created were one created now. Thus, the result of the SIZE command is dependent on the currently established STRU, MODE, and TYPE parameters. The SIZE command returns how many octets would be transferred if the file were to be transferred using the current transfer structure, mode, and type. This command is normally used in conjunction with the RESTART (REST) command when STORing a file to a remote server in STREAM mode, to determine the restart point. The server-PI might need to read the partially transferred file, do any appropriate conversion, and count the number of octets that would be generated when sending the file in order to correctly respond to this command. Estimates of the file transfer size MUST NOT be returned; only precise information is acceptable.4.1. Syntax
The syntax of the SIZE command is: size = "Size" SP pathname CRLF The server-PI will respond to the SIZE command with a 213 reply giving the transfer size of the file whose pathname was supplied, or an error response if the file does not exist, the size is unavailable, or some other error has occurred. The value returned is in a format suitable for use with the RESTART (REST) command for mode STREAM, provided the transfer mode and type are not altered.
size-response = "213" SP 1*DIGIT CRLF /
error-response
Note that when the 213 response is issued, that is, when there is no
error, the format MUST be exactly as specified. Multi-line responses
are not permitted.
4.2. Error Responses
Where the command is correctly parsed but the size is not available,
perhaps because the pathname identifies no existing entity or because
the entity named cannot be transferred in the current MODE and TYPE
(or at all), then a 550 reply should be sent. Where the command
cannot be correctly parsed, a 500 or 501 reply should be sent, as
specified in [3]. The presence of the 550 error response to a SIZE
command MUST NOT be taken by the client as an indication that the
file cannot be transferred in the current MODE and TYPE. A server
may generate this error for other reasons -- for instance if the
processing overhead is considered too great. Various 4xy replies are
also possible in appropriate circumstances.
4.3. FEAT Response for SIZE
When replying to the FEAT command [6], a server-FTP process that
supports the SIZE command MUST include a line containing the single
word "SIZE". This word is case insensitive, and MAY be sent in any
mixture of upper or lower case, however it SHOULD be sent in upper
case. That is, the response SHOULD be:
C> FEAT
S> 211- <any descriptive text>
S> ...
S> SIZE
S> ...
S> 211 END
The ellipses indicate place holders where other features may be
included, and are not required. The one-space indentation of the
feature lines is mandatory [6].
4.4. Size Examples
Consider a text file "Example" stored on a Unix(TM) server where each
end of line is represented by a single octet. Assume the file
contains 112 lines, and 1830 octets total. Then the SIZE command
would produce:
C> TYPE I
S> 200 Type set to I.
C> size Example
S> 213 1830
C> TYPE A
S> 200 Type set to A.
C> Size Example
S> 213 1942
Notice that with TYPE=A the SIZE command reports an extra 112 octets.
Those are the extra octets that need to be inserted, one at the end
of each line, to provide correct end-of-line semantics for a transfer
using TYPE=A. Other systems might need to make other changes to the
transfer format of files when converting between TYPEs and MODEs.
The SIZE command takes all of that into account.
Since calculating the size of a file with this degree of precision
may take considerable effort on the part of the server-PI, user-PIs
should not used this command unless this precision is essential (such
as when about to restart an interrupted transfer). For other uses,
the "Size" fact of the MLST command (see section 7.5.7) ought be
requested.
5. Restart of Interrupted Transfer (REST)
To avoid having to resend the entire file if the file is only
partially transferred, both sides need some way to agree on where in
the data stream to restart the data transfer.
The FTP specification [3] includes three modes of data transfer,
STREAM, Block, and Compressed. In Block and Compressed modes, the
data stream that is transferred over the data connection is
formatted, allowing the embedding of restart markers into the stream.
The sending DTP can include a restart marker with whatever
information it needs to be able to restart a file transfer at that
point. The receiving DTP can keep a list of these restart markers,
and correlate them with how the file is being saved. To restart the
file transfer, the receiver just sends back that last restart marker,
and both sides know how to resume the data transfer. Note that there
are some flaws in the description of the restart mechanism in STD 9,
RFC 959 [3]. See section 4.1.3.4 of RFC 1123 [9] for the
corrections.
5.1. Restarting in STREAM Mode
In STREAM mode, the data connection contains just a stream of unformatted octets of data. Explicit restart markers thus cannot be inserted into the data stream, they would be indistinguishable from data. For this reason, the FTP specification [3] did not provide the ability to do restarts in stream mode. However, there is not really a need to have explicit restart markers in this case, as restart markers can be implied by the octet offset into the data stream. Because the data stream defines the file in STREAM mode, a different data stream would represent a different file. Thus, an offset will always represent the same position within a file. On the other hand, in other modes than STREAM, the same file can be transferred using quite different octet sequences and yet be reconstructed into the one identical file. Thus an offset into the data stream in transfer modes other than STREAM would not give an unambiguous restart point. If the data representation TYPE is IMAGE and the STRUcture is File, for many systems the file will be stored exactly in the same format as it is sent across the data connection. It is then usually very easy for the receiver to determine how much data was previously received, and notify the sender of the offset where the transfer should be restarted. In other representation types and structures more effort will be required, but it remains always possible to determine the offset with finite, but perhaps non-negligible, effort. In the worst case, an FTP process may need to open a data connection to itself, set the appropriate transfer type and structure, and actually transmit the file, counting the transmitted octets. If the user-FTP process is intending to restart a retrieve, it will directly calculate the restart marker and send that information in the RESTart command. However, if the user-FTP process is intending to restart sending the file, it needs to be able to determine how much data was previously sent, and correctly received and saved. A new FTP command is needed to get this information. This is the purpose of the SIZE command, as documented in section 4.5.2. Error Recovery and Restart
STREAM mode transfers with FILE STRUcture may be restarted even though no restart marker has been transferred in addition to the data itself. This is done by using the SIZE command, if needed, in combination with the RESTART (REST) command, and one of the standard file transfer commands. When using TYPE ASCII or IMAGE, the SIZE command will return the number of octets that would actually be transferred if the file were
to be sent between the two systems, i.e., with type IMAGE, the SIZE normally would be the number of octets in the file. With type ASCII, the SIZE would be the number of octets in the file including any modifications required to satisfy the TYPE ASCII CR-LF end-of-line convention.5.3. Syntax
The syntax for the REST command when the current transfer mode is STREAM is: rest = "Rest" SP 1*DIGIT CRLF The numeric value gives the number of octets of the immediately- following transfer to not actually send, effectively causing the transmission to be restarted at a later point. A value of zero effectively disables restart, causing the entire file to be transmitted. The server-PI will respond to the REST command with a 350 reply, indicating that the REST parameter has been saved, and that another command, which should be either RETR or STOR, should then follow to complete the restart. rest-response = "350" SP *TCHAR CRLF / error-response Server-FTP processes may permit transfer commands other than RETR and STOR, such as APPE and STOU, to complete a restart; however, this is not recommended. STOU (store unique) is undefined in this usage, as storing the remainder of a file into a unique file name is rarely going to be useful. If APPE (append) is permitted, it MUST act identically to STOR when a restart marker has been set. That is, in both cases, octets from the data connection are placed into the file at the location indicated by the restart marker value. The REST command is intended to complete a failed transfer. Use with RETR is comparatively well defined in all cases, as the client bears the responsibility of merging the retrieved data with the partially retrieved file. It may choose to use the data obtained other than to complete an earlier transfer, or to re-retrieve data that had been retrieved before. With STOR, however, the server must insert the data into the file named. The results are undefined if a client uses REST to do other than restart to complete a transfer of a file that had previously failed to completely transfer. In particular, if the restart marker set with a REST command is not at the end of the data currently stored at the server, as reported by the server, or if insufficient data are provided in a STOR that follows a REST to extend the destination file to at least its previous size, then the effects are undefined.
The REST command must be the last command issued before the data transfer command that is to cause a restarted, rather than a complete, file transfer. The effect of issuing a REST command at any other time is undefined. The server-PI may react to a badly positioned REST command by issuing an error response to the following command, not being a restartable data transfer command, or it may save the restart value and apply it to the next data transfer command, or it may silently ignore the inappropriate restart attempt. Because of this, a user-PI that has issued a REST command, but that has not successfully transmitted the following data transfer command for any reason, should send another REST command before the next data transfer command. If that transfer is not to be restarted, then "REST 0" should be issued. An error response will follow a REST command only when the server does not implement the command, or when the restart marker value is syntactically invalid for the current transfer mode (e.g., in STREAM mode, something other than one or more digits appears in the parameter to the REST command). Any other errors, including such problems as restart marker out of range, should be reported when the following transfer command is issued. Such errors will cause that transfer request to be rejected with an error indicating the invalid restart attempt.5.4. FEAT Response for REST
Where a server-FTP process supports RESTart in STREAM mode, as specified here, it MUST include, in the response to the FEAT command [6], a line containing exactly the string "REST STREAM". This string is not case sensitive, but it SHOULD be transmitted in upper case. Where REST is not supported at all or supported only in block or compressed modes, the REST line MUST NOT be included in the FEAT response. Where required, the response SHOULD be: C> feat S> 211- <any descriptive text> S> ... S> REST STREAM S> ... S> 211 end The ellipses indicate place holders where other features may be included, and are not required. The one-space indentation of the feature lines is mandatory [6].
5.5. REST Example
Assume that the transfer of a largish file has previously been interrupted after 802816 octets had been received, that the previous transfer was with TYPE=I, and that it has been verified that the file on the server has not since changed. C> TYPE I S> 200 Type set to I. C> PORT 127,0,0,1,15,107 S> 200 PORT command successful. C> REST 802816 S> 350 Restarting at 802816. Send STORE or RETRIEVE C> RETR cap60.pl198.tar S> 150 Opening BINARY mode data connection [...] S> 226 Transfer complete.
(page 17 continued on part 2)
