tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 3659

Proposed STD
Pages: 61
Top     in Index     Prev     Next
in Group Index     Prev in Group     No Next: Highest Number in Group     Group: FTPEXT

Extensions to FTP

Part 1 of 3, p. 1 to 17
None       Next RFC Part

Updates:    0959

Top       ToC       Page 1 
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).


   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.

Top       Page 2 
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

Top      ToC       Page 3 
   11. Security Considerations. . . . . . . . . . . . . . . . . . . . 57
   12. Normative References . . . . . . . . . . . . . . . . . . . . . 58
   Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . 59

1.  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,

   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.

Top      ToC       Page 4 
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

      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

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.

Top      ToC       Page 5 
      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

   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.

Top      ToC       Page 6 
   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 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.

Top      ToC       Page 7 
   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


   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".

Top      ToC       Page 8 
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

   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.

Top      ToC       Page 9 
   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 /

   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

Top      ToC       Page 10 
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.

Top      ToC       Page 11 
   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.

Top      ToC       Page 12 
      size-response = "213" SP 1*DIGIT CRLF /

   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:

Top      ToC       Page 13 
      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

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 of RFC 1123 [9] for the

Top      ToC       Page 14 
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

Top      ToC       Page 15 
   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

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 /

   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.

Top      ToC       Page 16 
   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>  ...
      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].

Top      ToC       Page 17 
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)

Next RFC Part