draft-ietf-ftpext-mlst-15.txt

ProFTPd 是一款基于GPL协议的可配置的FTP服务器

   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.



Elz & Hethmon            [Expires October 2002]                [Page 12]

Internet Draft        draft-ietf-ftpext-mlst-15.txt           April 2002


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 be able 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 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.



Elz & Hethmon            [Expires October 2002]                [Page 13]

Internet Draft        draft-ietf-ftpext-mlst-15.txt           April 2002


   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



Elz & Hethmon            [Expires October 2002]                [Page 14]

Internet Draft        draft-ietf-ftpext-mlst-15.txt           April 2002


   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.  If it chooses to use the data obtained other than to
   complete an earlier transfer, or if it chooses to re-retrieve data
   that had been retrieved before, that is its choice.  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 which 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 which is to cause a restarted rather than 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 which 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 the restart marker value is
   syntactically invalid for the current transfer mode.  That is, in
   STREAM mode, if 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.









Elz & Hethmon            [Expires October 2002]                [Page 15]

Internet Draft        draft-ietf-ftpext-mlst-15.txt           April 2002


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

6. A Trivial Virtual File Store (TVFS)

   Traditionally, FTP has placed almost no constraints upon the file
   store (NVFS) provided by a server.  This specification does not alter
   that.  However, it has become common for servers to attempt to
   provide at least file system naming conventions modeled loosely upon
   those of the UNIX(TM) file system.  That is, a tree structured file
   system, built of directories, each of which can contain other
   directories, or other kinds of files, or both.  Each file and



Elz & Hethmon            [Expires October 2002]                [Page 16]

Internet Draft        draft-ietf-ftpext-mlst-15.txt           April 2002


   directory has a name relative to the directory that contains it,
   except for the directory at the root of the tree, which is contained
   in no other directory, and hence has no name of its own.

   That which has so far been described is perfectly consistent with the
   standard FTP NVFS and access mechanisms.  The "CWD" command is used
   to move from one directory to an embedded directory.  "CDUP" may be
   provided to return to the parent directory, and the various file
   manipulation commands ("RETR", "STOR", the rename commands, etc) are
   used to manipulate files within the current directory.

   However, it is often useful to be able to reference files other than
   by changing directories, especially as FTP provides no guaranteed
   mechanism to return to a previous directory.  The Trivial Virtual
   File Store (TVFS), if implemented, provides that mechanism.

6.1. TVFS File Names

   Where a server implements the TVFS, no elementary file name shall
   contain the character "/".  Where the underlying natural file store
   permits files, or directories, to contain the "/" character in their
   names, a server-PI implementing TVFS must encode that character in
   some manner whenever file or directory names are being returned to
   the user-PI, and reverse that encoding whenever such names are being
   accepted from the user-PI.

   The encoding method to be used is not specified here.  Where some
   other character is illegal in file and directory names in the
   underlying file store, a simple transliteration may be sufficient.
   Where there is no suitable substitute character a more complex
   encoding scheme, possibly using an escape character, is likely to be
   required.

   With the one exception of the unnamed root directory, a TVFS file
   name may not be empty.  That is, all other file names contain at
   least one character.