7. Listings for Machine Processing (MLST and MLSD)
The MLST and MLSD commands are intended to standardize the file and
directory information returned by the server-FTP process. These
commands differ from the LIST command in that the format of the
replies is strictly defined although extensible.
Two commands are defined, MLST and MLSD. MLST provides data about
exactly the object named on its command line, and no others. MLSD,
on the other, lists the contents of a directory if a directory is
named, otherwise a 501 reply is returned. In either case, if no
object is named, the current directory is assumed. That will cause
MLST to send a one-line response, describing the current directory
itself, and MLSD to list the contents of the current directory.
In the following, the term MLSx will be used wherever either MLST or
MLSD may be inserted.
The MLST and MLSD commands also extend the FTP protocol as presented
in STD 9, RFC 959std9 [3] and STD 3, RFC 1123std3 [9] to allow that
transmission of 8-bit data over the control connection. Note this is
not specifying character sets which are 8-bit, but specifying that
FTP implementations are to specifically allow the transmission and
reception of 8-bit bytes, with all bits significant, over the control
connection. That is, all 256 possible octet values are permitted.
The MLSx command allows both UTF-8/Unicode and "raw" forms as
arguments, and in responses both to the MLST and MLSD commands, and
all other FTP commands which take pathnames as arguments.
The MLST and MLSD commands each allow a single optional argument.
This argument may be either a directory name or, for MLST only, a
file name. For these purposes, a "file name" is the name of any
entity in the server NVFS which is not a directory. Where TVFS is
supported, any TVFS relative pathname valid in the current working
directory, or any TVFS fully qualified pathname, may be given. If a
directory name is given then MLSD must return a listing of the
contents of the named directory, otherwise it issues a 501 reply, and
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
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 an 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 the parameter is 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
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 STD 9, RFC 959std9 [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
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.
Many of the 4xy and 5xy responses defined in section 4.2 of STD 9,
RFC 959std9 [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 that 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.
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.
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 that 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;
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 [11] 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.
Five values are possible for the type fact:
file -- a file entry
cdir -- the listed directory
pdir -- a parent directory
dir -- a directory or sub-directory
OS.name=type -- an OS or file system dependent file type
The syntax is defined to be:
type-fact = type-label "=" type-val
type-label = "Type"
type-val = "File" / "cdir" / "pdir" / "dir" /
os-type
The value of the type fact (the "type-val") is a case independent
string.
7.5.1.1. type=file
The presence of the type=file fact indicates the listed entry is a
file containing non-system data. That is, it may be transferred from
one system to another of quite different characteristics, and perhaps
still be meaningful.
7.5.1.2. type=cdir
The type=cdir fact indicates the listed entry contains a pathname of
the directory whose contents are listed. An entry of this type will
only be returned as a part of the result of an MLSD command when the
type fact is included, and provides a name for the listed directory,
and facts about that directory. In a sense, it can be viewed as
representing the title of the listing, in a machine friendly format.
It may appear at any point of the listing, it is not restricted to
appearing at the start, though frequently may do so, and may occur
multiple times. It MUST NOT be included if the type fact is not
included, or there would be no way for the user-PI to distinguish the
name of the directory from an entry in the directory.
Where TVFS is supported by the server-FTP, this name may be used to
construct pathnames with which to refer to the files and directories
returned in the same MLSD output (see section 6.2). These pathnames
are only expected to work when the server-PI's position in the NVFS
file tree is the same as its position when the MLSD command was
issued, unless a fully qualified pathname results.
Where TVFS is not supported, the only defined semantics associated
with a "type=cdir" entry are that, provided the current working
directory of the server-PI has not been changed, a pathname of type
"cdir" may be used as an argument to a CWD command, which will cause
the current directory of the server-PI to change so that the
directory that was listed in its current working directory.
7.5.1.3. type=dir
If present, the type=dir entry gives the name of a directory. Such
an entry typically cannot be transferred from one system to another
using RETR, etc., but should (permissions permitting) be able to be
the object of an MLSD command.
7.5.1.4. type=pdir
If present, which will occur only in the response to a MLSD command
when the type fact is included, the type=pdir entry represents a
pathname of the parent directory of the listed directory. As well as
having the properties of a type=dir, a CWD command that uses the
pathname from this entry should change the user to a parent directory
of the listed directory. If the listed directory is the current
directory, a CDUP command may also have the effect of changing to the
named directory. User-FTP processes should note not all responses
will include this information, and that some systems may provide
multiple type=pdir responses.
Where TVFS is supported, a "type=pdir" name may be a relative
pathname, or a fully qualified pathname. A relative pathname will be
relative to the directory being listed, not to the current directory
of the server-PI at the time.
For the purposes of this type value, a "parent directory" is any
directory in which there is an entry of type=dir that refers to the
directory in which the type=pdir entity was found. Thus it is not
required that all entities with type=pdir refer to the same
directory. The "unique" fact (if supported and supplied) can be used
to determine whether there is a relationship between the type=pdir
entries or not.
7.5.1.5. System Defined Types
Files types that are specific to a specific operating system, or file
system, can be encoded using the "OS." type names. The format is:
os-type = "OS." os-name "=" os-kind
os-name = <an IANA registered operating system name>
os-kind = token
The "os-name" indicates the specific system type that supports the
particular localtype. OS specific types are registered by the IANA
using the procedures specified in section 10. The "os-kind" provides
the system dependent information as to the type of the file listed.
The os-name and os-kind strings in an os-type are case independent.
"OS.unix=block" and "OS.Unix=BLOCK" represent the same type (or
would, if such a type were registered.)
Note: Where the underlying system supports a file type that is
essentially an indirect pointer to another file, the NVFS
representation of that type should normally be to represent the file
that the reference indicates. That is, the underlying basic file
will appear more than once in the NVFS, each time with the "unique"
fact (see immediately following section) containing the same value,
indicating that the same file is represented by all such names.
User-PIs transferring the file need then transfer it only once, and
then insert their own form of indirect reference to construct
alternate names where desired, or perhaps even copy the local file if
that is the only way to provide two names with the same content. A
file which would be a reference to another file, if only the other
file actually existed, may be represented in any OS dependent manner
appropriate, or not represented at all.
7.5.1.6. Multiple Types
Where a file is such that it may validly, and sensibly, treated by
the server-PI as being of more than one of the above types, then
multiple entries should be returned, each with its own "Type" fact of
the appropriate type, and each containing the same pathname. This
may occur, for example, with a structured file, which may contain
sub-files, and where the server-PI permits the structured file to be
treated as a unit, or treated as a directory allowing the sub-files
within it to be referenced. When this is done, the pathname returned
with each entry MUST be identical to the others representing the same
file.
7.5.2. The unique Fact
The unique fact is used to present a unique identifier for a file or
directory in the NVFS accessed via a server-FTP process. The value
of this fact should be the same for any number of pathnames that
refer to the same underlying file. The fact should have different
values for names that reference distinct files. The mapping between
files, and unique fact tokens should be maintained, and remain
consistent, for at least the lifetime of the control connection from
user-PI to server-PI.
unique-fact = "Unique" "=" token
This fact would be expected to be used by server-FTPs whose host
system allows things such as symbolic links so that the same file may
be represented in more than one directory on the server. The only
conclusion that should be drawn is that if two different names each
have the same value for the unique fact, they refer to the same
underlying object. The value of the unique fact (the token) should
be considered an opaque string for comparison purposes, and is a case
dependent value. The tokens "A" and "a" do not represent the same
underlying object.
7.5.3. The modify Fact
The modify fact is used to determine the last time the content of the
file (or directory) indicated was modified. Any change of substance
to the file should cause this value to alter. That is, if a change
is made to a file such that the results of a RETR command would
differ, then the value of the modify fact should alter. User-PIs
should not assume that a different modify fact value indicates that
the file contents are necessarily different than when last retrieved.
Some systems may alter the value of the modify fact for other
reasons, though this is discouraged wherever possible. Also a file
may alter, and then be returned to its previous content, which would
often be indicated as two incremental alterations to the value of the
modify fact.
For directories, this value should alter whenever a change occurs to
the directory such that different file names would (or might) be
included in MLSD output of that directory.
modify-fact = "Modify" "=" time-val
7.5.4. The create Fact
The create fact indicates when a file, or directory, was first
created. Exactly what "creation" is for this purpose is not
specified here, and may vary from server to server. About all that
can be said about the value returned is that it can never indicate a
later time than the modify fact.
create-fact = "Create" "=" time-val
Implementation Note: Implementors of this fact on UNIX(TM) systems
should note that the unix "stat" "st_ctime" field does not give
creation time, and that unix file systems do not record creation
time at all. Unix (and POSIX) implementations will normally not
include this fact.
7.5.5. The perm Fact
The perm fact is used to indicate access rights the current FTP user
has over the object listed. Its value is always an unordered
sequence of alphabetic characters.
perm-fact = "Perm" "=" *pvals
pvals = "a" / "c" / "d" / "e" / "f" /
"l" / "m" / "p" / "r" / "w"
There are ten permission indicators currently defined. Many are
meaningful only when used with a particular type of object. The
indicators are case independent, "d" and "D" are the same indicator.
The "a" permission applies to objects of type=file, and indicates
that the APPE (append) command may be applied to the file named.
The "c" permission applies to objects of type=dir (and type=pdir,
type=cdir). It indicates that files may be created in the directory
named. That is, that a STOU command is likely to succeed, and that
STOR and APPE commands might succeed if the file named did not
previously exist, but is to be created in the directory object that
has the "c" permission. It also indicates that the RNTO command is
likely to succeed for names in the directory.
The "d" permission applies to all types. It indicates that the
object named may be deleted, that is, that the RMD command may be
applied to it if it is a directory, and otherwise that the DELE
command may be applied to it.
The "e" permission applies to the directory types. When set on an
object of type=dir, type=cdir, or type=pdir it indicates that a CWD
command naming the object should succeed, and the user should be able
to enter the directory named. For type=pdir it also indicates that
the CDUP command may succeed (if this particular pathname is the one
to which a CDUP would apply.)
The "f" permission for objects indicates that the object named may be
renamed - that is, may be the object of an RNFR command.
The "l" permission applies to the directory file types, and indicates
that the listing commands, LIST, NLST, and MLSD may be applied to the
directory in question.
The "m" permission applies to directory types, and indicates that the
MKD command may be used to create a new directory within the
directory under consideration.
The "p" permission applies to directory types, and indicates that
objects in the directory may be deleted, or (stretching naming a
little) that the directory may be purged. Note: it does not indicate
that the RMD command may be used to remove the directory named
itself, the "d" permission indicator indicates that.
The "r" permission applies to type=file objects, and for some
systems, perhaps to other types of objects, and indicates that the
RETR command may be applied to that object.
The "w" permission applies to type=file objects, and for some
systems, perhaps to other types of objects, and indicates that the
STOR command may be applied to the object named.
Note: That a permission indicator is set can never imply that the
appropriate command is guaranteed to work -- just that it might.
Other system specific limitations, such as limitations on
available space for storing files, may cause an operation to fail,
where the permission flags may have indicated that it was likely
to succeed. The permissions are a guide only.
Implementation note: The permissions are described here as they apply
to FTP commands. They may not map easily into particular
permissions available on the server's operating system. Servers
are expected to synthesize these permission bits from the
permission information available from operating system. For
example, to correctly determine whether the "D" permission bit
should be set on a directory for a server running on the UNIX(TM)
operating system, the server should check that the directory named
is empty, and that the user has write permission on both the
directory under consideration, and its parent directory.
Some systems may have more specific permissions than those listed
here, such systems should map those to the flags defined as best
they are able. Other systems may have only more broad access
controls. They will generally have just a few possible
permutations of permission flags, however they should attempt to
correctly represent what is permitted.
7.5.6. The lang Fact
The lang fact describes the natural language of the file name for use
in display purposes. Values used here should be taken from the
language registry of the IANA. See [12] for the syntax, and
procedures, related to language tags.
lang-fact = "Lang" "=" token
Server-FTP implementations MUST NOT guess language values. Language
values must be determined in an unambiguous way such as file system
tagging of language or by user configuration. Note that the lang
fact provides no information at all about the content of a file, only
about the encoding of its name.
7.5.7. The size Fact
The size fact applies to non-directory file types and should always
reflect the approximate size of the file. This should be as accurate
as the server can make it, without going to extraordinary lengths,
such as reading the entire file. The size is expressed in units of
octets of data in the file.
Given limitations in some systems, Client-FTP implementations must
understand this size may not be precise and may change between the
time of a MLST and RETR operation.
Clients that need highly accurate size information for some
particular reason should use the SIZE command as defined in section
4. The most common need for this accuracy is likely to be in
conjunction with the REST command described in section 5. The size
fact, on the other hand, should be used for purposes such as
indicating to a human user the approximate size of the file to be
transferred, and perhaps to give an idea of expected transfer
completion time.
size-fact = "Size" "=" 1*DIGIT
The media-type fact represents the IANA media type of the file named,
and applies only to non-directory types. The list of values used
must follow the guidelines set by the IANA registry.
media-type = "Media-Type" "=" <per IANA guidelines>
Server-FTP implementations MUST NOT guess media type values. Media
type values must be determined in an unambiguous way such as file
system tagging of media-type or by user configuration. This fact
gives information about the content of the file named. Both the
primary media type, and any appropriate subtype should be given,
separated by a slash "/" as is traditional.
7.5.9. The charset Fact
The charset fact provides the IANA character set name, or alias, for
the encoded pathnames in a MLSx response. The default character set
is UTF-8 unless specified otherwise. FTP implementations SHOULD use
UTF-8 if possible to encourage maximum inter-operability. The value
of this fact applies to the pathname only, and provides no
information about the contents of the file.
charset-type = "Charset" "=" token
7.5.10. Required Facts
Servers are not required to support any particular set of the
available facts. However, servers SHOULD, if conceivably possible,
support at least the type, perm, size, unique, and modify facts.
7.6. System Dependent and Local Facts
By using an system dependent fact, or a local fact, a server-PI may
communicate to the user-PI information about the file named that is
peculiar to the underlying file system.
7.6.1. System Dependent Facts
System dependent fact names are labeled by prefixing a label
identifying the specific information returned by the name of the
appropriate operating system from the IANA maintained list of
operating system names.
The value of an OS dependent fact may be whatever is appropriate to
convey the information available. It must be encoded as a "token" as
defined in section 2.1 however.
In order to allow reliable inter-operation between users of system
dependent facts, the IANA will maintain a registry of system
dependent fact names, their syntax, and the interpretation to be
given to their values. Registrations of system dependent facts are
to be accomplished according to the procedures of section 10.
7.6.2. Local Facts
Implementations may also make available other facts of their own
choosing. As the method of interpretation of such information will
generally not be widely understood, server-PIs should be aware that
clients will typically ignore any local facts provided. As there is
no registration of locally defined facts, it is entirely possible
that different servers will use the same local fact name to provide
vastly different information. Hence user-PIs should be hesitant
about making any use of any information in a locally defined fact
without some other specific assurance that the particular fact is one
that they do comprehend.
Local fact names all begin with the sequence "X.". The rest of the
name is a "token" (see section 2.1). The value of a local fact can
be anything at all, provided it can be encoded as a "token".
7.7. MLSx Examples
The following examples are all taken from dialogues between existing
FTP clients and servers. Because of this, not all possible
variations of possible response formats are shown in the examples.
This should not be taken as limiting the options of other server
implementors. Where the examples show OS dependent information, that
is to be treated as being purely for the purposes of demonstration of
some possible OS specific information that could be defined. As at
the time of the writing of this document, no OS specific facts or
file types have been defined, the examples shown here should not be
treated as in any way to be preferred over other possible similar
definitions. Consult the IANA registries to determine what types and
facts have been defined. Finally also beware that as the examples
shown are taken from existing implementations, coded before this
document was completed, the possibility of variations between the
text of this document and the examples exists. In any such case of
inconsistency, the example is to be treated as incorrect.
In the examples shown, only relevant commands and responses have been
included. This is not to imply that other commands (including
authentication, directory modification, PORT or PASV commands, or
similar) would not be present in an actual connection, or were not,
in fact, actually used in the examples before editing. Note also
that the formats shown are those that are transmitted between client
and server, not formats that would normally ever be reported to the
user of the client.
7.7.1. Simple MLST
C> PWD
S> 257 "/tmp" is current directory.
C> MLst cap60.pl198.tar.gz
S> 250- Listing cap60.pl198.tar.gz
S> Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz
S> 250 End
The client first asked to be told the current directory of the
server. This was purely for the purposes of clarity of this example.
The client then requested facts about a specific file. The server
returned the "250-" first control-response line, followed by a single
line of facts about the file, followed by the terminating "250 "
line. The text on the control-response line and the terminating line
can be anything the server decides to send. Notice that the fact
line is indented by a single space. Notice also that there are no
spaces in the set of facts returned, until the single space before
the file name. The file name returned on the fact line is a fully
qualified pathname of the file listed. The facts returned show that
the line refers to a file, that file contains approximately 1024990
bytes, though more or less than that may be transferred if the file
is retrieved, and a different number may be required to store the
file at the client's file store, and the connected user has
permission to retrieve the file but not to do anything else
particularly interesting.
7.7.2. MLST of a directory
C> PWD
S> 257 "/" is current directory.
C> MLst tmp
S> 250- Listing tmp
S> Type=dir;Modify=19981107085215;Perm=el; /tmp
S> 250 End
Again the PWD is just for the purposes of demonstration for the
example. The MLST fact line this time shows that the file listed is
a directory, that it was last modified at 08:52:15 on the 7th of
November, 1998 UTC, and that the user has permission to enter the
directory, and to list its contents, but not to modify it in any way.
Again, the fully qualified pathname of the directory listed is given.
7.7.3. MLSD of a directory
C> MLSD tmp
S> 150 BINARY connection open for MLSD tmp
D> Type=cdir;Modify=19981107085215;Perm=el; tmp
D> Type=cdir;Modify=19981107085215;Perm=el; /tmp
D> Type=pdir;Modify=19990112030508;Perm=el; ..
D> Type=file;Size=25730;Modify=19940728095854;Perm=; capmux.tar.z
D> Type=file;Size=1830;Modify=19940916055648;Perm=r; hatch.c
D> Type=file;Size=25624;Modify=19951003165342;Perm=r; MacIP-02.txt
D> Type=file;Size=2154;Modify=19950501105033;Perm=r; uar.netbsd.patch
D> Type=file;Size=54757;Modify=19951105101754;Perm=r; iptnnladev.1.0.sit.hqx
D> Type=file;Size=226546;Modify=19970515023901;Perm=r; melbcs.tif
D> Type=file;Size=12927;Modify=19961025135602;Perm=r; tardis.1.6.sit.hqx
D> Type=file;Size=17867;Modify=19961025135602;Perm=r; timelord.1.4.sit.hqx
D> Type=file;Size=224907;Modify=19980615100045;Perm=r; uar.1.2.3.sit.hqx
D> Type=file;Size=1024990;Modify=19980130010322;Perm=r; cap60.pl198.tar.gz
S> 226 MLSD completed
In this example notice that there is no leading space on the fact
lines returned over the data connection. Also notice that two lines
of "type=cdir" have been given. These show two alternate names for
the directory listed, one a fully qualified pathname, and the other a
local name relative to the servers current directory when the MLSD
was performed. Note that all other file names in the output are
relative to the directory listed, though the server could, if it
chose, give a fully qualified pathname for the "type=pdir" line.
This server has chosen not to. The other files listed present a
fairly boring set of files that are present in the listed directory.
Note that there is no particular order in which they are listed.
They are not sorted by file name, by size, or by modify time. Note
also that the "perm" fact has an empty value for the file
"capmux.tar.z" indicating that the connected user has no permissions
at all for that file. This server has chosen to present the "cdir"
and "pdir" lines before the lines showing the content of the
directory, it is not required to do so. The "size" fact does not
provide any meaningful information for a directory, so is not
included in the fact lines for the directory types shown.
C> MLst test
S> 250- Listing test
S> Type=dir;Perm=el;Unique=keVO1+ZF4 test
S> 250 End
C> MLSD test
S> 150 BINARY connection open for MLSD test
D> Type=cdir;Perm=el;Unique=keVO1+ZF4; test
D> Type=pdir;Perm=e;Unique=keVO1+d?3; ..
D> Type=OS.unix=slink:/foobar;Perm=;Unique=keVO1+4G4; foobar
D> Type=OS.unix=chr-13/29;Perm=;Unique=keVO1+5G4; device
D> Type=OS.unix=blk-11/108;Perm=;Unique=keVO1+6G4; block
D> Type=file;Perm=awr;Unique=keVO1+8G4; writable
D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; promiscuous
D> Type=dir;Perm=;Unique=keVO1+1t2; no-exec
D> Type=file;Perm=r;Unique=keVO1+EG4; two words
D> Type=file;Perm=r;Unique=keVO1+IH4; leading space
D> Type=file;Perm=r;Unique=keVO1+1G4; file1
D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; incoming
D> Type=file;Perm=r;Unique=keVO1+1G4; file2
D> Type=file;Perm=r;Unique=keVO1+1G4; file3
D> Type=file;Perm=r;Unique=keVO1+1G4; file4
S> 226 MLSD completed
C> MLSD test/incoming
S> 150 BINARY connection open for MLSD test/incoming
D> Type=cdir;Perm=cpmel;Unique=keVO1+7G4; test/incoming
D> Type=pdir;Perm=el;Unique=keVO1+ZF4; ..
D> Type=file;Perm=awdrf;Unique=keVO1+EH4; bar
D> Type=file;Perm=awdrf;Unique=keVO1+LH4;
D> Type=file;Perm=rf;Unique=keVO1+1G4; file5
D> Type=file;Perm=rf;Unique=keVO1+1G4; file6
D> Type=dir;Perm=cpmdelf;Unique=keVO1+!s2; empty
S> 226 MLSD completed
For the purposes of this example the fact set requested has been
modified to delete the "size" and "modify" facts, and add the
"unique" fact. First, facts about a file name have been obtained via
MLST. Note that no fully qualified pathname was given this time.
That was because the server was unable to determine that information.
Then having determined that the file name represents a directory,
that directory has been listed. That listing also shows no fully
qualified pathname, for the same reason, thus has but a single
"type=cdir" line. This directory (which was created especially for
the purpose) contains several interesting files. There are some with
OS dependent file types, several sub-directories, and several
ordinary files.
Not much can be said here about the OS dependent file types, as none
of the information shown there should be treated as any more than
possibilities. It can be seen that the OS type of the server is
"unix" though, which is one of the OS types in the IANA registry of
Operating System names.
Of the three directories listed, "no-exec" has no permission granted
to this user to access at all. From the "Unique" fact values, it can
be determined that "promiscuous" and "incoming" in fact represent the
same directory. Its permissions show that the connected user has
permission to do essentially anything other than to delete the
directory. That directory was later listed. It happens that the
directory can not be deleted because it is not empty.
Of the normal files listed, two contain spaces in their names. The
file called " leading space" actually contains two spaces in its
name, one before the "l" and one between the "g" and the "s". The
two spaces that separate the facts from the visible part of the
pathname make that clear. The file "writable" has the "a" and "w"
permission bits set, and consequently the connected user should be
able to STOR or APPE to that file.
The other four file names, "file1", "file2", "file3", and "file4" all
represent the same underlying file, as can be seen from the values of
the "unique" facts of each. It happens that "file1" and "file2" are
Unix "hard" links, and that "file3" and "file4" are "soft" or
"symbolic" links to the first two. None of that information is
available via standard MLST facts, it is sufficient for the purposes
of FTP to note that all represent the same file, and that the same
data would be fetched no matter which of them was retrieved, and that
all would be simultaneously modified were data stored in any.
Finally, the sub-directory "incoming" is listed. Since "promiscuous"
is the same directory there would be no point listing it as well. In
that directory, the files "file5" and "file6" represent still more
names for the "file1" file we have seen before. Notice the entry
between that for "bar" and "file5". Though it is not possible to
easily represent it in this document, that shows a file with a name
comprising exactly three spaces (" "). A client will have no
difficulty determining that name from the output presented to it
however. The directory "empty" is, as its name implies, empty,
though that is not shown here. It can, however, be deleted, as can
file "bar" and the file whose name is three spaces. All the files
that reside in this directory can be renamed. This is a consequence
of the UNIX semantics of the directory that contains them being
modifiable.
C> MLst file1
S> 250- Listing file1
S> Type=file;Modify=19990929003355.237; file1
S> 250 End
In this example, the server-FTP is indicating that "file1" was last
modified 237 milliseconds after 00:33:55 UTC on the 29th of
September, 1999.
7.7.6. A Different Server
C> MLST
S> 250-Begin
S> type=dir;unique=AQkAAAAAAAABCAAA; /
S> 250 End.
C> MLSD
S> 150 Opening ASCII mode data connection for MLS.
D> type=cdir;unique=AQkAAAAAAAABCAAA; /
D> type=dir;unique=AQkAAAAAAAABEAAA; bin
D> type=dir;unique=AQkAAAAAAAABGAAA; etc
D> type=dir;unique=AQkAAAAAAAAB8AwA; halflife
D> type=dir;unique=AQkAAAAAAAABoAAA; incoming
D> type=dir;unique=AQkAAAAAAAABIAAA; lib
D> type=dir;unique=AQkAAAAAAAABWAEA; linux
D> type=dir;unique=AQkAAAAAAAABKAEA; ncftpd
D> type=dir;unique=AQkAAAAAAAABGAEA; outbox
D> type=dir;unique=AQkAAAAAAAABuAAA; quake2
D> type=dir;unique=AQkAAAAAAAABQAEA; winstuff
S> 226 Listing completed.
C> MLSD linux
S> 150 Opening ASCII mode data connection for MLS.
D> type=cdir;unique=AQkAAAAAAAABWAEA; /linux
D> type=pdir;unique=AQkAAAAAAAABCAAA; /
D> type=dir;unique=AQkAAAAAAAABeAEA; firewall
D> type=file;size=12;unique=AQkAAAAAAAACWAEA; helo_world
D> type=dir;unique=AQkAAAAAAAABYAEA; kernel
D> type=dir;unique=AQkAAAAAAAABmAEA; scripts
D> type=dir;unique=AQkAAAAAAAABkAEA; security
S> 226 Listing completed.
C> MLSD linux/kernel
S> 150 Opening ASCII mode data connection for MLS.
D> type=cdir;unique=AQkAAAAAAAABYAEA; /linux/kernel
D> type=pdir;unique=AQkAAAAAAAABWAEA; /linux
D> type=file;size=6704;unique=AQkAAAAAAAADYAEA; k.config
D> type=file;size=7269221;unique=AQkAAAAAAAACYAEA; linux-2.0.36.tar.gz
D> type=file;size=12514594;unique=AQkAAAAAAAAEYAEA; linux-2.1.130.tar.gz
