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 959std9 [3]. See section 4.1.3.4 of RFC 1123std3 [9] for the
corrections.
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.
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.
