draft-ietf-ftpext-mlst-15.txt

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

   does not open a data connection.  In all cases for MLST, a single set
   of fact lines (usually a single fact line) containing the information
   about the named file or directory shall be returned over the control
   connection, without opening a data connection.

   If no argument is given then MLSD must return a listing of the
   contents of the current working directory, and MLST must return a
   listing giving information about the current working directory
   itself.  For these purposes, the contents of a directory are whatever
   file or directory names (not pathnames) the server-PI will allow to
   be referenced when the current working directory is the directory
   named, and which the server-PI desires to reveal to the user-PI.
   Note that omitting the argument is the only defined way to obtain a
   listing of the current directory, unless a pathname that represents
   the directory happens to be known.  In particular, there is no
   defined shorthand name for the current directory.  This does not
   prohibit any particular server-PI implementing such a shorthand.

   No title, header, or summary, lines, or any other formatting, other
   than as is specified below, is ever returned in the output of an MLST
   or MLSD command.

   If the Client-FTP sends an invalid argument, the Server-FTP MUST
   reply with an error code of 501.

   The syntax for the MLSx command is:

        mlst             = "MLst" [ SP pathname ] CRLF
        mlsd             = "MLsD" [ SP pathname ] CRLF








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


7.2. Format of MLSx Response

   The format of a response to an MLSx command is as follows:

        mlst-response    = control-response / error-response
        mlsd-response    = ( initial-response final-response ) /
                           error-response

        control-response = "250-" [ response-message ] CRLF
                           1*( SP entry CRLF )
                           "250" [ SP response-message ] CRLF

        initial-response = "150" [ SP response-message ] CRLF
        final-response   = "226" SP response-message CRLF

        response-message = *TCHAR

        data-response    = *( entry CRLF )

        entry            = [ facts ] SP pathname
        facts            = 1*( fact ";" )
        fact             = factname "=" value
        factname         = "Size" / "Modify" / "Create" /
                           "Type" / "Unique" / "Perm" /
                           "Lang" / "Media-Type" / "CharSet" /
                           os-depend-fact / local-fact
        os-depend-fact   = <IANA assigned OS name> "." token
        local-fact       = "X." token
        value            = *SCHAR

   Upon receipt of a MLSx command, the server will verify the parameter,
   and if invalid return an error-response.  For this purpose, the
   parameter should be considered to be invalid if the client issuing
   the command does not have permission to perform the requested
   operation.

   If valid, then for an MLST command, the server-PI will send the first
   (leading) line of the control response, the entry for the pathname
   given, or the current directory if no pathname was provided, and the
   terminating line.  Normally exactly one entry would be returned, more
   entries are permitted only when required to represent a file that is
   to have multiple "Type" facts returned.  In this case, the pathname
   component of every response MUST be identical.

   Note that for MLST the fact set is preceded by a space.  That is
   provided to guarantee that the fact set cannot be accidentally
   interpreted as the terminating line of the control response, but is
   required even when that would not be possible.  Exactly one space



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


   exists between the set of facts and the pathname.  Where no facts are
   present, there will be exactly two leading spaces before the
   pathname.  No spaces are permitted in the facts, any other spaces in
   the response are to be treated as being a part of the pathname.

   If the command was an MLSD command, the server will open a data
   connection as indicated in section 3.2 of RFC959 [3].  If that fails,
   the server will return an error-response.  If all is OK, the server
   will return the initial-response, send the appropriate data-response
   over the new data connection, close that connection, and then send
   the final-response over the control connection.  The grammar above
   defines the format for the data-response, which defines the format of
   the data returned over the data connection established.

   The data connection opened for a MLSD response shall be a connection
   as if the "TYPE L 8", "MODE S", and "STRU F" commands had been given,
   whatever FTP transfer type, mode and structure had actually been set,
   and without causing those settings to be altered for future commands.
   That is, this transfer type shall be set for the duration of the data
   connection established for this command only.  While the content of
   the data sent can be viewed as a series of lines, implementations
   should note that there is no maximum line length defined.
   Implementations should be prepared to deal with arbitrarily long
   lines.

   The facts part of the specification would contain a series of "file
   facts" about the file or directory named on the same line.  Typical
   information to be presented would include file size, last
   modification time, creation time, a unique identifier, and a
   file/directory flag.

   The complete format for a successful reply to the MLSD command would
   be:

        facts SP pathname CRLF
        facts SP pathname CRLF
        facts SP pathname CRLF
        ...

   Note that the format is intended for machine processing, not human
   viewing, and as such the format is very rigid.  Implementations MUST
   NOT vary the format by, for example, inserting extra spaces for
   readability, replacing spaces by tabs, including header or title
   lines, or inserting blank lines, or in any other way alter this
   format.  Exactly one space is always required after the set of facts
   (which may be empty).  More spaces may be present on a line if, and
   only if, the pathname presented contains significant spaces.  The set
   of facts must not contain any spaces anywhere inside it.  Facts



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


   should be provided in each output line only if they both provide
   relevant information about the file named on the same line, and they
   are in the set requested by the user-PI.  See section 7.9 (page 51).
   There is no requirement that the same set of facts be provided for
   each file, or that the facts presented occur in the same order for
   each file.

7.2.1. Error responses to MLSx commands

   Many of the 4xy and 5xy responses defined in section 4.2 of RFC959
   [3] are possible in response to the MLST and MLSD commands.  In
   particular, syntax errors can generate 500 or 501 replies.  Giving a
   pathname that exists but is not a directory as the argument to a MLSD
   command generates a 501 reply.  Giving a name which does not exist,
   or for which access permission (to obtain directory information as
   requested) is not granted will elicit a 550 reply.  Other replies
   (530, 553, 503, 504, and any of the 4xy replies) are also possible in
   appropriate circumstances.

7.3. File name encoding

   An FTP implementation supporting the MLSx commands must be 8-bit
   clean.  This is necessary in order to transmit UTF-8 encoded file
   names.  This specification recommends the use of UTF-8 encoded file
   names.  FTP implementations SHOULD use UTF-8 whenever possible to
   encourage the maximum inter-operability.

   File names are not restricted to UTF-8, however treatment of
   arbitrary character encodings is not specified by this standard.
   Applications are encouraged to treat non-UTF-8 encodings of file
   names as octet sequences.

   Note that this encoding is unrelated to that of the contents of the
   file, even if the file contains character data.

   Further information about file name encoding for FTP may be found in
   "Internationalization of the File Transfer Protocol" [7].

7.3.1. Notes about the File name

   The file name returned in the MLST response should be the same name
   as was specified in the MLST command, or, where TVFS is supported, a
   fully qualified TVFS path naming the same file.  Where no argument
   was given to the MLST command, the server-PI may either include an
   empty file name in the response, or it may supply a name that refers
   to the current directory, if such a name is available.  Where TVFS is
   supported, a fully qualified pathname of the current directory SHOULD
   be returned.



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


   File names returned in the output from an MLSD command SHOULD be
   unqualified names within the directory named, or the current
   directory if no argument was given.  That is, the directory named in
   the MLSD command SHOULD NOT appear as a component of the file names
   returned.

   If the server-FTP process is able, and the "type" fact is being
   returned, it MAY return in the MLSD response, an entry whose type is
   "cdir", which names the directory from which the contents of the
   listing were obtained.  Where TVFS is supported, the name MAY be the
   fully qualified pathname of the directory, or MAY be any other
   pathname which is valid to refer to that directory from the current
   working directory of the server-FTP.  Where more than one name
   exists, multiple of these entries may be returned.  In a sense, the
   "cdir" entry can be viewed as a heading for the MLSD output.
   However, it is not required to be the first entry returned, and may
   occur anywhere within the listing.

   When TVFS is supported, a user-PI can refer to any file or directory
   in the listing by combining a type "cdir" name, with the appropriate
   name from the directory listing using the procedure defined in
   section 6.2.

   Alternatively, whether TVFS is supported or not, the user-PI can
   issue a CWD command ([3]) giving a name of type "cdir" from the
   listing returned, and from that point reference the files returned in
   the MLSD response from which the cdir was obtained by using the file
   name components of the listing.

7.4. Format of Facts

   The "facts" for a file in a reply to a MLSx command consist of
   information about that file.  The facts are a series of keyword=value
   pairs each followed by semi-colon (";") characters.  An individual
   fact may not contain a semi-colon in its name or value.  The complete
   series of facts may not contain the space character.  See the
   definition or "RCHAR" in section 2.1 for a list of the characters
   that can occur in a fact value.  Not all are applicable to all facts.

   A sample of a typical series of facts would be: (spread over two
   lines for presentation here only)

        size=4161;lang=en-US;modify=19970214165800;create=19961001124534;
        type=file;x.myfact=foo,bar;







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


7.5. Standard Facts

   This document defines a standard set of facts as follows:

        size       -- Size in octets
        modify     -- Last modification time
        create     -- Creation time
        type       -- Entry type
        unique     -- Unique id of file/directory
        perm       -- File permissions, whether read, write, execute is
                      allowed for the login id.
        lang       -- Language of the file name per IANA[12] registry.
        media-type -- MIME media-type of file contents per IANA registry.
        charset    -- Character set per IANA registry (if not UTF-8)

   Fact names are case-insensitive.  Size, size, SIZE, and SiZe are the
   same fact.

   Further operating system specific keywords could be specified by
   using the IANA operating system name as a prefix (examples only):

        OS/2.ea   -- OS/2 extended attributes
        MACOS.rf  -- MacIntosh resource forks
        UNIX.mode -- Unix file modes (permissions)

   Implementations may define keywords for experimental, or private use.
   All such keywords MUST begin with the two character sequence "x.".
   As type names are case independent, "x." and "X." are equivalent.
   For example:

        x.ver  -- Version information
        x.desc -- File description
        x.type -- File type

7.5.1. The type Fact

   The type fact needs a special description.  Part of the problem with
   current practices is deciding when a file is a directory.  If it is a
   directory, is it the current directory, a regular directory, or a
   parent directory?  The MLST specification makes this unambiguous
   using the type fact.  The type fact given specifies information about
   the object listed on the same line of the MLST response.