idnits 2.17.1 draft-ietf-ftpext-mlst-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 23 instances of too long lines in the document, the longest one being 5 characters in excess of 72. == There are 7 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 2002) is 7865 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '10' is defined on line 2671, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 2044 (ref. '2') (Obsoleted by RFC 2279) ** Obsolete normative reference: RFC 2234 (ref. '5') (Obsoleted by RFC 4234) -- Possible downref: Non-RFC (?) normative reference: ref. '11' -- Possible downref: Non-RFC (?) normative reference: ref. '12' ** Obsolete normative reference: RFC 1766 (ref. '13') (Obsoleted by RFC 3066, RFC 3282) ** Downref: Normative reference to an Informational RFC: RFC 2577 (ref. '14') Summary: 7 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 FTPEXT Working Group R. Elz 3 Internet Draft Prince of Songkla University 4 Expiration Date: March 2003 5 P. Hethmon 6 Hethmon Brothers 8 September 2002 10 Extensions to FTP 12 draft-ietf-ftpext-mlst-16.txt 14 Status of this Memo 16 This document is an Internet-Draft and is subject to all provisions 17 of Section 10 of RFC2026. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 To view the list Internet-Draft Shadow Directories, see 33 http://www.ietf.org/shadow.html. 35 This entire section has been prepended to this document automatically 36 during formatting without any direct involvement by the author(s) of 37 this draft. 39 Abstract 41 This document specifies new FTP commands to obtain listings of remote 42 directories in a defined format, and to permit restarts of 43 interrupted data transfers in STREAM mode. It allows character sets 44 other than US-ASCII, and also defines an optional virtual file 45 storage structure. 47 Table of Contents 49 Abstract ................................................ 1 50 1 Introduction ............................................ 3 51 2 Document Conventions .................................... 3 52 2.1 Basic Tokens ............................................ 4 53 2.2 Pathnames ............................................... 4 54 2.3 Times ................................................... 6 55 2.4 Server Replies .......................................... 7 56 2.5 Interpreting Examples ................................... 8 57 3 File Modification Time (MDTM) ........................... 8 58 3.1 Syntax .................................................. 9 59 3.2 Error responses ......................................... 9 60 3.3 FEAT response for MDTM .................................. 10 61 3.4 MDTM Examples ........................................... 10 62 4 File SIZE ............................................... 11 63 4.1 Syntax .................................................. 11 64 4.2 Error responses ......................................... 12 65 4.3 FEAT response for SIZE .................................. 12 66 4.4 Size Examples ........................................... 12 67 5 Restart of Interrupted Transfer (REST) .................. 13 68 5.1 Restarting in STREAM Mode ............................... 14 69 5.2 Error Recovery and Restart .............................. 14 70 5.3 Syntax .................................................. 15 71 5.4 FEAT response for REST .................................. 16 72 5.5 REST Example ............................................ 17 73 6 A Trivial Virtual File Store (TVFS) ..................... 17 74 6.1 TVFS File Names ......................................... 18 75 6.2 TVFS Pathnames .......................................... 18 76 6.3 FEAT Response for TVFS .................................. 20 77 6.4 OPTS for TVFS ........................................... 21 78 6.5 TVFS Examples ........................................... 21 79 7 Listings for Machine Processing (MLST and MLSD) ......... 22 80 7.1 Format of MLSx Requests ................................. 23 81 7.2 Format of MLSx Response ................................. 24 82 7.3 File name encoding ...................................... 26 83 7.4 Format of Facts ......................................... 27 84 7.5 Standard Facts .......................................... 28 85 7.6 System Dependent and Local Facts ........................ 36 86 7.7 MLSx Examples ........................................... 37 87 7.8 FEAT response for MLSx .................................. 49 88 7.9 OPTS parameters for MLST ................................ 51 89 8 Impact On Other FTP Commands ............................ 54 90 9 Character sets and Internationalization ................. 55 91 10 IANA Considerations ..................................... 55 92 10.1 The OS specific fact registry ........................... 55 93 10.2 The OS specific filetype registry ....................... 56 94 11 Security Considerations ................................. 56 95 12 Normative References .................................... 58 96 Acknowledgments ......................................... 59 97 Copyright ............................................... 59 98 Editors' Addresses ...................................... 60 100 1. Introduction 102 This document updates the File Transfer Protocol (FTP) [3]. Four new 103 commands are added: "SIZE", "MDTM", "MLST", and "MLSD". The existing 104 command "REST" is modified. Of those, the "SIZE" and "MDTM" 105 commands, and the modifications to "REST" have been in wide use for 106 many years. The others are new. 108 These commands allow a client to restart an interrupted transfer in 109 transfer modes not previously supported in any documented way, and to 110 obtain a directory listing in a machine friendly, predictable, 111 format. 113 An optional structure for the server's file store (NVFS) is also 114 defined, allowing servers that support such a structure to convey 115 that information to clients in a standard way, thus allowing clients 116 more certainty in constructing and interpreting pathnames. 118 2. Document Conventions 120 This document makes use of the document conventions defined in BCP14 121 [4]. That provides the interpretation of capitalized imperative 122 words like MUST, SHOULD, etc. 124 This document also uses notation defined in STD 9 [3]. In 125 particular, the terms "reply", "user", "NVFS", "file", "pathname", 126 "FTP commands", "DTP", "user-FTP process", "user-PI", "user-DTP", 127 "server-FTP process", "server-PI", "server-DTP", "mode", "type", 128 "NVT", "control connection", "data connection", and "ASCII", are all 129 used here as defined there. 131 Syntax required is defined using the Augmented BNF defined in [5]. 132 Some general ABNF definitions are required throughout the document, 133 those will be defined later in this section. At first reading, it 134 may be wise to simply recall that these definitions exist here, and 135 skip to the next section. 137 2.1. Basic Tokens 139 This document imports the core definitions given in Appendix A of 140 [5]. There definitions will be found for basic ABNF elements like 141 ALPHA, DIGIT, SP, etc. To that, the following terms are added for 142 use in this document. 144 TCHAR = VCHAR / SP / HTAB ; visible plus white space 145 RCHAR = ALPHA / DIGIT / "," / "." / ":" / "!" / 146 "@" / "#" / "$" / "%" / "^" / 147 "&" / "(" / ")" / "-" / "_" / 148 "+" / "?" / "/" / "\" / "'" / 149 DQUOTE ; <"> -- double quote character (%x22) 150 SCHAR = RCHAR / "=" ; 152 The VCHAR (from [5]), RCHAR, SCHAR, and TCHAR types give basic 153 character types from varying sub-sets of the ASCII character set for 154 use in various commands and responses. 156 token = 1*RCHAR 158 A "token" is a string whose precise meaning depends upon the context 159 in which it is used. In some cases it will be a value from a set of 160 possible values maintained elsewhere. In others it might be a string 161 invented by one party to an FTP conversation from whatever sources it 162 finds relevant. 164 Note that in ABNF, string literals are case insensitive. That 165 convention is preserved in this document, and implies that FTP 166 commands added by this specification have names that can be 167 represented in any case. That is, "MDTM" is the same as "mdtm", 168 "Mdtm" and "MdTm" etc. However note that ALPHA, in particular, is 169 case sensitive. That implies that a "token" is a case sensitive 170 value. That implication is correct, except where explicitly stated 171 to the contrary in this document, or in some other specification 172 which defines the values this document specifies be used in a 173 particular context. 175 2.2. Pathnames 177 Various FTP commands take pathnames as arguments, or return pathnames 178 in responses. When the MLST command is supported, as indicated in 179 the response to the FEAT command [6], pathnames are to be transferred 180 in one of the following two formats. 182 pathname = utf-8-name / raw 183 utf-8-name = 184 raw = 186 Which format is used is at the option of the user-PI or server-PI 187 sending the pathname. UTF-8 encodings [2] contain enough internal 188 structure that it is always, in practice, possible to determine 189 whether a UTF-8 or raw encoding has been used, in those cases where 190 it matters. While it is useful for the user-PI to be able to 191 correctly display a pathname received from the server-PI to the user, 192 it is far more important for the user-PI to be able to retain and 193 retransmit the identical pathname when required. Implementations are 194 advised against converting a UTF-8 pathname to a local charset that 195 isn't capable of representing the full Unicode character repertoire, 196 and then attempting to invert the charset translation later. Note 197 that ASCII is a subset of UTF-8. See also [1]. 199 Unless otherwise specified, the pathname is terminated by the CRLF 200 that terminates the FTP command, or by the CRLF that ends a reply. 201 Any trailing spaces preceding that CRLF form part of the name. 202 Exactly one space will precede the pathname and serve as a separator 203 from the preceding syntax element. Any additional spaces form part 204 of the pathname. See [7] for a fuller explanation of the character 205 encoding issues. All implementations supporting MLST MUST support 206 [7]. 208 Note: for pathnames transferred over a data connection, there is no 209 way to represent a pathname containing the characters CR and LF in 210 sequence, and distinguish that from the end of line indication. 211 Hence, pathnames containing the CRLF pair of characters cannot be 212 transmitted over a data connection. Data connections only contain 213 file names transmitted from server-FTP to user-FTP as the result of 214 one of the directory listing commands. Files with names containing 215 the CRLF sequence must either have that sequence converted to some 216 other form, such that the other form can be recognised and be 217 correctly converted back to CRLF, or be omitted from the listing. 219 Implementations should also beware that the control connection uses 220 Telnet NVT conventions [8], and that the Telnet IAC character, if 221 part of a pathname sent over the control connection, MUST be 222 correctly escaped as defined by the Telnet protocol. 224 NVT also distinguishes between CR, LF, and the end of line CRLF, and 225 so would permit pathnames containing the pair of characters CR and LF 226 to be correctly transmitted. However, because such a sequence cannot 227 be transmitted over a data connection (as part of the result of a 228 LIST, NLST, or MLSD command) such pathnames are best avoided. 230 Implementors should also be aware that although Telnet NVT 231 conventions are used over the control connections, Telnet option 232 negotiation MUST NOT be attempted. See section 4.1.2.12 of [9]. 234 2.2.1. Pathname Syntax 236 Except where TVFS is supported (see section 6) this specification 237 imposes no syntax upon pathnames. Nor does it restrict the character 238 set from which pathnames are created. This does not imply that the 239 NVFS is required to make sense of all possible pathnames. Server-PIs 240 may restrict the syntax of valid pathnames in their NVFS in any 241 manner appropriate to their implementation or underlying file system. 242 Similarly, a server-PI may parse the pathname, and assign meaning to 243 the components detected. 245 2.2.2. Wildcarding 247 For the commands defined in this specification, all pathnames are to 248 be treated literally. That is, for a pathname given as a parameter 249 to a command, the file whose name is identical to the pathname given 250 is implied. No characters from the pathname may be treated as 251 special or "magic", thus no pattern matching (other than for exact 252 equality) between the pathname given and the files present in the 253 NVFS of the Server-FTP is permitted. 255 Clients that desire some form of pattern matching functionality must 256 obtain a listing of the relevant directory, or directories, and 257 implement their own file name selection procedures. 259 2.3. Times 261 The syntax of a time value is: 263 time-val = 14DIGIT [ "." 1*DIGIT ] 265 The leading, mandatory, fourteen digits are to be interpreted as, in 266 order from the leftmost, four digits giving the year, with a range of 267 1000--9999, two digits giving the month of the year, with a range of 268 01--12, two digits giving the day of the month, with a range of 269 01--31, two digits giving the hour of the day, with a range of 270 00--23, two digits giving minutes past the hour, with a range of 271 00--59, and finally, two digits giving seconds past the minute, with 272 a range of 00--60 (with 60 being used only at a leap second). Years 273 in the tenth century, and earlier, cannot be expressed. This is not 274 considered a serious defect of the protocol. 276 The optional digits, which are preceded by a period, give decimal 277 fractions of a second. These may be given to whatever precision is 278 appropriate to the circumstance, however implementations MUST NOT add 279 precision to time-vals where that precision does not exist in the 280 underlying value being transmitted. 282 Symbolically, a time-val may be viewed as 284 YYYYMMDDHHMMSS.sss 286 The "." and subsequent digits ("sss") are optional. However the "." 287 MUST NOT appear unless at least one following digit also appears. 289 Time values are always represented in UTC (GMT), and in the Gregorian 290 calendar regardless of what calendar may have been in use at the date 291 and time indicated at the location of the server-PI. 293 The technical differences between GMT, TAI, UTC, UT1, UT2, etc, are 294 not considered here. A server-FTP process should always use the same 295 time reference, so the times it returns will be consistent. Clients 296 are not expected to be time synchronized with the server, so the 297 possible difference in times that might be reported by the different 298 time standards is not considered important. 300 2.4. Server Replies 302 Section 4.2 of [3] defines the format and meaning of replies by the 303 server-PI to FTP commands from the user-PI. Those reply conventions 304 are used here without change. 306 error-response = error-code SP *TCHAR CRLF 307 error-code = ("4" / "5") 2DIGIT 309 Implementors should note that the ABNF syntax (which was not used in 310 [3]) used in this document, and other FTP related documents, 311 sometimes shows replies using the one line format. Unless otherwise 312 explicitly stated, that is not intended to imply that multi-line 313 responses are not permitted. Implementors should assume that, unless 314 stated to the contrary, any reply to any FTP command (including QUIT) 315 may be of the multi-line format described in [3]. 317 Throughout this document, replies will be identified by the three 318 digit code that is their first element. Thus the term "500 reply" 319 means a reply from the server-PI using the three digit code "500". 321 2.5. Interpreting Examples 323 In the examples of FTP dialogs presented in this document, lines that 324 begin "C> " were sent over the control connection from the user-PI to 325 the server-PI, lines that begin "S> " were sent over the control 326 connection from the server-PI to the user-PI, and each sequence of 327 lines that begin "D> " was sent from the server-PI to the user-PI 328 over a data connection created just to send those lines and closed 329 immediately after. No examples here show data transferred over a 330 data connection from the client to the server. In all cases, the 331 prefixes shown above, including the one space, have been added for 332 the purposes of this document, and are not a part of the data 333 exchanged between client and server. 335 3. File Modification Time (MDTM) 337 The FTP command, MODIFICATION TIME (MDTM), can be used to determine 338 when a file in the server NVFS was last modified. This command has 339 existed in many FTP servers for many years, as an adjunct to the REST 340 command for STREAM mode, thus is widely available. However, where 341 supported, the "modify" fact which can be provided in the result from 342 the new MLST command is recommended as a superior alternative. 344 When attempting to restart a RETRieve, if the User-FTP makes use of 345 the MDTM command, or "modify" fact, it can check and see if the 346 modification time of the source file is more recent than the 347 modification time of the partially transferred file. If it is, then 348 most likely the source file has changed and it would be unsafe to 349 restart the previously incomplete file transfer. 351 Because the User and server FTPs' clocks are not necessarily 352 synchronised, User FTPs intending to use this method should usually 353 obtain the modification time of the file from the server before the 354 initial RETRieval, and compare that with the modification time before 355 a RESTart. If they differ, the files may have changed, and RESTart 356 would be inadvisable. Where this is not possible, the User FTP 357 should make sure to allow for possible clock skew when comparing 358 times. 360 When attempting to restart a STORe, the User FTP can use the MDTM 361 command to discover the modification time of the partially 362 transferred file. If it is older than the modification time of the 363 file that is about to be STORed, then most likely the source file has 364 changed and it would be unsafe to restart the file transfer. 366 Note that using MLST (described below) where available, can provide 367 this information, and much more, thus giving an even better 368 indication that a file has changed, and that restarting a transfer 369 would not give valid results. 371 Note that this is applicable to any RESTart attempt, regardless of 372 the mode of the file transfer. 374 3.1. Syntax 376 The syntax for the MDTM command is: 378 mdtm = "MdTm" SP pathname CRLF 380 As with all FTP commands, the "MDTM" command label is interpreted in 381 a case insensitive manner. 383 The "pathname" specifies an object in the NVFS which may be the 384 object of a RETR command. Attempts to query the modification time of 385 files that exist but are unable to be retrieved may generate an 386 error-response, or can result in a positive response carrying a time- 387 val with an unspecified value, the choice being made by the server- 388 PI. 390 The server-PI will respond to the MDTM command with a 213 reply 391 giving the last modification time of the file whose pathname was 392 supplied, or a 550 reply if the file does not exist, the modification 393 time is unavailable, or some other error has occurred. 395 mdtm-response = "213" SP time-val CRLF / 396 error-response 398 Note that when the 213 response is issued, that is, when there is no 399 error, the format MUST be exactly as specified. Multi-line responses 400 are not permitted. 402 3.2. Error responses 404 Where the command is correctly parsed, but the modification time is 405 not available, either because the pathname identifies no existing 406 entity, or because the information is not available for the entity 407 named, then a 550 reply should be sent. Where the command cannot be 408 correctly parsed, a 500 or 501 reply should be sent, as specified in 409 [3]. Various 4xy replies are also possible in appropriate 410 circumstances. 412 3.3. FEAT response for MDTM 414 When replying to the FEAT command [6], an FTP server process that 415 supports the MDTM command MUST include a line containing the single 416 word "MDTM". This MAY be sent in upper or lower case, or a mixture 417 of both (it is case insensitive) but SHOULD be transmitted in upper 418 case only. That is, the response SHOULD be 420 C> Feat 421 S> 211- 422 S> ... 423 S> MDTM 424 S> ... 425 S> 211 End 427 The ellipses indicate place holders where other features may be 428 included, and are not required. The one space indentation of the 429 feature lines is mandatory [6]. 431 3.4. MDTM Examples 433 If we assume the existence of three files, A B and C, a directory D, 434 two files with names that end with the string "ile6", and no other 435 files at all, then the MDTM command may behave as indicated. The 436 "C>" lines are commands from user-PI to server-PI, the "S>" lines are 437 server-PI replies. 439 C> MDTM A 440 S> 213 19980615100045.014 441 C> MDTM B 442 S> 213 19980615100045.014 443 C> MDTM C 444 S> 213 19980705132316 445 C> MDTM D 446 S> 550 D is not retrievable 447 C> MDTM E 448 S> 550 No file named "E" 449 C> mdtm file6 450 S> 213 19990929003355 451 C> MdTm 19990929043300 File6 452 S> 213 19991005213102 453 C> MdTm 19990929043300 file6 454 S> 550 19990929043300 file6: No such file or directory. 456 From that we can conclude that both A and B were last modified at the 457 same time (to the nearest millisecond), and that C was modified 20 458 days and several hours later. 460 The times are in GMT, so file A was modified on the 15th of June, 461 1998, at approximately 11am in London (summer time was then in 462 effect), or perhaps at 8pm in Melbourne, Australia, or at 6am in New 463 York. All of those represent the same absolute time of course. The 464 location where the file was modified, and consequently the local wall 465 clock time at that location, is not available. 467 There is no file named "E" in the current directory, but there are 468 files named both "file6" and "19990929043300 File6". The 469 modification times of those files were obtained. There is no file 470 named "19990929043300 file6". 472 4. File SIZE 474 The FTP command, SIZE OF FILE (SIZE), is used to obtain the transfer 475 size of a file from the server-FTP process. That is, the exact 476 number of octets (8 bit bytes) which would be transmitted over the 477 data connection should that file be transmitted. This value will 478 change depending on the current STRUcture, MODE and TYPE of the data 479 connection, or a data connection which would be created were one 480 created now. Thus, the result of the SIZE command is dependent on 481 the currently established STRU, MODE and TYPE parameters. 483 The SIZE command returns how many octets would be transferred if the 484 file were to be transferred using the current transfer structure, 485 mode and type. This command is normally used in conjunction with the 486 RESTART (REST) command when STORing a file to a remote server in 487 STREAM mode, to determine the restart point. The server-PI might 488 need to read the partially transferred file, do any appropriate 489 conversion, and count the number of octets that would be generated 490 when sending the file in order to correctly respond to this command. 491 Estimates of the file transfer size MUST NOT be returned, only 492 precise information is acceptable. 494 4.1. Syntax 496 The syntax of the SIZE command is: 498 size = "Size" SP pathname CRLF 500 The server-PI will respond to the SIZE command with a 213 reply 501 giving the transfer size of the file whose pathname was supplied, or 502 an error response if the file does not exist, the size is 503 unavailable, or some other error has occurred. The value returned is 504 in a format suitable for use with the RESTART (REST) command for mode 505 STREAM, provided the transfer mode and type are not altered. 507 size-response = "213" SP 1*DIGIT CRLF / 508 error-response 510 Note that when the 213 response is issued, that is, when there is no 511 error, the format MUST be exactly as specified. Multi-line responses 512 are not permitted. 514 4.2. Error responses 516 Where the command is correctly parsed, but the size is not available, 517 perhaps because the pathname identifies no existing entity, or 518 because the entity named cannot be transferred in the current MODE 519 and TYPE (or at all), then a 550 reply should be sent. Where the 520 command cannot be correctly parsed, a 500 or 501 reply should be 521 sent, as specified in [3]. The presence of the 550 error response to 522 a SIZE command MUST NOT be taken by the client as an indication that 523 the file can not be transferred in the current MODE and TYPE. A 524 server may generate this error for other reasons -- for instance if 525 the processing overhead is considered too great. Various 4xy replies 526 are also possible in appropriate circumstances. 528 4.3. FEAT response for SIZE 530 When replying to the FEAT command [6], an FTP server process that 531 supports the SIZE command MUST include a line containing the single 532 word "SIZE". This word is case insensitive, and MAY be sent in any 533 mixture of upper or lower case, however it SHOULD be sent in upper 534 case. That is, the response SHOULD be 536 C> FEAT 537 S> 211- 538 S> ... 539 S> SIZE 540 S> ... 541 S> 211 END 543 The ellipses indicate place holders where other features may be 544 included, and are not required. The one space indentation of the 545 feature lines is mandatory [6]. 547 4.4. Size Examples 549 Consider a text file "Example" stored on a Unix(TM) server where each 550 end of line is represented by a single octet. Assume the file 551 contains 112 lines, and 1830 octets total. Then the SIZE command 552 would produce: 554 C> TYPE I 555 S> 200 Type set to I. 556 C> size Example 557 S> 213 1830 558 C> TYPE A 559 S> 200 Type set to A. 560 C> Size Example 561 S> 213 1942 563 Notice that with TYPE=A the SIZE command reports an extra 112 octets. 564 Those are the extra octets that need to be inserted, one at the end 565 of each line, to provide correct end of line semantics for a transfer 566 using TYPE=A. Other systems might need to make other changes to the 567 transfer format of files when converting between TYPEs and MODEs. 568 The SIZE command takes all of that into account. 570 Since calculating the size of a file with this degree of precision 571 may take considerable effort on the part of the server-PI, user-PIs 572 should not used this command unless this precision is essential (such 573 as when about to restart an interrupted transfer). For other uses, 574 the "Size" fact of the MLST command (see section 7.5.7) ought be 575 requested. 577 5. Restart of Interrupted Transfer (REST) 579 To avoid having to resend the entire file if the file is only 580 partially transferred, both sides need some way to be able to agree 581 on where in the data stream to restart the data transfer. 583 The FTP specification [3] includes three modes of data transfer, 584 Stream, Block and Compressed. In Block and Compressed modes, the 585 data stream that is transferred over the data connection is 586 formatted, allowing the embedding of restart markers into the stream. 587 The sending DTP can include a restart marker with whatever 588 information it needs to be able to restart a file transfer at that 589 point. The receiving DTP can keep a list of these restart markers, 590 and correlate them with how the file is being saved. To restart the 591 file transfer, the receiver just sends back that last restart marker, 592 and both sides know how to resume the data transfer. Note that there 593 are some flaws in the description of the restart mechanism in RFC 959 594 [3]. See section 4.1.3.4 of RFC 1123 [9] for the corrections. 596 5.1. Restarting in STREAM Mode 598 In Stream mode, the data connection contains just a stream of 599 unformatted octets of data. Explicit restart markers thus cannot be 600 inserted into the data stream, they would be indistinguishable from 601 data. For this reason, the FTP specification [3] did not provide the 602 ability to do restarts in stream mode. However, there is not really 603 a need to have explicit restart markers in this case, as restart 604 markers can be implied by the octet offset into the data stream. 606 Because the data stream defines the file in STREAM mode, a different 607 data stream would represent a different file. Thus, an offset will 608 always represent the same position within a file. On the other hand, 609 in other modes than STREAM, the same file can be transferred using 610 quite different octet sequences, and yet be reconstructed into the 611 one identical file. Thus an offset into the data stream in transfer 612 modes other than STREAM would not give an unambiguous restart point. 614 If the data representation TYPE is IMAGE, and the STRUcture is File, 615 for many systems the file will be stored exactly in the same format 616 as it is sent across the data connection. It is then usually very 617 easy for the receiver to determine how much data was previously 618 received, and notify the sender of the offset where the transfer 619 should be restarted. In other representation types and structures 620 more effort will be required, but it remains always possible to 621 determine the offset with finite, but perhaps non-negligible, effort. 622 In the worst case an FTP process may need to open a data connection 623 to itself, set the appropriate transfer type and structure, and 624 actually transmit the file, counting the transmitted octets. 626 If the user-FTP process is intending to restart a retrieve, it will 627 directly calculate the restart marker, and send that information in 628 the RESTart command. However, if the user-FTP process is intending 629 to restart sending the file, it needs to be able to determine how 630 much data was previously sent, and correctly received and saved. A 631 new FTP command is needed to get this information. This is the 632 purpose of the SIZE command, as documented in section 4. 634 5.2. Error Recovery and Restart 636 STREAM MODE transfers with FILE STRUcture may be restarted even 637 though no restart marker has been transferred in addition to the data 638 itself. This is done by using the SIZE command, if needed, in 639 combination with the RESTART (REST) command, and one of the standard 640 file transfer commands. 642 When using TYPE ASCII or IMAGE, the SIZE command will return the 643 number of octets that would actually be transferred if the file were 644 to be sent between the two systems. I.e. with type IMAGE, the SIZE 645 normally would be the number of octets in the file. With type ASCII, 646 the SIZE would be the number of octets in the file including any 647 modifications required to satisfy the TYPE ASCII CR-LF end of line 648 convention. 650 5.3. Syntax 652 The syntax for the REST command when the current transfer mode is 653 STREAM is: 655 rest = "Rest" SP 1*DIGIT CRLF 657 The numeric value gives the number of octets of the immediately 658 following transfer to not actually send, effectively causing the 659 transmission to be restarted at a later point. A value of zero 660 effectively disables restart, causing the entire file to be 661 transmitted. The server-PI will respond to the REST command with a 662 350 reply, indicating that the REST parameter has been saved, and 663 that another command, which should be either RETR or STOR, should 664 then follow to complete the restart. 666 rest-response = "350" SP *TCHAR CRLF / 667 error-response 669 Server-FTP processes may permit transfer commands other than RETR and 670 STOR, such as APPE and STOU, to complete a restart, however, this is 671 not recommended. STOU (store unique) is undefined in this usage, as 672 storing the remainder of a file into a unique file name is rarely 673 going to be useful. If APPE (append) is permitted, it MUST act 674 identically to STOR when a restart marker has been set. That is, in 675 both cases, octets from the data connection are placed into the file 676 at the location indicated by the restart marker value. 678 The REST command is intended to complete a failed transfer. Use with 679 RETR is comparatively well defined in all cases, as the client bears 680 the responsibility of merging the retrieved data with the partially 681 retrieved file. If it chooses to use the data obtained other than to 682 complete an earlier transfer, or if it chooses to re-retrieve data 683 that had been retrieved before, that is its choice. With STOR, 684 however, the server must insert the data into the file named. The 685 results are undefined if a client uses REST to do other than restart 686 to complete a transfer of a file which had previously failed to 687 completely transfer. In particular, if the restart marker set with a 688 REST command is not at the end of the data currently stored at the 689 server, as reported by the server, or if insufficient data are 690 provided in a STOR that follows a REST to extend the destination file 691 to at least its previous size, then the effects are undefined. 693 The REST command must be the last command issued before the data 694 transfer command which is to cause a restarted rather than complete 695 file transfer. The effect of issuing a REST command at any other 696 time is undefined. The server-PI may react to a badly positioned 697 REST command by issuing an error response to the following command, 698 not being a restartable data transfer command, or it may save the 699 restart value and apply it to the next data transfer command, or it 700 may silently ignore the inappropriate restart attempt. Because of 701 this, a user-PI that has issued a REST command, but which has not 702 successfully transmitted the following data transfer command for any 703 reason, should send another REST command before the next data 704 transfer command. If that transfer is not to be restarted, then 705 "REST 0" should be issued. 707 An error-response will follow a REST command only when the server 708 does not implement the command, or the restart marker value is 709 syntactically invalid for the current transfer mode. That is, in 710 STREAM mode, if something other than one or more digits appears in 711 the parameter to the REST command. Any other errors, including such 712 problems as restart marker out of range, should be reported when the 713 following transfer command is issued. Such errors will cause that 714 transfer request to be rejected with an error indicating the invalid 715 restart attempt. 717 5.4. FEAT response for REST 719 Where a server-FTP process supports RESTart in STREAM mode, as 720 specified here, it MUST include in the response to the FEAT command 721 [6], a line containing exactly the string "REST STREAM". This string 722 is not case sensitive, but SHOULD be transmitted in upper case. 723 Where REST is not supported at all, or supported only in block or 724 compressed modes, the REST line MUST NOT be included in the FEAT 725 response. Where required, the response SHOULD be 727 C> feat 728 S> 211- 729 S> ... 730 S> REST STREAM 731 S> ... 732 S> 211 end 734 The ellipses indicate place holders where other features may be 735 included, and are not required. The one space indentation of the 736 feature lines is mandatory [6]. 738 5.5. REST Example 740 Assume that the transfer of a largish file has previously been 741 interrupted after 802816 octets had been received, that the previous 742 transfer was with TYPE=I, and that it has been verified that the file 743 on the server has not since changed. 745 C> TYPE I 746 S> 200 Type set to I. 747 C> PORT 127,0,0,1,15,107 748 S> 200 PORT command successful. 749 C> REST 802816 750 S> 350 Restarting at 802816. Send STORE or RETRIEVE 751 C> RETR cap60.pl198.tar 752 S> 150 Opening BINARY mode data connection 753 [...] 754 S> 226 Transfer complete. 756 6. A Trivial Virtual File Store (TVFS) 758 Traditionally, FTP has placed almost no constraints upon the file 759 store (NVFS) provided by a server. This specification does not alter 760 that. However, it has become common for servers to attempt to 761 provide at least file system naming conventions modeled loosely upon 762 those of the UNIX(TM) file system. That is, a tree structured file 763 system, built of directories, each of which can contain other 764 directories, or other kinds of files, or both. Each file and 765 directory has a name relative to the directory that contains it, 766 except for the directory at the root of the tree, which is contained 767 in no other directory, and hence has no name of its own. 769 That which has so far been described is perfectly consistent with the 770 standard FTP NVFS and access mechanisms. The "CWD" command is used 771 to move from one directory to an embedded directory. "CDUP" may be 772 provided to return to the parent directory, and the various file 773 manipulation commands ("RETR", "STOR", the rename commands, etc) are 774 used to manipulate files within the current directory. 776 However, it is often useful to be able to reference files other than 777 by changing directories, especially as FTP provides no guaranteed 778 mechanism to return to a previous directory. The Trivial Virtual 779 File Store (TVFS), if implemented, provides that mechanism. 781 6.1. TVFS File Names 783 Where a server implements the TVFS, no elementary file name shall 784 contain the character "/". Where the underlying natural file store 785 permits files, or directories, to contain the "/" character in their 786 names, a server-PI implementing TVFS must encode that character in 787 some manner whenever file or directory names are being returned to 788 the user-PI, and reverse that encoding whenever such names are being 789 accepted from the user-PI. 791 The encoding method to be used is not specified here. Where some 792 other character is illegal in file and directory names in the 793 underlying file store, a simple transliteration may be sufficient. 794 Where there is no suitable substitute character a more complex 795 encoding scheme, possibly using an escape character, is likely to be 796 required. 798 With the one exception of the unnamed root directory, a TVFS file 799 name may not be empty. That is, all other file names contain at 800 least one character. 802 With the sole exception of the "/" character, any valid IS10646 803 character [11] may be used in a TVFS file name. When transmitted, 804 file name characters are encoded using the UTF-8 encoding [2]. Note 805 that the two character sequence CR LF occurring in a file name will 806 make that name impossible to transmit over a data connection. 807 Consequently, it should be avoided, or if that is impossible to 808 achieve, it MUST be encoded in some reversible way. 810 6.2. TVFS Pathnames 812 A TVFS "Pathname" combines the file or directory name of a target 813 file or directory, with the directory names of zero or more enclosing 814 directories, so as to allow the target file or directory to be 815 referenced other than when the server's "current working directory" 816 is the directory directly containing the target file or directory. 818 By definition, every TVFS file or directory name is also a TVFS 819 pathname. Such a pathname is valid to reference the file from the 820 directory containing the name, that is, when that directory is the 821 server-FTP's current working directory. 823 Other TVFS pathnames are constructed by prefixing a pathname by a 824 name of a directory from which the path is valid, and separating the 825 two with the "/" character. Such a pathname is valid to reference 826 the file or directory from the directory containing the newly added 827 directory name. 829 Where a pathname has been extended to the point where the directory 830 added is the unnamed root directory, the pathname will begin with the 831 "/" character. Such a path is known as a fully qualified pathname. 832 Fully qualified paths may, obviously, not be further extended, as, by 833 definition, no directory contains the root directory. Being unnamed, 834 it cannot be represented in any other directory. A fully qualified 835 pathname is valid to reference the named file or directory from any 836 location (that is, regardless of what the current working directory 837 may be) in the virtual file store. 839 Any pathname which is not a fully qualified pathname may be referred 840 to as a "relative pathname" and will only correctly reference the 841 intended file when the current working directory of the server-FTP is 842 a directory from which the relative pathname is valid. 844 As a special case, the pathname "/" is defined to be a fully 845 qualified pathname referring to the root directory. That is, the 846 root directory does not have a directory (or file) name, but does 847 have a pathname. This special pathname may be used only as is as a 848 reference to the root directory. It may not be combined with other 849 pathnames using the rules above, as doing so would lead to a pathname 850 containing two consecutive "/" characters, which is an undefined 851 sequence. 853 6.2.1. Notes 855 + It is not required, or expected, that there be only one fully 856 qualified pathname that will reference any particular file or 857 directory. 858 + As a caveat, though the TVFS file store is basically tree 859 structured, there is no requirement that any file or directory 860 have only one parent directory. 861 + As defined, no TVFS pathname will ever contain two consecutive 862 "/" characters. Such a name is not illegal however, and may be 863 defined by the server for any purpose that suits it. Clients 864 implementing this specification should not assume any semantics 865 at all for such names. 866 + Similarly, other than the special case path that refers to the 867 root directory, no TVFS pathname constructed as defined here will 868 ever end with the "/" character. Such names are also not 869 illegal, but are undefined. 870 + While any legal IS10646 character is permitted to occur in a TVFS 871 file or directory name, other than "/", server FTP 872 implementations are not required to support all possible IS10646 873 characters. The subset supported is entirely at the discretion 874 of the server. The case (where it exists) of the characters that 875 make up file, directory, and pathnames may be significant. 876 Unless determined otherwise by means unspecified here, clients 877 should assume that all such names are comprised of characters 878 whose case is significant. Servers are free to treat case (or 879 any other attribute) of a name as irrelevant, and hence map two 880 names which appear to be distinct onto the same underlying file. 881 + There are no defined "magic" names, like ".", ".." or "C:". 882 Servers may implement such names, with any semantics they choose, 883 but are not required to do so. 884 + TVFS imposes no particular semantics or properties upon files, 885 guarantees no access control schemes, or any of the other common 886 properties of a file store. Only the naming scheme is defined. 888 6.3. FEAT Response for TVFS 890 In response to the FEAT command [6] a server that wishes to indicate 891 support for the TVFS as defined here will include a line that begins 892 with the four characters "TVFS" (in any case, or mixture of cases, 893 upper case is not required). Servers SHOULD send upper case. 895 Such a response to the FEAT command MUST NOT be returned unless the 896 server implements TVFS as defined here. 898 Later specifications may add to the TVFS definition. Such additions 899 should be notified by means of additional text appended to the TVFS 900 feature line. Such specifications, if any, will define the extra 901 text. 903 Until such a specification is defined, servers should not include 904 anything after "TVFS" in the TVFS feature line. Clients, however, 905 should be prepared to deal with arbitrary text following the four 906 defined characters, and simply ignore it if unrecognized. 908 A typical response to the FEAT command issued by a server 909 implementing only this specification would be: 911 C> feat 912 S> 211- 913 S> ... 914 S> TVFS 915 S> ... 916 S> 211 end 918 The ellipses indicate place holders where other features may be 919 included, and are not required. The one space indentation of the 920 feature lines is mandatory [6], and is not counted as one of the 921 first four characters for the purposes of this feature listing. 923 The TVFS feature adds no new commands to the FTP command repertoire. 925 6.4. OPTS for TVFS 927 There are no options in this TVFS specification, and hence there is 928 no OPTS command defined. 930 6.5. TVFS Examples 932 Assume a TVFS file store is comprised of a root directory, which 933 contains two directories (A and B) and two non-directory files (X and 934 Y). The A directory contains two directories (C and D) and one other 935 file (Z). The B directory contains just two non-directory files (P 936 and Q) and the C directory also two non-directory files (also named P 937 and Q, by chance). The D directory is empty, that is, contains no 938 files or directories. 939 This structure may depicted graphically as... 941 (unnamed root) 942 / | \ \ 943 / | \ \ 944 A X B Y 945 /|\ / \ 946 / | \ / \ 947 C D Z P Q 948 / \ 949 / \ 950 P Q 952 Given this structure, the following fully qualified pathnames exist. 954 / 955 /A 956 /B 957 /X 958 /Y 959 /A/C 960 /A/D 961 /A/Z 962 /A/C/P 963 /A/C/Q 964 /B/P 965 /B/Q 967 It is clear that none of the paths / /A /B or /A/D refer to the same 968 directory, as the contents of each is different. Nor do any of / /A 969 /A/C or /A/D. However /A/C and /B might be the same directory, there 970 is insufficient information given to tell. Any of the other 971 pathnames (/X /Y /A/Z /A/C/P /A/C/Q /B/P and /B/Q) may refer to the 972 same underlying files, in almost any combination. 974 If the current working directory of the server-FTP is /A then the 975 following pathnames, in addition to all the fully qualified 976 pathnames, are valid 978 C 979 D 980 Z 981 C/P 982 C/Q 984 These all refer to the same files or directories as the corresponding 985 fully qualified path with "/A/" prepended. 987 That those pathnames all exist does not imply that the TVFS sever 988 will necessarily grant any kind of access rights to the named paths, 989 or that access to the same file via different pathnames will 990 necessarily be granted equal rights. 992 None of the following relative paths are valid when the current 993 directory is /A 995 A 996 B 997 X 998 Y 999 B/P 1000 B/Q 1001 P 1002 Q 1004 Any of those could be made valid by changing the server-FTP's current 1005 working directory to the appropriate directory. Note that the paths 1006 "P" and "Q" might refer to different files depending upon which 1007 directory is selected to cause those to become valid TVFS relative 1008 paths. 1010 7. Listings for Machine Processing (MLST and MLSD) 1012 The MLST and MLSD commands are intended to standardize the file and 1013 directory information returned by the Server-FTP process. These 1014 commands differ from the LIST command in that the format of the 1015 replies is strictly defined although extensible. 1017 Two commands are defined, MLST which provides data about exactly the 1018 object named on its command line, and no others. MLSD on the other 1019 hand will list the contents of a directory if a directory is named, 1020 otherwise a 501 reply will be returned. In either case, if no object 1021 is named, the current directory is assumed. That will cause MLST to 1022 send a one line response, describing the current directory itself, 1023 and MLSD to list the contents of the current directory. 1025 In the following, the term MLSx will be used wherever either MLST or 1026 MLSD may be inserted. 1028 The MLST and MLSD commands also extend the FTP protocol as presented 1029 in RFC 959 [3] and RFC 1123 [9] to allow that transmission of 8-bit 1030 data over the control connection. Note this is not specifying 1031 character sets which are 8-bit, but specifying that FTP 1032 implementations are to specifically allow the transmission and 1033 reception of 8-bit bytes, with all bits significant, over the control 1034 connection. That is, all 256 possible octet values are permitted. 1035 The MLSx command allows both UTF-8/Unicode and "raw" forms as 1036 arguments, and in responses both to the MLST and MLSD commands, and 1037 all other FTP commands which take pathnames as arguments. 1039 7.1. Format of MLSx Requests 1041 The MLST and MLSD commands each allow a single optional argument. 1042 This argument may be either a directory name or, for MLST only, a 1043 file name. For these purposes, a "file name" is the name of any 1044 entity in the server NVFS which is not a directory. Where TVFS is 1045 supported, any TVFS relative pathname valid in the current working 1046 directory, or any TVFS fully qualified pathname, may be given. If a 1047 directory name is given then MLSD must return a listing of the 1048 contents of the named directory, otherwise it issues a 501 reply, and 1049 does not open a data connection. In all cases for MLST, a single set 1050 of fact lines (usually a single fact line) containing the information 1051 about the named file or directory shall be returned over the control 1052 connection, without opening a data connection. 1054 If no argument is given then MLSD must return a listing of the 1055 contents of the current working directory, and MLST must return a 1056 listing giving information about the current working directory 1057 itself. For these purposes, the contents of a directory are whatever 1058 file or directory names (not pathnames) the server-PI will allow to 1059 be referenced when the current working directory is the directory 1060 named, and which the server-PI desires to reveal to the user-PI. 1061 Note that omitting the argument is the only defined way to obtain a 1062 listing of the current directory, unless a pathname that represents 1063 the directory happens to be known. In particular, there is no 1064 defined shorthand name for the current directory. This does not 1065 prohibit any particular server-PI implementing such a shorthand. 1067 No title, header, or summary, lines, or any other formatting, other 1068 than as is specified below, is ever returned in the output of an MLST 1069 or MLSD command. 1071 If the Client-FTP sends an invalid argument, the Server-FTP MUST 1072 reply with an error code of 501. 1074 The syntax for the MLSx command is: 1076 mlst = "MLst" [ SP pathname ] CRLF 1077 mlsd = "MLsD" [ SP pathname ] CRLF 1079 7.2. Format of MLSx Response 1081 The format of a response to an MLSx command is as follows: 1083 mlst-response = control-response / error-response 1084 mlsd-response = ( initial-response final-response ) / 1085 error-response 1087 control-response = "250-" [ response-message ] CRLF 1088 1*( SP entry CRLF ) 1089 "250" [ SP response-message ] CRLF 1091 initial-response = "150" [ SP response-message ] CRLF 1092 final-response = "226" SP response-message CRLF 1094 response-message = *TCHAR 1096 data-response = *( entry CRLF ) 1098 entry = [ facts ] SP pathname 1099 facts = 1*( fact ";" ) 1100 fact = factname "=" value 1101 factname = "Size" / "Modify" / "Create" / 1102 "Type" / "Unique" / "Perm" / 1103 "Lang" / "Media-Type" / "CharSet" / 1104 os-depend-fact / local-fact 1105 os-depend-fact = "." token 1106 local-fact = "X." token 1107 value = *SCHAR 1109 Upon receipt of a MLSx command, the server will verify the parameter, 1110 and if invalid return an error-response. For this purpose, the 1111 parameter should be considered to be invalid if the client issuing 1112 the command does not have permission to perform the requested 1113 operation. 1115 If valid, then for an MLST command, the server-PI will send the first 1116 (leading) line of the control response, the entry for the pathname 1117 given, or the current directory if no pathname was provided, and the 1118 terminating line. Normally exactly one entry would be returned, more 1119 entries are permitted only when required to represent a file that is 1120 to have multiple "Type" facts returned. In this case, the pathname 1121 component of every response MUST be identical. 1123 Note that for MLST the fact set is preceded by a space. That is 1124 provided to guarantee that the fact set cannot be accidentally 1125 interpreted as the terminating line of the control response, but is 1126 required even when that would not be possible. Exactly one space 1127 exists between the set of facts and the pathname. Where no facts are 1128 present, there will be exactly two leading spaces before the 1129 pathname. No spaces are permitted in the facts, any other spaces in 1130 the response are to be treated as being a part of the pathname. 1132 If the command was an MLSD command, the server will open a data 1133 connection as indicated in section 3.2 of RFC959 [3]. If that fails, 1134 the server will return an error-response. If all is OK, the server 1135 will return the initial-response, send the appropriate data-response 1136 over the new data connection, close that connection, and then send 1137 the final-response over the control connection. The grammar above 1138 defines the format for the data-response, which defines the format of 1139 the data returned over the data connection established. 1141 The data connection opened for a MLSD response shall be a connection 1142 as if the "TYPE L 8", "MODE S", and "STRU F" commands had been given, 1143 whatever FTP transfer type, mode and structure had actually been set, 1144 and without causing those settings to be altered for future commands. 1145 That is, this transfer type shall be set for the duration of the data 1146 connection established for this command only. While the content of 1147 the data sent can be viewed as a series of lines, implementations 1148 should note that there is no maximum line length defined. 1149 Implementations should be prepared to deal with arbitrarily long 1150 lines. 1152 The facts part of the specification would contain a series of "file 1153 facts" about the file or directory named on the same line. Typical 1154 information to be presented would include file size, last 1155 modification time, creation time, a unique identifier, and a 1156 file/directory flag. 1158 The complete format for a successful reply to the MLSD command would 1159 be: 1161 facts SP pathname CRLF 1162 facts SP pathname CRLF 1163 facts SP pathname CRLF 1164 ... 1166 Note that the format is intended for machine processing, not human 1167 viewing, and as such the format is very rigid. Implementations MUST 1168 NOT vary the format by, for example, inserting extra spaces for 1169 readability, replacing spaces by tabs, including header or title 1170 lines, or inserting blank lines, or in any other way alter this 1171 format. Exactly one space is always required after the set of facts 1172 (which may be empty). More spaces may be present on a line if, and 1173 only if, the pathname presented contains significant spaces. The set 1174 of facts must not contain any spaces anywhere inside it. Facts 1175 should be provided in each output line only if they both provide 1176 relevant information about the file named on the same line, and they 1177 are in the set requested by the user-PI. See section 7.9 (page 51). 1178 There is no requirement that the same set of facts be provided for 1179 each file, or that the facts presented occur in the same order for 1180 each file. 1182 7.2.1. Error responses to MLSx commands 1184 Many of the 4xy and 5xy responses defined in section 4.2 of RFC959 1185 [3] are possible in response to the MLST and MLSD commands. In 1186 particular, syntax errors can generate 500 or 501 replies. Giving a 1187 pathname that exists but is not a directory as the argument to a MLSD 1188 command generates a 501 reply. Giving a name which does not exist, 1189 or for which access permission (to obtain directory information as 1190 requested) is not granted will elicit a 550 reply. Other replies 1191 (530, 553, 503, 504, and any of the 4xy replies) are also possible in 1192 appropriate circumstances. 1194 7.3. File name encoding 1196 An FTP implementation supporting the MLSx commands must be 8-bit 1197 clean. This is necessary in order to transmit UTF-8 encoded file 1198 names. This specification recommends the use of UTF-8 encoded file 1199 names. FTP implementations SHOULD use UTF-8 whenever possible to 1200 encourage the maximum inter-operability. 1202 File names are not restricted to UTF-8, however treatment of 1203 arbitrary character encodings is not specified by this standard. 1204 Applications are encouraged to treat non-UTF-8 encodings of file 1205 names as octet sequences. 1207 Note that this encoding is unrelated to that of the contents of the 1208 file, even if the file contains character data. 1210 Further information about file name encoding for FTP may be found in 1211 "Internationalization of the File Transfer Protocol" [7]. 1213 7.3.1. Notes about the File name 1215 The file name returned in the MLST response should be the same name 1216 as was specified in the MLST command, or, where TVFS is supported, a 1217 fully qualified TVFS path naming the same file. Where no argument 1218 was given to the MLST command, the server-PI may either include an 1219 empty file name in the response, or it may supply a name that refers 1220 to the current directory, if such a name is available. Where TVFS is 1221 supported, a fully qualified pathname of the current directory SHOULD 1222 be returned. 1224 File names returned in the output from an MLSD command SHOULD be 1225 unqualified names within the directory named, or the current 1226 directory if no argument was given. That is, the directory named in 1227 the MLSD command SHOULD NOT appear as a component of the file names 1228 returned. 1230 If the server-FTP process is able, and the "type" fact is being 1231 returned, it MAY return in the MLSD response, an entry whose type is 1232 "cdir", which names the directory from which the contents of the 1233 listing were obtained. Where TVFS is supported, the name MAY be the 1234 fully qualified pathname of the directory, or MAY be any other 1235 pathname which is valid to refer to that directory from the current 1236 working directory of the server-FTP. Where more than one name 1237 exists, multiple of these entries may be returned. In a sense, the 1238 "cdir" entry can be viewed as a heading for the MLSD output. 1239 However, it is not required to be the first entry returned, and may 1240 occur anywhere within the listing. 1242 When TVFS is supported, a user-PI can refer to any file or directory 1243 in the listing by combining a type "cdir" name, with the appropriate 1244 name from the directory listing using the procedure defined in 1245 section 6.2. 1247 Alternatively, whether TVFS is supported or not, the user-PI can 1248 issue a CWD command ([3]) giving a name of type "cdir" from the 1249 listing returned, and from that point reference the files returned in 1250 the MLSD response from which the cdir was obtained by using the file 1251 name components of the listing. 1253 7.4. Format of Facts 1255 The "facts" for a file in a reply to a MLSx command consist of 1256 information about that file. The facts are a series of keyword=value 1257 pairs each followed by semi-colon (";") characters. An individual 1258 fact may not contain a semi-colon in its name or value. The complete 1259 series of facts may not contain the space character. See the 1260 definition or "RCHAR" in section 2.1 for a list of the characters 1261 that can occur in a fact value. Not all are applicable to all facts. 1263 A sample of a typical series of facts would be: (spread over two 1264 lines for presentation here only) 1266 size=4161;lang=en-US;modify=19970214165800;create=19961001124534; 1267 type=file;x.myfact=foo,bar; 1269 7.5. Standard Facts 1271 This document defines a standard set of facts as follows: 1273 size -- Size in octets 1274 modify -- Last modification time 1275 create -- Creation time 1276 type -- Entry type 1277 unique -- Unique id of file/directory 1278 perm -- File permissions, whether read, write, execute is 1279 allowed for the login id. 1280 lang -- Language of the file name per IANA[12] registry. 1281 media-type -- MIME media-type of file contents per IANA registry. 1282 charset -- Character set per IANA registry (if not UTF-8) 1284 Fact names are case-insensitive. Size, size, SIZE, and SiZe are the 1285 same fact. 1287 Further operating system specific keywords could be specified by 1288 using the IANA operating system name as a prefix (examples only): 1290 OS/2.ea -- OS/2 extended attributes 1291 MACOS.rf -- MacIntosh resource forks 1292 UNIX.mode -- Unix file modes (permissions) 1294 Implementations may define keywords for experimental, or private use. 1295 All such keywords MUST begin with the two character sequence "x.". 1296 As type names are case independent, "x." and "X." are equivalent. 1297 For example: 1299 x.ver -- Version information 1300 x.desc -- File description 1301 x.type -- File type 1303 7.5.1. The type Fact 1305 The type fact needs a special description. Part of the problem with 1306 current practices is deciding when a file is a directory. If it is a 1307 directory, is it the current directory, a regular directory, or a 1308 parent directory? The MLST specification makes this unambiguous 1309 using the type fact. The type fact given specifies information about 1310 the object listed on the same line of the MLST response. 1312 Five values are possible for the type fact: 1314 file -- a file entry 1315 cdir -- the listed directory 1316 pdir -- a parent directory 1317 dir -- a directory or sub-directory 1318 OS.name=type -- an OS or file system dependent file type 1320 The syntax is defined to be: 1322 type-fact = type-label "=" type-val 1323 type-label = "Type" 1324 type-val = "File" / "cdir" / "pdir" / "dir" / 1325 os-type 1327 The value of the type fact (the "type-val") is a case independent 1328 string. 1330 7.5.1.1. type=file 1332 The presence of the type=file fact indicates the listed entry is a 1333 file containing non-system data. That is, it may be transferred from 1334 one system to another of quite different characteristics, and perhaps 1335 still be meaningful. 1337 7.5.1.2. type=cdir 1339 The type=cdir fact indicates the listed entry contains a pathname of 1340 the directory whose contents are listed. An entry of this type will 1341 only be returned as a part of the result of an MLSD command when the 1342 type fact is included, and provides a name for the listed directory, 1343 and facts about that directory. In a sense, it can be viewed as 1344 representing the title of the listing, in a machine friendly format. 1345 It may appear at any point of the listing, it is not restricted to 1346 appearing at the start, though frequently may do so, and may occur 1347 multiple times. It MUST NOT be included if the type fact is not 1348 included, or there would be no way for the user-PI to distinguish the 1349 name of the directory from an entry in the directory. 1351 Where TVFS is supported by the server-FTP, this name may be used to 1352 construct pathnames with which to refer to the files and directories 1353 returned in the same MLSD output (see section 6.2). These pathnames 1354 are only expected to work when the server-PI's position in the NVFS 1355 file tree is the same as its position when the MLSD command was 1356 issued, unless a fully qualified pathname results. 1358 Where TVFS is not supported, the only defined semantics associated 1359 with a "type=cdir" entry are that, provided the current working 1360 directory of the server-PI has not been changed, a pathname of type 1361 "cdir" may be used as an argument to a CWD command, which will cause 1362 the current directory of the server-PI to change so that the 1363 directory which was listed in its current working directory. 1365 7.5.1.3. type=dir 1367 If present, the type=dir entry gives the name of a directory. Such 1368 an entry typically cannot be transferred from one system to another 1369 using RETR, etc, but should (permissions permitting) be able to be 1370 the object of an MLSD command. 1372 7.5.1.4. type=pdir 1374 If present, which will occur only in the response to a MLSD command 1375 when the type fact is included, the type=pdir entry represents a 1376 pathname of the parent directory of the listed directory. As well as 1377 having the properties of a type=dir, a CWD command that uses the 1378 pathname from this entry should change the user to a parent directory 1379 of the listed directory. If the listed directory is the current 1380 directory, a CDUP command may also have the effect of changing to the 1381 named directory. User-FTP processes should note not all responses 1382 will include this information, and that some systems may provide 1383 multiple type=pdir responses. 1385 Where TVFS is supported, a "type=pdir" name may be a relative 1386 pathname, or a fully qualified pathname. A relative pathname will be 1387 relative to the directory being listed, not to the current directory 1388 of the server-PI at the time. 1390 For the purposes of this type value, a "parent directory" is any 1391 directory in which there is an entry of type=dir which refers to the 1392 directory in which the type=pdir entity was found. Thus it is not 1393 required that all entities with type=pdir refer to the same 1394 directory. The "unique" fact (if supported and supplied) can be used 1395 to determine whether there is a relationship between the type=pdir 1396 entries or not. 1398 7.5.1.5. System defined types 1400 Files types that are specific to a specific operating system, or file 1401 system, can be encoded using the "OS." type names. The format is: 1403 os-type = "OS." os-name "=" os-kind 1404 os-name = 1405 os-kind = token 1407 The "os-name" indicates the specific system type which supports the 1408 particular localtype. OS specific types are registered by the IANA 1409 using the procedures specified in section 10. The "os-kind" provides 1410 the system dependent information as to the type of the file listed. 1411 The os-name and os-kind strings in an os-type are case independent. 1412 "OS.unix=block" and "OS.Unix=BLOCK" represent the same type (or 1413 would, if such a type were registered.) 1415 Note: Where the underlying system supports a file type which is 1416 essentially an indirect pointer to another file, the NVFS 1417 representation of that type should normally be to represent the file 1418 which the reference indicates. That is, the underlying basic file 1419 will appear more than once in the NVFS, each time with the "unique" 1420 fact (see immediately following section) containing the same value, 1421 indicating that the same file is represented by all such names. 1422 User-PIs transferring the file need then transfer it only once, and 1423 then insert their own form of indirect reference to construct 1424 alternate names where desired, or perhaps even copy the local file if 1425 that is the only way to provide two names with the same content. A 1426 file which would be a reference to another file, if only the other 1427 file actually existed, may be represented in any OS dependent manner 1428 appropriate, or not represented at all. 1430 7.5.1.6. Multiple types 1432 Where a file is such that it may validly, and sensibly, treated by 1433 the server-PI as being of more than one of the above types, then 1434 multiple entries should be returned, each with its own "Type" fact of 1435 the appropriate type, and each containing the same pathname. This 1436 may occur, for example, with a structured file, which may contain 1437 sub-files, and where the server-PI permits the structured file to be 1438 treated as a unit, or treated as a directory allowing the sub-files 1439 within it to be referenced. When this is done, the pathname returned 1440 with each entry MUST be identical to the others representing the same 1441 file. 1443 7.5.2. The unique Fact 1445 The unique fact is used to present a unique identifier for a file or 1446 directory in the NVFS accessed via a server-FTP process. The value 1447 of this fact should be the same for any number of pathnames that 1448 refer to the same underlying file. The fact should have different 1449 values for names which reference distinct files. The mapping between 1450 files, and unique fact tokens should be maintained, and remain 1451 consistent, for at least the lifetime of the control connection from 1452 user-PI to server-PI. 1454 unique-fact = "Unique" "=" token 1456 This fact would be expected to be used by Server-FTPs whose host 1457 system allows things such as symbolic links so that the same file may 1458 be represented in more than one directory on the server. The only 1459 conclusion that should be drawn is that if two different names each 1460 have the same value for the unique fact, they refer to the same 1461 underlying object. The value of the unique fact (the token) should 1462 be considered an opaque string for comparison purposes, and is a case 1463 dependent value. The tokens "A" and "a" do not represent the same 1464 underlying object. 1466 7.5.3. The modify Fact 1468 The modify fact is used to determine the last time the content of the 1469 file (or directory) indicated was modified. Any change of substance 1470 to the file should cause this value to alter. That is, if a change 1471 is made to a file such that the results of a RETR command would 1472 differ, then the value of the modify fact should alter. User-PIs 1473 should not assume that a different modify fact value indicates that 1474 the file contents are necessarily different than when last retrieved. 1475 Some systems may alter the value of the modify fact for other 1476 reasons, though this is discouraged wherever possible. Also a file 1477 may alter, and then be returned to its previous content, which would 1478 often be indicated as two incremental alterations to the value of the 1479 modify fact. 1481 For directories, this value should alter whenever a change occurs to 1482 the directory such that different file names would (or might) be 1483 included in MLSD output of that directory. 1485 modify-fact = "Modify" "=" time-val 1487 7.5.4. The create Fact 1489 The create fact indicates when a file, or directory, was first 1490 created. Exactly what "creation" is for this purpose is not 1491 specified here, and may vary from server to server. About all that 1492 can be said about the value returned is that it can never indicate a 1493 later time than the modify fact. 1495 create-fact = "Create" "=" time-val 1497 Implementation Note: Implementors of this fact on UNIX(TM) systems 1498 should note that the unix "stat" "st_ctime" field does not give 1499 creation time, and that unix file systems do not record creation 1500 time at all. Unix (and POSIX) implementations will normally not 1501 include this fact. 1503 7.5.5. The perm Fact 1505 The perm fact is used to indicate access rights the current FTP user 1506 has over the object listed. Its value is always an unordered 1507 sequence of alphabetic characters. 1509 perm-fact = "Perm" "=" *pvals 1510 pvals = "a" / "c" / "d" / "e" / "f" / 1511 "l" / "m" / "p" / "r" / "w" 1513 There are ten permission indicators currently defined. Many are 1514 meaningful only when used with a particular type of object. The 1515 indicators are case independent, "d" and "D" are the same indicator. 1517 The "a" permission applies to objects of type=file, and indicates 1518 that the APPE (append) command may be applied to the file named. 1520 The "c" permission applies to objects of type=dir (and type=pdir, 1521 type=cdir). It indicates that files may be created in the directory 1522 named. That is, that a STOU command is likely to succeed, and that 1523 STOR and APPE commands might succeed if the file named did not 1524 previously exist, but is to be created in the directory object that 1525 has the "c" permission. It also indicates that the RNTO command is 1526 likely to succeed for names in the directory. 1528 The "d" permission applies to all types. It indicates that the 1529 object named may be deleted, that is, that the RMD command may be 1530 applied to it if it is a directory, and otherwise that the DELE 1531 command may be applied to it. 1533 The "e" permission applies to the directory types. When set on an 1534 object of type=dir, type=cdir, or type=pdir it indicates that a CWD 1535 command naming the object should succeed, and the user should be able 1536 to enter the directory named. For type=pdir it also indicates that 1537 the CDUP command may succeed (if this particular pathname is the one 1538 to which a CDUP would apply.) 1540 The "f" permission for objects indicates that the object named may be 1541 renamed - that is, may be the object of an RNFR command. 1543 The "l" permission applies to the directory file types, and indicates 1544 that the listing commands, LIST, NLST, and MLSD may be applied to the 1545 directory in question. 1547 The "m" permission applies to directory types, and indicates that the 1548 MKD command may be used to create a new directory within the 1549 directory under consideration. 1551 The "p" permission applies to directory types, and indicates that 1552 objects in the directory may be deleted, or (stretching naming a 1553 little) that the directory may be purged. Note: it does not indicate 1554 that the RMD command may be used to remove the directory named 1555 itself, the "d" permission indicator indicates that. 1557 The "r" permission applies to type=file objects, and for some 1558 systems, perhaps to other types of objects, and indicates that the 1559 RETR command may be applied to that object. 1561 The "w" permission applies to type=file objects, and for some 1562 systems, perhaps to other types of objects, and indicates that the 1563 STOR command may be applied to the object named. 1565 Note: That a permission indicator is set can never imply that the 1566 appropriate command is guaranteed to work -- just that it might. 1567 Other system specific limitations, such as limitations on 1568 available space for storing files, may cause an operation to 1569 fail, where the permission flags may have indicated that it was 1570 likely to succeed. The permissions are a guide only. 1572 Implementation note: The permissions are described here as they apply 1573 to FTP commands. They may not map easily into particular 1574 permissions available on the server's operating system. Servers 1575 are expected to synthesize these permission bits from the 1576 permission information available from operating system. For 1577 example, to correctly determine whether the "D" permission bit 1578 should be set on a directory for a server running on the 1579 UNIX(TM) operating system, the server should check that the 1580 directory named is empty, and that the user has write permission 1581 on both the directory under consideration, and its parent 1582 directory. 1584 Some systems may have more specific permissions than those 1585 listed here, such systems should map those to the flags defined 1586 as best they are able. Other systems may have only more broad 1587 access controls. They will generally have just a few possible 1588 permutations of permission flags, however they should attempt to 1589 correctly represent what is permitted. 1591 7.5.6. The lang Fact 1593 The lang fact describes the natural language of the file name for use 1594 in display purposes. Values used here should be taken from the 1595 language registry of the IANA. See [13] for the syntax, and 1596 procedures, related to language tags. 1598 lang-fact = "Lang" "=" token 1600 Server-FTP implementations MUST NOT guess language values. Language 1601 values must be determined in an unambiguous way such as file system 1602 tagging of language or by user configuration. Note that the lang 1603 fact provides no information at all about the content of a file, only 1604 about the encoding of its name. 1606 7.5.7. The size Fact 1608 The size fact applies to non-directory file types and should always 1609 reflect the approximate size of the file. This should be as accurate 1610 as the server can make it, without going to extraordinary lengths, 1611 such as reading the entire file. The size is expressed in units of 1612 octets of data in the file. 1614 Given limitations in some systems, Client-FTP implementations must 1615 understand this size may not be precise and may change between the 1616 time of a MLST and RETR operation. 1618 Clients that need highly accurate size information for some 1619 particular reason should use the SIZE command as defined in section 1620 4. The most common need for this accuracy is likely to be in 1621 conjunction with the REST command described in section 5. The size 1622 fact, on the other hand, should be used for purposes such as 1623 indicating to a human user the approximate size of the file to be 1624 transferred, and perhaps to give an idea of expected transfer 1625 completion time. 1627 size-fact = "Size" "=" 1*DIGIT 1629 7.5.8. The media-type Fact 1631 The media-type fact represents the IANA media type of the file named, 1632 and applies only to non-directory types. The list of values used 1633 must follow the guidelines set by the IANA registry. 1635 media-type = "Media-Type" "=" 1637 Server-FTP implementations MUST NOT guess media type values. Media 1638 type values must be determined in an unambiguous way such as file 1639 system tagging of media-type or by user configuration. This fact 1640 gives information about the content of the file named. Both the 1641 primary media type, and any appropriate subtype should be given, 1642 separated by a slash "/" as is traditional. 1644 7.5.9. The charset Fact 1646 The charset fact provides the IANA character set name, or alias, for 1647 the encoded pathnames in a MLSx response. The default character set 1648 is UTF-8 unless specified otherwise. FTP implementations SHOULD use 1649 UTF-8 if possible to encourage maximum inter-operability. The value 1650 of this fact applies to the pathname only, and provides no 1651 information about the contents of the file. 1653 charset-type = "Charset" "=" token 1655 7.5.10. Required facts 1657 Servers are not required to support any particular set of the 1658 available facts. However, servers SHOULD, if conceivably possible, 1659 support at least the type, perm, size, unique, and modify facts. 1661 7.6. System Dependent and Local Facts 1663 By using an system dependent fact, or a local fact, a server-PI may 1664 communicate to the user-PI information about the file named which is 1665 peculiar to the underlying file system. 1667 7.6.1. System Dependent Facts 1669 System dependent fact names are labeled by prefixing a label 1670 identifying the specific information returned by the name of the 1671 appropriate operating system from the IANA maintained list of 1672 operating system names. 1674 The value of an OS dependent fact may be whatever is appropriate to 1675 convey the information available. It must be encoded as a "token" as 1676 defined in section 2.1 however. 1678 In order to allow reliable inter-operation between users of system 1679 dependent facts, the IANA will maintain a registry of system 1680 dependent fact names, their syntax, and the interpretation to be 1681 given to their values. Registrations of system dependent facts are 1682 to be accomplished according to the procedures of section 10. 1684 7.6.2. Local Facts 1686 Implementations may also make available other facts of their own 1687 choosing. As the method of interpretation of such information will 1688 generally not be widely understood, server-PIs should be aware that 1689 clients will typically ignore any local facts provided. As there is 1690 no registration of locally defined facts, it is entirely possible 1691 that different servers will use the same local fact name to provide 1692 vastly different information. Hence user-PIs should be hesitant 1693 about making any use of any information in a locally defined fact 1694 without some other specific assurance that the particular fact is one 1695 that they do comprehend. 1697 Local fact names all begin with the sequence "X.". The rest of the 1698 name is a "token" (see section 2.1). The value of a local fact can 1699 be anything at all, provided it can be encoded as a "token". 1701 7.7. MLSx Examples 1703 The following examples are all taken from dialogues between existing 1704 FTP clients and servers. Because of this, not all possible 1705 variations of possible response formats are shown in the examples. 1706 This should not be taken as limiting the options of other server 1707 implementors. Where the examples show OS dependent information, that 1708 is to be treated as being purely for the purposes of demonstration of 1709 some possible OS specific information that could be defined. As at 1710 the time of the writing of this document, no OS specific facts or 1711 file types have been defined, the examples shown here should not be 1712 treated as in any way to be preferred over other possible similar 1713 definitions. Consult the IANA registries to determine what types and 1714 facts have been defined. Finally also beware that as the examples 1715 shown are taken from existing implementations, coded before this 1716 document was completed, the possibility of variations between the 1717 text of this document and the examples exists. In any such case of 1718 inconsistency, the example is to be treated as incorrect. 1720 In the examples shown, only relevant commands and responses have been 1721 included. This is not to imply that other commands (including 1722 authentication, directory modification, PORT or PASV commands, or 1723 similar) would not be present in an actual connection, or were not, 1724 in fact, actually used in the examples before editing. Note also 1725 that the formats shown are those that are transmitted between client 1726 and server, not formats which would normally ever be reported to the 1727 user of the client. 1729 7.7.1. Simple MLST 1731 C> PWD 1732 S> 257 "/tmp" is current directory. 1733 C> MLst cap60.pl198.tar.gz 1734 S> 250- Listing cap60.pl198.tar.gz 1735 S> Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz 1736 S> 250 End 1738 The client first asked to be told the current directory of the 1739 server. This was purely for the purposes of clarity of this example. 1740 The client then requested facts about a specific file. The server 1741 returned the "250-" first control-response line, followed by a single 1742 line of facts about the file, followed by the terminating "250 " 1743 line. The text on the control-response line and the terminating line 1744 can be anything the server decides to send. Notice that the fact 1745 line is indented by a single space. Notice also that there are no 1746 spaces in the set of facts returned, until the single space before 1747 the file name. The file name returned on the fact line is a fully 1748 qualified pathname of the file listed. The facts returned show that 1749 the line refers to a file, that file contains approximately 1024990 1750 bytes, though more or less than that may be transferred if the file 1751 is retrieved, and a different number may be required to store the 1752 file at the client's file store, and the connected user has 1753 permission to retrieve the file but not to do anything else 1754 particularly interesting. 1756 7.7.2. MLST of a directory 1758 C> PWD 1759 S> 257 "/" is current directory. 1760 C> MLst tmp 1761 S> 250- Listing tmp 1762 S> Type=dir;Modify=19981107085215;Perm=el; /tmp 1763 S> 250 End 1765 Again the PWD is just for the purposes of demonstration for the 1766 example. The MLST fact line this time shows that the file listed is 1767 a directory, that it was last modified at 08:52:15 on the 7th of 1768 November, 1998 UTC, and that the user has permission to enter the 1769 directory, and to list its contents, but not to modify it in any way. 1770 Again, the fully qualified pathname of the directory listed is given. 1772 7.7.3. MLSD of a directory 1774 C> MLSD tmp 1775 S> 150 BINARY connection open for MLSD tmp 1776 D> Type=cdir;Modify=19981107085215;Perm=el; tmp 1777 D> Type=cdir;Modify=19981107085215;Perm=el; /tmp 1778 D> Type=pdir;Modify=19990112030508;Perm=el; .. 1779 D> Type=file;Size=25730;Modify=19940728095854;Perm=; capmux.tar.z 1780 D> Type=file;Size=1830;Modify=19940916055648;Perm=r; hatch.c 1781 D> Type=file;Size=25624;Modify=19951003165342;Perm=r; MacIP-02.txt 1782 D> Type=file;Size=2154;Modify=19950501105033;Perm=r; uar.netbsd.patch 1783 D> Type=file;Size=54757;Modify=19951105101754;Perm=r; iptnnladev.1.0.sit.hqx 1784 D> Type=file;Size=226546;Modify=19970515023901;Perm=r; melbcs.tif 1785 D> Type=file;Size=12927;Modify=19961025135602;Perm=r; tardis.1.6.sit.hqx 1786 D> Type=file;Size=17867;Modify=19961025135602;Perm=r; timelord.1.4.sit.hqx 1787 D> Type=file;Size=224907;Modify=19980615100045;Perm=r; uar.1.2.3.sit.hqx 1788 D> Type=file;Size=1024990;Modify=19980130010322;Perm=r; cap60.pl198.tar.gz 1789 S> 226 MLSD completed 1791 In this example notice that there is no leading space on the fact 1792 lines returned over the data connection. Also notice that two lines 1793 of "type=cdir" have been given. These show two alternate names for 1794 the directory listed, one a fully qualified pathname, and the other a 1795 local name relative to the servers current directory when the MLSD 1796 was performed. Note that all other file names in the output are 1797 relative to the directory listed, though the server could, if it 1798 chose, give a fully qualified pathname for the "type=pdir" line. 1799 This server has chosen not to. The other files listed present a 1800 fairly boring set of files that are present in the listed directory. 1801 Note that there is no particular order in which they are listed. 1802 They are not sorted by file name, by size, or by modify time. Note 1803 also that the "perm" fact has an empty value for the file 1804 "capmux.tar.z" indicating that the connected user has no permissions 1805 at all for that file. This server has chosen to present the "cdir" 1806 and "pdir" lines before the lines showing the content of the 1807 directory, it is not required to do so. The "size" fact does not 1808 provide any meaningful information for a directory, so is not 1809 included in the fact lines for the directory types shown. 1811 7.7.4. A more complex example 1813 C> MLst test 1814 S> 250- Listing test 1815 S> Type=dir;Perm=el;Unique=keVO1+ZF4 test 1816 S> 250 End 1817 C> MLSD test 1818 S> 150 BINARY connection open for MLSD test 1819 D> Type=cdir;Perm=el;Unique=keVO1+ZF4; test 1820 D> Type=pdir;Perm=e;Unique=keVO1+d?3; .. 1821 D> Type=OS.unix=slink:/foobar;Perm=;Unique=keVO1+4G4; foobar 1822 D> Type=OS.unix=chr-13/29;Perm=;Unique=keVO1+5G4; device 1823 D> Type=OS.unix=blk-11/108;Perm=;Unique=keVO1+6G4; block 1824 D> Type=file;Perm=awr;Unique=keVO1+8G4; writable 1825 D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; promiscuous 1826 D> Type=dir;Perm=;Unique=keVO1+1t2; no-exec 1827 D> Type=file;Perm=r;Unique=keVO1+EG4; two words 1828 D> Type=file;Perm=r;Unique=keVO1+IH4; leading space 1829 D> Type=file;Perm=r;Unique=keVO1+1G4; file1 1830 D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; incoming 1831 D> Type=file;Perm=r;Unique=keVO1+1G4; file2 1832 D> Type=file;Perm=r;Unique=keVO1+1G4; file3 1833 D> Type=file;Perm=r;Unique=keVO1+1G4; file4 1834 S> 226 MLSD completed 1835 C> MLSD test/incoming 1836 S> 150 BINARY connection open for MLSD test/incoming 1837 D> Type=cdir;Perm=cpmel;Unique=keVO1+7G4; test/incoming 1838 D> Type=pdir;Perm=el;Unique=keVO1+ZF4; .. 1839 D> Type=file;Perm=awdrf;Unique=keVO1+EH4; bar 1840 D> Type=file;Perm=awdrf;Unique=keVO1+LH4; 1841 D> Type=file;Perm=rf;Unique=keVO1+1G4; file5 1842 D> Type=file;Perm=rf;Unique=keVO1+1G4; file6 1843 D> Type=dir;Perm=cpmdelf;Unique=keVO1+!s2; empty 1844 S> 226 MLSD completed 1846 For the purposes of this example the fact set requested has been 1847 modified to delete the "size" and "modify" facts, and add the 1848 "unique" fact. First, facts about a file name have been obtained via 1849 MLST. Note that no fully qualified pathname was given this time. 1850 That was because the server was unable to determine that information. 1851 Then having determined that the file name represents a directory, 1852 that directory has been listed. That listing also shows no fully 1853 qualified pathname, for the same reason, thus has but a single 1854 "type=cdir" line. This directory (which was created especially for 1855 the purpose) contains several interesting files. There are some with 1856 OS dependent file types, several sub-directories, and several 1857 ordinary files. 1859 Not much can be said here about the OS dependent file types, as none 1860 of the information shown there should be treated as any more than 1861 possibilities. It can be seen that the OS type of the server is 1862 "unix" though, which is one of the OS types in the IANA registry of 1863 Operating System names. 1865 Of the three directories listed, "no-exec" has no permission granted 1866 to this user to access at all. From the "Unique" fact values, it can 1867 be determined that "promiscuous" and "incoming" in fact represent the 1868 same directory. Its permissions show that the connected user has 1869 permission to do essentially anything other than to delete the 1870 directory. That directory was later listed. It happens that the 1871 directory can not be deleted because it is not empty. 1873 Of the normal files listed, two contain spaces in their names. The 1874 file called " leading space" actually contains two spaces in its 1875 name, one before the "l" and one between the "g" and the "s". The 1876 two spaces that separate the facts from the visible part of the 1877 pathname make that clear. The file "writable" has the "a" and "w" 1878 permission bits set, and consequently the connected user should be 1879 able to STOR or APPE to that file. 1881 The other four file names, "file1", "file2", "file3", and "file4" all 1882 represent the same underlying file, as can be seen from the values of 1883 the "unique" facts of each. It happens that "file1" and "file2" are 1884 Unix "hard" links, and that "file3" and "file4" are "soft" or 1885 "symbolic" links to the first two. None of that information is 1886 available via standard MLST facts, it is sufficient for the purposes 1887 of FTP to note that all represent the same file, and that the same 1888 data would be fetched no matter which of them was retrieved, and that 1889 all would be simultaneously modified were data stored in any. 1891 Finally, the sub-directory "incoming" is listed. Since "promiscuous" 1892 is the same directory there would be no point listing it as well. In 1893 that directory, the files "file5" and "file6" represent still more 1894 names for the "file1" file we have seen before. Notice the entry 1895 between that for "bar" and "file5". Though it is not possible to 1896 easily represent it in this document, that shows a file with a name 1897 comprising exactly three spaces (" "). A client will have no 1898 difficulty determining that name from the output presented to it 1899 however. The directory "empty" is, as its name implies, empty, 1900 though that is not shown here. It can, however, be deleted, as can 1901 file "bar" and the file whose name is three spaces. All the files 1902 that reside in this directory can be renamed. This is a consequence 1903 of the UNIX semantics of the directory that contains them being 1904 modifiable. 1906 7.7.5. More accurate time information 1908 C> MLst file1 1909 S> 250- Listing file1 1910 S> Type=file;Modify=19990929003355.237; file1 1911 S> 250 End 1913 In this example, the server-FTP is indicating that "file1" was last 1914 modified 237 milliseconds after 00:33:55 UTC on the 29th of 1915 September, 1999. 1917 7.7.6. A different server 1919 C> MLST 1920 S> 250-Begin 1921 S> type=dir;unique=AQkAAAAAAAABCAAA; / 1922 S> 250 End. 1923 C> MLSD 1924 S> 150 Opening ASCII mode data connection for MLS. 1925 D> type=cdir;unique=AQkAAAAAAAABCAAA; / 1926 D> type=dir;unique=AQkAAAAAAAABEAAA; bin 1927 D> type=dir;unique=AQkAAAAAAAABGAAA; etc 1928 D> type=dir;unique=AQkAAAAAAAAB8AwA; halflife 1929 D> type=dir;unique=AQkAAAAAAAABoAAA; incoming 1930 D> type=dir;unique=AQkAAAAAAAABIAAA; lib 1931 D> type=dir;unique=AQkAAAAAAAABWAEA; linux 1932 D> type=dir;unique=AQkAAAAAAAABKAEA; ncftpd 1933 D> type=dir;unique=AQkAAAAAAAABGAEA; outbox 1934 D> type=dir;unique=AQkAAAAAAAABuAAA; quake2 1935 D> type=dir;unique=AQkAAAAAAAABQAEA; winstuff 1936 S> 226 Listing completed. 1937 C> MLSD linux 1938 S> 150 Opening ASCII mode data connection for MLS. 1939 D> type=cdir;unique=AQkAAAAAAAABWAEA; /linux 1940 D> type=pdir;unique=AQkAAAAAAAABCAAA; / 1941 D> type=dir;unique=AQkAAAAAAAABeAEA; firewall 1942 D> type=file;size=12;unique=AQkAAAAAAAACWAEA; helo_world 1943 D> type=dir;unique=AQkAAAAAAAABYAEA; kernel 1944 D> type=dir;unique=AQkAAAAAAAABmAEA; scripts 1945 D> type=dir;unique=AQkAAAAAAAABkAEA; security 1946 S> 226 Listing completed. 1947 C> MLSD linux/kernel 1948 S> 150 Opening ASCII mode data connection for MLS. 1949 D> type=cdir;unique=AQkAAAAAAAABYAEA; /linux/kernel 1950 D> type=pdir;unique=AQkAAAAAAAABWAEA; /linux 1951 D> type=file;size=6704;unique=AQkAAAAAAAADYAEA; k.config 1952 D> type=file;size=7269221;unique=AQkAAAAAAAACYAEA; linux-2.0.36.tar.gz 1953 D> type=file;size=12514594;unique=AQkAAAAAAAAEYAEA; linux-2.1.130.tar.gz 1954 S> 226 Listing completed. 1956 Note that this server returns its "unique" fact value in quite a 1957 different format. It also returns fully qualified pathnames for the 1958 "pdir" entry. 1960 7.7.7. Some IANA files 1962 C> MLSD 1963 S> 150 BINARY connection open for MLSD . 1964 D> Type=cdir;Modify=19990219183438; /iana/assignments 1965 D> Type=pdir;Modify=19990112030453; .. 1966 D> Type=dir;Modify=19990219073522; media-types 1967 D> Type=dir;Modify=19990112033515; character-set-info 1968 D> Type=dir;Modify=19990112033529; languages 1969 D> Type=file;Size=44242;Modify=19990217230400; character-sets 1970 D> Type=file;Size=1947;Modify=19990209215600; operating-system-names 1971 S> 226 MLSD completed 1972 C> MLSD media-types 1973 S> 150 BINARY connection open for MLSD media-types 1974 D> Type=cdir;Modify=19990219073522; media-types 1975 D> Type=cdir;Modify=19990219073522; /iana/assignments/media-types 1976 D> Type=pdir;Modify=19990219183438; .. 1977 D> Type=dir;Modify=19990112033045; text 1978 D> Type=dir;Modify=19990219183442; image 1979 D> Type=dir;Modify=19990112033216; multipart 1980 D> Type=dir;Modify=19990112033254; video 1981 D> Type=file;Size=30249;Modify=19990218032700; media-types 1982 S> 226 MLSD completed 1983 C> MLSD character-set-info 1984 S> 150 BINARY connection open for MLSD character-set-info 1985 D> Type=cdir;Modify=19990112033515; character-set-info 1986 D> Type=cdir;Modify=19990112033515; /iana/assignments/character-set-info 1987 D> Type=pdir;Modify=19990219183438; .. 1988 D> Type=file;Size=1234;Modify=19980903020400; windows-1251 1989 D> Type=file;Size=4557;Modify=19980922001400; tis-620 1990 D> Type=file;Size=801;Modify=19970324130000; ibm775 1991 D> Type=file;Size=552;Modify=19970320130000; ibm866 1992 D> Type=file;Size=922;Modify=19960505140000; windows-1258 1993 S> 226 MLSD completed 1994 C> MLSD languages 1995 S> 150 BINARY connection open for MLSD languages 1996 D> Type=cdir;Modify=19990112033529; languages 1997 D> Type=cdir;Modify=19990112033529; /iana/assignments/languages 1998 D> Type=pdir;Modify=19990219183438; .. 1999 D> Type=file;Size=2391;Modify=19980309130000; default 2000 D> Type=file;Size=943;Modify=19980309130000; tags 2001 D> Type=file;Size=870;Modify=19971026130000; navajo 2002 D> Type=file;Size=699;Modify=19950911140000; no-bok 2003 S> 226 MLSD completed 2004 C> PWD 2005 S> 257 "/iana/assignments" is current directory. 2007 This example shows some of the IANA maintained files that are 2008 relevant for this specification in MLSD format. Note that these 2009 listings have been edited by deleting many entries, the actual 2010 listings are much longer. 2012 7.7.8. A stress test of case (in)dependence 2014 The following example is intended to make clear some cases where case 2015 dependent strings are permitted in the MLSx commands, and where case 2016 independent strings are required. 2018 Note first that the "MLSD" command, shown here as "MlsD" is case 2019 independent. Clients may issue this command in any case, or 2020 combination of cases, they desire. This is the case for all FTP 2021 commands. 2023 C> MlsD 2024 S> 150 BINARY connection open for MLSD . 2025 D> Type=pdir;Modify=19990929011228;Perm=el;Unique=keVO1+ZF4; .. 2026 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; FILE2 2027 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+aG8; file3 2028 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+ag8; FILE3 2029 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file1 2030 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file2 2031 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Ag8; File3 2032 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; File1 2033 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; File2 2034 D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bd8; FILE1 2035 S> 226 MLSD completed 2037 Next, notice the labels of the facts. These are also case 2038 independent strings, Server-FTP is permitted to return them in any 2039 case desired. User-FTP must be prepared to deal with any case, 2040 though it may do this by mapping the labels to a common case if 2041 desired. 2043 Then, notice that there are nine objects of "type" file returned. In 2044 a case independent NVFS these would represent three different file 2045 names, "file1", "file2", and "file3". With a case dependent NVFS all 2046 nine represent different file names. Either is possible, server-FTPs 2047 may implement a case dependent or a case independent NVFS. User-FTPs 2048 must allow for case dependent selection of files to manipulate on the 2049 server. 2051 Lastly, notice that the value of the "unique" fact is case dependent. 2052 In the example shown, "file1", "File1", and "file2" all have the same 2053 "unique" fact value "keVO1+bD8", and thus all represent the same 2054 underlying file. On the other hand, "FILE1" has a different "unique" 2055 fact value ("keVO1+bd8") and hence represents a different file. 2056 Similarly, "FILE2" and "File2" are two names for the same underlying 2057 file, whereas "file3", "File3" and "FILE3" all represent different 2058 underlying files. 2060 That the approximate sizes ("size" fact) and last modification times 2061 ("modify" fact) are the same in all cases might be no more than a 2062 coincidence. 2064 It is not suggested that the operators of server-FTPs create NVFS 2065 which stress the protocols to this extent, however both user and 2066 server implementations must be prepared to deal with such extreme 2067 examples. 2069 7.7.9. Example from another server 2071 C> MlsD 2072 S> 150 File Listing Follows in IMAGE / Binary mode. 2073 D> type=cdir;modify=19990426150227;perm=el; /MISC 2074 D> type=pdir;modify=19791231130000;perm=el; / 2075 D> type=dir;modify=19990426150227;perm=el; CVS 2076 D> type=dir;modify=19990426150228;perm=el; SRC 2077 S> 226 Transfer finished successfully. 2078 C> MlsD src 2079 S> 150 File Listing Follows in IMAGE / Binary mode. 2080 D> type=cdir;modify=19990426150228;perm=el; /MISC/src 2081 D> type=pdir;modify=19990426150227;perm=el; /MISC 2082 D> type=dir;modify=19990426150228;perm=el; CVS 2083 D> type=dir;modify=19990426150228;perm=el; INSTALL 2084 D> type=dir;modify=19990426150230;perm=el; INSTALLI 2085 D> type=dir;modify=19990426150230;perm=el; TREES 2086 S> 226 Transfer finished successfully. 2087 C> MlsD src/install 2088 S> 150 File Listing Follows in IMAGE / Binary mode. 2089 D> type=cdir;modify=19990426150228;perm=el; /MISC/src/install 2090 D> type=pdir;modify=19990426150228;perm=el; /MISC/src 2091 D> type=file;modify=19990406234304;perm=r;size=20059; BOOTPC.C 2092 D> type=file;modify=19980401170153;perm=r;size=278; BOOTPC.H 2093 D> type=file;modify=19990413153736;perm=r;size=54220; BOOTPC.O 2094 D> type=file;modify=19990223044003;perm=r;size=3389; CDROM.C 2095 D> type=file;modify=19990413153739;perm=r;size=30192; CDROM.O 2096 D> type=file;modify=19981119155324;perm=r;size=1055; CHANGELO 2097 D> type=file;modify=19981204171040;perm=r;size=8297; COMMANDS.C 2098 D> type=file;modify=19980508041749;perm=r;size=580; COMMANDS.H 2099 ... 2100 D> type=file;modify=19990419052351;perm=r;size=54264; URLMETHO.O 2101 D> type=file;modify=19980218161629;perm=r;size=993; WINDOWS.C 2102 D> type=file;modify=19970912154859;perm=r;size=146; WINDOWS.H 2103 D> type=file;modify=19990413153731;perm=r;size=16812; WINDOWS.O 2104 D> type=file;modify=19990322174959;perm=r;size=129; _CVSIGNO 2105 D> type=file;modify=19990413153640;perm=r;size=82536; _DEPEND 2106 S> 226 Transfer finished successfully. 2107 C> MLst src/install/windows.c 2108 S> 250-Listing src/install/windows.c 2109 S> type=file;perm=r;size=993; /misc/src/install/windows.c 2110 S> 250 End 2111 S> ftp> mlst SRC/INSTALL/WINDOWS.C 2112 C> MLst SRC/INSTALL/WINDOWS.C 2113 S> 250-Listing SRC/INSTALL/WINDOWS.C 2114 S> type=file;perm=r;size=993; /misc/SRC/INSTALL/WINDOWS.C 2115 S> 250 End 2117 Note that this server gives fully qualified pathnames for the "pdir" 2118 and "cdir" entries in MLSD listings. Also notice that this server 2119 does, though it is not required to, sort its directory listing 2120 outputs. That may be an artifact of the underlying file system 2121 access mechanisms of course. Finally notice that the NVFS supported 2122 by this server, in contrast to the earlier ones, implements its 2123 pathnames in a case independent manner. The server seems to return 2124 files using the case in which they were requested, when the name was 2125 sent by the client, and otherwise uses an algorithm known only to 2126 itself to select the case of the names it returns. 2128 7.7.10. A server listing itself 2130 C> MLst f 2131 S> 250-MLST f 2132 S> Type=dir;Modify=20000710052229;Unique=AAD/AAAABIA; f 2133 S> 250 End 2134 C> CWD f 2135 S> 250 CWD command successful. 2136 C> MLSD 2137 S> 150 Opening ASCII mode data connection for 'MLSD'. 2138 D> Type=cdir;Unique=AAD/AAAABIA; . 2139 D> Type=pdir;Unique=AAD/AAAAAAI; .. 2140 D> Type=file;Size=987;Unique=AAD/AAAABIE; Makefile 2141 D> Type=file;Size=20148;Unique=AAD/AAAABII; conf.c 2142 D> Type=file;Size=11111;Unique=AAD/AAAABIM; extern.h 2143 D> Type=file;Size=38721;Unique=AAD/AAAABIQ; ftpcmd.y 2144 D> Type=file;Size=17922;Unique=AAD/AAAABIU; ftpd.8 2145 D> Type=file;Size=60732;Unique=AAD/AAAABIY; ftpd.c 2146 D> Type=file;Size=3127;Unique=AAD/AAAABIc; logwtmp.c 2147 D> Type=file;Size=2294;Unique=AAD/AAAABIg; pathnames.h 2148 D> Type=file;Size=7605;Unique=AAD/AAAABIk; popen.c 2149 D> Type=file;Size=9951;Unique=AAD/AAAABIo; ftpd.conf.5 2150 D> Type=file;Size=5023;Unique=AAD/AAAABIs; ftpusers.5 2151 D> Type=file;Size=3547;Unique=AAD/AAAABIw; logutmp.c 2152 D> Type=file;Size=2064;Unique=AAD/AAAABI0; version.h 2153 D> Type=file;Size=20420;Unique=AAD/AAAAAAM; cmds.c 2154 D> Type=file;Size=15864;Unique=AAD/AAAAAAg; ls.c 2155 D> Type=file;Size=2898;Unique=AAD/AAAAAAk; ls.h 2156 D> Type=file;Size=2769;Unique=AAD/AAAAAAo; lsextern.h 2157 D> Type=file;Size=2042;Unique=AAD/AAAAAAs; stat_flags.h 2158 D> Type=file;Size=5708;Unique=AAD/AAAAAAw; cmp.c 2159 D> Type=file;Size=9280;Unique=AAD/AAAAAA0; print.c 2160 D> Type=file;Size=4657;Unique=AAD/AAAAAA4; stat_flags.c 2161 D> Type=file;Size=2664;Unique=AAD/AAAAAA8; util.c 2162 D> Type=file;Size=10383;Unique=AAD/AAAABJ0; ftpd.conf.cat5 2163 D> Type=file;Size=3631;Unique=AAD/AAAABJ4; ftpusers.cat5 2164 D> Type=file;Size=17729;Unique=AAD/AAAABJ8; ftpd.cat8 2165 S> 226 MLSD complete. 2167 This examples shows yet another server implementation, showing a 2168 listing of its own source code. Note that this implementation does 2169 not include the fully qualified path name in its "cdir" and "pdir" 2170 entries, nor in the output from "MLST". Also note that the facts 2171 requested were modified between the "MLST" and "MLSD" commands, 2172 though that exchange has not been shown here. 2174 7.7.11. A server with a difference 2176 C> PASV 2177 S> 227 Entering Passive Mode (127,0,0,1,255,46) 2178 C> MLSD 2179 S> 150 I tink I tee a trisector tree 2180 D> Type=file;Unique=aaaaafUYqaaa;Perm=rf;Size=15741; x 2181 D> Type=cdir;Unique=aaaaacUYqaaa;Perm=cpmel; / 2182 D> Type=file;Unique=aaaaajUYqaaa;Perm=rf;Size=5760; x4 2183 D> Type=dir;Unique=aaabcaUYqaaa;Perm=elf; sub 2184 D> Type=file;Unique=aaaaagUYqaaa;Perm=rf;Size=8043; x1 2185 D> Type=dir;Unique=aaab8aUYqaaa;Perm=cpmelf; files 2186 D> Type=file;Unique=aaaaahUYqaaa;Perm=rf;Size=4983; x2 2187 D> Type=file;Unique=aaaaaiUYqaaa;Perm=rf;Size=6854; x3 2188 S> 226 That's all folks... 2189 C> CWD sub 2190 S> 250 CWD command successful. 2191 C> PWD 2192 S> 257 "/sub" is current directory. 2193 C> PASV 2194 S> 227 Entering Passive Mode (127,0,0,1,255,44) 2195 C> MLSD 2196 S> 150 I tink I tee a trisector tree 2197 D> Type=dir;Unique=aaabceUYqaaa;Perm=elf; dir 2198 D> Type=file;Unique=aaabcbUYqaaa;Perm=rf;Size=0; y1 2199 D> Type=file;Unique=aaabccUYqaaa;Perm=rf;Size=0; y2 2200 D> Type=file;Unique=aaabcdUYqaaa;Perm=rf;Size=0; y3 2201 D> Type=pdir;Unique=aaaaacUYqaaa;Perm=cpmel; / 2202 D> Type=pdir;Unique=aaaaacUYqaaa;Perm=cpmel; .. 2203 D> Type=cdir;Unique=aaabcaUYqaaa;Perm=el; /sub 2204 S> 226 That's all folks... 2205 C> PASV 2206 S> 227 Entering Passive Mode (127,0,0,1,255,42) 2207 C> MLSD dir 2208 S> 150 I tink I tee a trisector tree 2209 D> Type=pdir;Unique=aaabcaUYqaaa;Perm=el; /sub 2210 D> Type=pdir;Unique=aaabcaUYqaaa;Perm=el; .. 2211 D> Type=file;Unique=aaab8cUYqaaa;Perm=r;Size=15039; mlst.c 2212 D> Type=dir;Unique=aaabcfUYqaaa;Perm=el; ect 2213 D> Type=cdir;Unique=aaabceUYqaaa;Perm=el; dir 2214 D> Type=cdir;Unique=aaabceUYqaaa;Perm=el; /sub/dir 2215 D> Type=dir;Unique=aaabchUYqaaa;Perm=el; misc 2216 D> Type=file;Unique=aaab8bUYqaaa;Perm=r;Size=34589; ftpd.c 2217 S> 226 That's all folks... 2218 C> CWD dir/ect 2219 S> 250 CWD command successful. 2220 C> PWD 2221 S> 257 "/sub/dir/ect" is current directory. 2222 C> PASV 2223 S> 227 Entering Passive Mode (127,0,0,1,255,40) 2224 C> MLSD 2225 S> 150 I tink I tee a trisector tree 2226 D> Type=dir;Unique=aaabcgUYqaaa;Perm=el; ory 2227 D> Type=pdir;Unique=aaabceUYqaaa;Perm=el; /sub/dir 2228 D> Type=pdir;Unique=aaabceUYqaaa;Perm=el; .. 2229 D> Type=cdir;Unique=aaabcfUYqaaa;Perm=el; /sub/dir/ect 2230 S> 226 That's all folks... 2231 C> CWD /files 2232 S> 250 CWD command successful. 2233 C> PASV 2234 S> 227 Entering Passive Mode (127,0,0,1,255,36) 2235 C> MLSD 2236 S> 150 I tink I tee a trisector tree 2237 D> Type=cdir;Unique=aaab8aUYqaaa;Perm=cpmel; /files 2238 D> Type=pdir;Unique=aaaaacUYqaaa;Perm=cpmel; / 2239 D> Type=pdir;Unique=aaaaacUYqaaa;Perm=cpmel; .. 2240 D> Type=file;Unique=aaab8cUYqaaa;Perm=rf;Size=15039; mlst.c 2241 D> Type=file;Unique=aaab8bUYqaaa;Perm=rf;Size=34589; ftpd.c 2242 S> 226 That's all folks... 2243 C> RNFR mlst.c 2244 S> 350 File exists, ready for destination name 2245 C> RNTO list.c 2246 S> 250 RNTO command successful. 2248 C> PASV 2249 S> 227 Entering Passive Mode (127,0,0,1,255,34) 2250 C> MLSD 2251 S> 150 I tink I tee a trisector tree 2252 D> Type=file;Unique=aaab8cUYqaaa;Perm=rf;Size=15039; list.c 2253 D> Type=pdir;Unique=aaaaacUYqaaa;Perm=cpmel; / 2254 D> Type=pdir;Unique=aaaaacUYqaaa;Perm=cpmel; .. 2255 D> Type=file;Unique=aaab8bUYqaaa;Perm=rf;Size=34589; ftpd.c 2256 D> Type=cdir;Unique=aaab8aUYqaaa;Perm=cpmel; /files 2257 S> 226 That's all folks... 2259 The server shown here returns its directory listings in seemingly 2260 random order, and even seems to modify the order of the directory as 2261 its contents change -- perhaps the underlying directory structure is 2262 based upon hashing of some kind. Note that the "pdir" and "cdir" 2263 entries are interspersed with other entries in the directory. Note 2264 also that this server does not show a "pdir" entry when listing the 2265 contents of the root directory of the virtual filestore, it does 2266 however include multiple "cdir" and "pdir" entries when it fees 2267 inclined. The server also uses obnoxiously "cute" messages. 2269 7.8. FEAT response for MLSx 2271 When responding to the FEAT command, a server-FTP process that 2272 supports MLST, and MLSD, plus internationalization of pathnames, MUST 2273 indicate that this support exists. It does this by including a MLST 2274 feature line. As well as indicating the basic support, the MLST 2275 feature line indicates which MLST facts are available from the 2276 server, and which of those will be returned if no subsequent "OPTS 2277 MLST" command is sent. 2279 mlst-feat = SP "MLST" [SP factlist] CRLF 2280 factlist = 1*( factname ["*"] ";" ) 2282 The initial space shown in the mlst-feat response is that required by 2283 the FEAT command, two spaces are not permitted. If no factlist is 2284 given, then the server-FTP process is indicating that it supports 2285 MLST, but implements no facts. Only pathnames can be returned. This 2286 would be a minimal MLST implementation, and useless for most 2287 practical purposes. Where the factlist is present, the factnames 2288 included indicate the facts supported by the server. Where the 2289 optional asterisk appears after a factname, that fact will be 2290 included in MLST format responses, until an "OPTS MLST" is given to 2291 alter the list of facts returned. After that, subsequent FEAT 2292 commands will return the asterisk to show the facts selected by the 2293 most recent "OPTS MLST". 2295 Note that there is no distinct FEAT output for MLSD. The presence of 2296 the MLST feature indicates that both MLST and MLSD are supported. 2298 7.8.1. Examples 2300 C> Feat 2301 S> 211- Features supported 2302 S> REST STREAM 2303 S> MDTM 2304 S> SIZE 2305 S> TVFS 2306 S> UTF8 2307 S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; 2308 S> 211 End 2310 Aside from some features irrelevant here, this server indicates that 2311 it supports MLST including several, but not all, standard facts, all 2312 of which it will send by default. It also supports two OS dependent 2313 facts, and one locally defined fact. The latter three must be 2314 requested expressly by the client for this server to supply them. 2316 C> Feat 2317 S> 211-Extensions supported: 2318 S> CLNT 2319 S> MDTM 2320 S> MLST type*;size*;modify*;UNIX.mode*;UNIX.owner;UNIX.group;unique; 2321 S> PASV 2322 S> REST STREAM 2323 S> SIZE 2324 S> TVFS 2325 S> Compliance Level: 19981201 (IETF mlst-05) 2326 S> 211 End. 2328 Again, in addition to some irrelevant features here, this server 2329 indicates that it supports MLST, four of the standard facts, one of 2330 which ("unique") is not enabled by default, and several OS dependent 2331 facts, one of which is provided by the server by default. This 2332 server actually supported more OS dependent facts. Others were 2333 deleted for the purposes of this document to comply with document 2334 formatting restrictions. 2336 C> FEAT 2337 S> 211-Features supported 2338 S> MDTM 2339 S> MLST Type*;Size*;Modify*;Perm;Unique*; 2340 S> REST STREAM 2341 S> SIZE 2342 S> TVFS 2343 S> 211 End 2345 This server has wisely chosen not to implement any OS dependent 2346 facts. At the time of writing this document, no such facts have been 2347 defined (using the mechanisms of section 10.1) so rational support 2348 for them would be difficult at best. All but one of the facts 2349 supported by this server are enabled by default. 2351 7.9. OPTS parameters for MLST 2353 For the MLSx commands, the Client-FTP may specify a list of facts it 2354 wishes to be returned in all subsequent MLSx commands until another 2355 OPTS MLST command is sent. The format is specified by: 2357 mlst-opts = "OPTS" SP "MLST" 2358 [ SP 1*( factname ";" ) ] 2360 By sending the "OPTS MLST" command, the client requests the server to 2361 include only the facts listed as arguments to the command in 2362 subsequent output from MLSx commands. Facts not included in the 2363 "OPTS MLST" command MUST NOT be returned by the server. Facts that 2364 are included should be returned for each entry returned from the MLSx 2365 command where they meaningfully apply. Facts requested that are not 2366 supported, or which are inappropriate to the file or directory being 2367 listed should simply be omitted from the MLSx output. This is not an 2368 error. Note that where no factname arguments are present, the client 2369 is requesting that only the file names be returned. In this case, 2370 and in any other case where no facts are included in the result, the 2371 space that separates the fact names and their values from the file 2372 name is still required. That is, the first character of the output 2373 line will be a space, (or two characters will be spaces when the line 2374 is returned over the control connection) and the file name will start 2375 immediately thereafter. 2377 Clients should note that generating values for some facts can be 2378 possible, but very expensive, for some servers. It is generally 2379 acceptable to retrieve any of the facts that the server offers as its 2380 default set before any "OPTS MLST" command has been given, however 2381 clients should use particular caution before requesting any facts not 2382 in that set. That is, while other facts may be available from the 2383 server, clients should refrain from requesting such facts unless 2384 there is a particular operational requirement for that particular 2385 information, which ought be more significant than perhaps simply 2386 improving the information displayed to an end user. 2388 Note, there is no "OPTS MLSD" command, the fact names set with the 2389 "OPTS MLST" command apply to both MLST and MLSD commands. 2391 Servers are not required to accept "OPTS MLST" commands before 2392 authentication of the user-PI, but may choose to permit them. 2394 7.9.1. OPTS MLST Response 2396 The "response-message" from [6] to a successful OPTS MLST command has 2397 the following syntax. 2399 mlst-opt-resp = "MLST OPTS" [ SP 1*( factname ";" ) ] 2401 This defines the "response-message" as used in the "opts-good" 2402 message in RFC2389 [6]. 2404 The facts named in the response are those which the server will now 2405 include in MLST (and MLSD) response, after the processing of the 2406 "OPTS MLST" command. Any facts from the request not supported by the 2407 server will be omitted from this response message. If no facts will 2408 be included, the list of facts will be empty. Note that the list of 2409 facts returned will be the same as those marked by a trailing 2410 asterisk ("*") in a subsequent FEAT command response. There is no 2411 requirement that the order of the facts returned be the same as that 2412 in which they were requested, or that in which they will be listed in 2413 a FEAT command response, or that in which facts are returned in MLST 2414 responses. The fixed string "MLST OPTS" in the response may be 2415 returned in any case, or mixture of cases. 2417 7.9.2. Examples 2419 C> Feat 2420 S> 211- Features supported 2421 S> MLST Type*;Size;Modify*;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2422 S> 211 End 2423 C> OptS Mlst Type;UNIX.mode;Perm; 2424 S> 200 MLST OPTS Type;Perm;UNIX.mode; 2425 C> Feat 2426 S> 211- Features supported 2427 S> MLST Type*;Size;Modify;Perm*;Unique;UNIX.mode*;UNIX.chgd;X.hidden; 2428 S> 211 End 2429 C> opts MLst lang;type;charset;create; 2430 S> 200 MLST OPTS Type; 2431 C> Feat 2432 S> 211- Features supported 2433 S> MLST Type*;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2434 S> 211 End 2435 C> OPTS mlst size;frogs; 2436 S> 200 MLST OPTS Size; 2437 C> Feat 2438 S> 211- Features supported 2439 S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2440 S> 211 End 2441 C> opts MLst unique type; 2442 S> 501 Invalid MLST options 2443 C> Feat 2444 S> 211- Features supported 2445 S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2446 S> 211 End 2448 For the purposes of this example, features other than MLST have been 2449 deleted from the output to avoid clutter. The example shows the 2450 initial default feature output for MLST. The facts requested are 2451 then changed by the client. The first change shows facts that are 2452 available from the server being selected. Subsequent FEAT output 2453 shows the altered features as being returned. The client then 2454 attempts to select some standard features which the server does not 2455 support. This is not an error, however the server simply ignores the 2456 requests for unsupported features, as the FEAT output that follows 2457 shows. Then, the client attempts to request a non-standard, and 2458 unsupported, feature. The server ignores that, and selects only the 2459 supported features requested. Lastly, the client sends a request 2460 containing a syntax error (spaces cannot appear in the factlist.) 2461 The server-FTP sends an error response and completely ignores the 2462 request, leaving the fact set selected as it had been previously. 2464 Note that in all cases, except the error response, the response lists 2465 the facts that have been selected. 2467 C> Feat 2468 S> 211- Features supported 2469 S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; 2470 S> 211 End 2471 C> Opts MLST 2472 S> 200 MLST OPTS 2473 C> Feat 2474 S> 211- Features supported 2475 S> MLST Type;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; 2476 S> 211 End 2477 C> MLst tmp 2478 S> 250- Listing tmp 2479 S> /tmp 2480 S> 250 End 2481 C> OPTS mlst unique;size; 2482 S> 200 MLST OPTS Size;Unique; 2483 C> MLst tmp 2484 S> 250- Listing tmp 2485 S> Unique=keVO1+YZ5; /tmp 2486 S> 250 End 2487 C> OPTS mlst unique;type;modify; 2488 S> 200 MLST OPTS Type;Modify;Unique; 2489 C> MLst tmp 2490 S> 250- Listing tmp 2491 S> Type=dir;Modify=19990930152225;Unique=keVO1+YZ5; /tmp 2492 S> 250 End 2493 C> OPTS mlst fish;cakes; 2494 S> 200 MLST OPTS 2495 C> MLst tmp 2496 S> 250- Listing tmp 2497 S> /tmp 2498 S> 250 End 2499 C> OptS Mlst Modify;Unique; 2500 S> 200 MLST OPTS Modify;Unique; 2501 C> MLst tmp 2502 S> 250- Listing tmp 2503 S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp 2504 S> 250 End 2505 C> opts MLst fish cakes; 2506 S> 501 Invalid MLST options 2507 C> MLst tmp 2508 S> 250- Listing tmp 2509 S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp 2510 S> 250 End 2512 This example shows the effect of changing the facts requested upon 2513 subsequent MLST commands. Notice that a syntax error leaves the set 2514 of selected facts unchanged. Also notice exactly two spaces 2515 preceding the pathname when no facts were selected, either 2516 deliberately, or because none of the facts requested were available. 2518 8. Impact On Other FTP Commands 2520 Along with the introduction of MLST, traditional FTP commands must be 2521 extended to allow for the use of more than US-ASCII[1] or EBCDIC 2522 character sets. In general, the support of MLST requires support for 2523 arbitrary character sets wherever file names and directory names are 2524 allowed. This applies equally to both arguments given to the 2525 following commands and to the replies from them, as appropriate. 2527 APPE RMD 2528 CWD RNFR 2529 DELE RNTO 2530 MKD STAT 2531 PWD STOR 2532 RETR STOU 2534 The arguments to all of these commands should be processed the same 2535 way that MLST commands and responses are processed with respect to 2536 handling embedded spaces, CRs and NULs. See section 2.2. 2538 9. Character sets and Internationalization 2540 FTP commands are protocol elements, and are always expressed in 2541 ASCII. FTP responses are composed of the numeric code, which is a 2542 protocol element, and a message, which is often expected to convey 2543 information to the user. It is not expected that users normally 2544 interact directly with the protocol elements, rather the user FTP- 2545 process constructs the commands, and interprets the results, in the 2546 manner best suited for the particular user. Explanatory text in 2547 responses generally has no particular meaning to the protocol. The 2548 numeric codes provide all necessary information. Server-PIs are free 2549 to provide the text in any language that can be adequately 2550 represented in ASCII, or where an alternative language and 2551 representation has been negotiated (see [7]) in that language and 2552 representation. 2554 Pathnames are expected to be encoded in UTF-8 allowing essentially 2555 any character to be represented in a pathname. Meaningful pathnames 2556 are defined by the server NVFS. 2558 No restrictions at all are placed upon the contents of files 2559 transferred using the FTP protocols. Unless the "media-type" fact is 2560 provided in a MLSx response nor is any advice given here which would 2561 allow determining the content type. That information is assumed to 2562 be obtained via other means. 2564 10. IANA Considerations 2566 This specification makes use of some lists of values currently 2567 maintained by the IANA, and creates two new lists for the IANA to 2568 maintain. It does not add any values to any existing registries. 2570 The existing IANA registries used by this specification are modified 2571 using mechanisms specified elsewhere. 2573 10.1. The OS specific fact registry 2575 A registry of OS specific fact names shall be maintained by the IANA. 2576 The OS names for the OS portion of the fact name must be taken from 2577 the IANA's list of registered OS names. To add a fact name to this 2578 OS specific registry of OS specific facts, an applicant must send to 2579 the IANA a request, in which is specified the OS name, the OS 2580 specific fact name, a definition of the syntax of the fact value, 2581 which must conform to the syntax of a token as given in this 2582 document, and a specification of the semantics to be associated with 2583 the particular fact and its values. Upon receipt of such an 2584 application, and if the combination of OS name and OS specific fact 2585 name has not been previously defined, the IANA will add the 2586 specification to the registry. 2588 Any examples of OS specific facts found in this document are to be 2589 treated as examples of possible OS specific facts, and do not form a 2590 part of the IANA's registry merely because of being included in this 2591 document. 2593 10.2. The OS specific filetype registry 2595 A registry of OS specific file types shall be maintained by the IANA. 2596 The OS names for the OS portion of the fact name must be taken from 2597 the IANA's list of registered OS names. To add a file type to this 2598 OS specific registry of OS specific file types, an applicant must 2599 send to the IANA a request, in which is specified the OS name, the OS 2600 specific file type, a definition of the syntax of the fact value, 2601 which must conform to the syntax of a token as given in this 2602 document, and a specification of the semantics to be associated with 2603 the particular fact and its values. Upon receipt of such an 2604 application, and if the combination of OS name and OS specific file 2605 type has not been previously defined, the IANA will add the 2606 specification to the registry. 2608 Any examples of OS specific file types found in this document are to 2609 be treated as potential OS specific file types only, and do not form 2610 a part of the IANA's registry merely because of being included in 2611 this document. 2613 11. Security Considerations 2615 This memo does not directly concern security. It is not believed 2616 that any of the mechanisms documented here impact in any particular 2617 way upon the security of FTP. 2619 Implementing the SIZE command, and perhaps some of the facts of the 2620 MLSx commands, may impose a considerable load on the server, which 2621 could lead to denial of service attacks. Servers have, however, 2622 implemented this for many years, without significant reported 2623 difficulties. 2625 Server FTP should take care not to reveal sensitive information about 2626 files to unauthorised parties. In particular, some underlying 2627 filesystems provide a file identifier which, if known, can allow many 2628 of the filesystem protection mechanisms to be by-passed. That 2629 identifier would not be a suitable choice to use as the basis of the 2630 value of the unique fact. 2632 The FEAT and OPTS commands may be issued before the FTP 2633 authentication has occurred [6]. This allows unauthenticated clients 2634 to determine which of the features defined here are supported, and to 2635 negotiate the fact list for MLSx output. No actual MLSx commands may 2636 be issued however, and no problems with permitting the selection of 2637 the format prior to authentication are foreseen. 2639 A general discussion of issues related to the security of FTP can be 2640 found in [14]. 2642 12. Normative References 2644 [1] Coded Character Set--7-bit American Standard Code for Information 2645 Interchange, ANSI X3.4-1986. 2647 [2] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO 2648 10646", RFC 2044, October 1996. 2650 [3] Postel, J., Reynolds, J., "File Transfer Protocol (FTP)", 2651 STD 9, RFC 959, October 1985 2653 [4] Bradner, S., "Key words for use in RFCs to Indicate 2654 Requirement Levels", BCP 14, RFC 2119, March 1997 2656 [5] Crocker, D., Overell, P., "Augmented BNF for Syntax 2657 Specifications: ABNF", RFC 2234, November 1997 2659 [6] Hethmon, P., Elz, R., "Feature negotiation mechanism for the 2660 File Transfer Protocol", RFC 2389, August 1998 2662 [7] Curtin, W., "Internationalization of the File Transfer Protocol", 2663 RFC 2640, July 1999 2665 [8] Postel, J., Reynolds, J., "Telnet protocol Specification" 2666 STD 8, RFC 854, May 1983 2668 [9] Braden, R,. "Requirements for Internet Hosts -- Application 2669 and Support", STD 3, RFC 1123, October 1989 2671 [10] Mockapetris, P., "Domain Names -- Concepts and Facilities" 2672 STD 13, RFC 1034, November 1987 2674 [11] ISO/IEC 10646-1:1993 "Universal multiple-octet coded character set 2675 (UCS) -- Part 1: Architecture and basic multilingual plane", 2676 International Standard -- Information Technology, 1993 2678 [12] Internet Assigned Numbers Authority. http://www.iana.org 2679 Email: iana@iana.org. 2681 [13] Alvestrand, H., "Tags for the Identification of Languages" 2682 RFC 1766, March 1995 2684 [14] Allman, M., Ostermann, S., "FTP Security Considerations" 2685 RFC 2577, May 1999 2687 Acknowledgments 2689 This document is a product of the FTPEXT working group of the IETF. 2691 The following people are among those who have contributed to this 2692 document: 2694 Alex Belits 2695 D. J. Bernstein 2696 Dave Cridland 2697 Martin J. Duerst 2698 Bill Fenner (and the rest of the IESG) 2699 Paul Ford-Hutchinson 2700 Mike Gleason 2701 Mark Harris 2702 Stephen Head 2703 Alun Jones 2704 Andrew Main 2705 James Matthews 2706 Luke Mewburn 2707 Jan Mikkelsen 2708 Keith Moore 2709 Buz Owen 2710 Mark Symons 2711 Stephen Tihor 2712 and the entire FTPEXT working group of the IETF. 2714 Apologies are offered to any inadvertently omitted. 2716 The description of the modifications to the REST command and the MDTM 2717 and SIZE commands comes from a set of modifications suggested for 2718 RFC959 by Rick Adams in 1989. A draft containing just those 2719 commands, edited by David Borman, has been merged with this document. 2721 Mike Gleason, Alun Jones and Luke Mewburn provided access to FTP 2722 servers used in some of the examples. 2724 All of the examples in this document are taken from actual 2725 client/server exchanges, though some have been edited for brevity, or 2726 to meet document formatting requirements. 2728 Copyright 2730 This document is in the public domain. Any and all copyright 2731 protection that might apply in any jurisdiction is expressly 2732 disclaimed. 2734 In addition, some lawyer somewhere says this document could, or 2735 should, say: The authors hereby relinquish any claim to any copyright 2736 that they may have in this work, whether granted under contract or by 2737 operation of law or international treaty, and hereby commit to the 2738 public, at large, that they shall not, at any time in the future, 2739 seek to enforce any copyright in this work against any person or 2740 entity, or prevent any person or entity from copying, publishing, 2741 distributing or creating derivative works of this work. 2743 The editors believe that the first paragraph of this section implies 2744 the second. 2746 Note that the authors of this document are the IETF community at 2747 large, and the FTPEXT working group in particular. Those individuals 2748 named below are merely those who copied the IETF's work onto 2749 (electronic) paper. 2751 Editors' Addresses 2753 Robert Elz 2754 Prince of Songkla University 2755 Department of Computer Enginering 2756 Hat Yai, 90112 2757 Thailand 2759 Email: kre@munnari.OZ.AU 2761 Paul Hethmon 2762 Hethmon Brothers 2763 2305 Chukar Road 2764 Knoxville, TN 37923 USA 2766 Phone: +1 423 690 8990 2767 Email: phethmon@hethmon.com