4.2. FTP REPLIES
Replies to File Transfer Protocol commands are devised to ensure the synchronization of requests and actions in the process of file transfer, and to guarantee that the user process always knows the state of the Server. Every command must generate at least one reply, although there may be more than one; in the latter case, the multiple replies must be easily distinguished. In addition, some commands occur in sequential groups, such as USER, PASS and ACCT, or RNFR and RNTO. The replies show the existence of an intermediate state if all preceding commands have been successful. A failure at any point in the sequence necessitates the repetition of the entire sequence from the beginning.
The details of the command-reply sequence are made explicit in a set of state diagrams below.
An FTP reply consists of a three digit number (transmitted as three alphanumeric characters) followed by some text. The number is intended for use by automata to determine what state to enter next; the text is intended for the human user. It is intended that the three digits contain enough encoded information that the user-process (the User-PI) will not need to examine the text and may either discard it or pass it on to the user, as appropriate. In particular, the text may be server-dependent, so there are likely to be varying texts for each reply code.
A reply is defined to contain the 3-digit code, followed by Space <SP>, followed by one line of text (where some maximum line length has been specified), and terminated by the Telnet end-of-line code. There will be cases however, where the text is longer than a single line. In these cases the complete text must be bracketed so the User-process knows when it may stop reading the reply (i.e. stop processing input on the control connection) and go do other things. This requires a special format on the first line to indicate that more than one line is coming, and another on the last line to designate it as the last. At least one of these must contain the appropriate reply code to indicate the state of the transaction. To satisfy all factions, it was decided that both the first and last line codes should be the same.
Thus the format for multi-line replies is that the first line will begin with the exact required reply code, followed immediately by a Hyphen, "-" (also known as Minus), followed by text. The last line will begin with the same code, followed immediately by Space <SP>, optionally some text, and the Telnet end-of-line code.
For example:
123-First line
Second line
234 A line beginning with numbers
123 The last line
The user-process then simply needs to search for the second occurrence of the same reply code, followed by <SP> (Space), at the beginning of a line, and ignore all intermediary lines. If an intermediary line begins with a 3-digit number, the Server must pad the front to avoid confusion.
This scheme allows standard system routines to be used for reply information (such as for the STAT reply), with "artificial" first and last lines tacked on. In rare cases where these routines are able to generate three digits and a Space at the beginning of any line, the beginning of each text line should be offset by some neutral text, like Space.
This scheme assumes that multi-line replies may not be nested.
Reply Code Structure
The three digits of the reply each have a special significance. This is intended to allow a range of very simple to very sophisticated responses by the user-process. The first digit denotes whether the response is good, bad or incomplete. (Referring to the state diagram), an unsophisticated user-process will be able to determine its next action (proceed as planned, redo, retrench, etc.) by simply examining this first digit. A user-process that wants to know approximately what kind of error occurred (e.g. file system error, command syntax error) may examine the second digit, reserving the third digit for the finest gradation of information (e.g., RNTO command without a preceding RNFR).
First Digit Values
There are five values for the first digit of the reply code:
1yz - Positive Preliminary reply
The requested action is being initiated; expect another reply before proceeding with a new command. (The user-process sending another command before the completion reply would be in violation of protocol; but server-FTP processes should queue any commands that arrive while a preceding command is in progress.) This type of reply can be used to indicate that the command was accepted and the user-process may now pay attention to the data connections, for implementations where simultaneous monitoring is difficult. The server-FTP process may send at most, one 1yz reply per command.
2yz - Positive Completion reply
The requested action has been successfully completed. A new request may be initiated.
3yz - Positive Intermediate reply
The command has been accepted, but the requested action is being held in abeyance, pending receipt of further information. The user should send another command specifying this information. This reply is used in command sequence groups.
4yz - Transient Negative Completion reply
The command was not accepted and the requested action did not take place, but the error condition is temporary and the action may be requested again. The user should return to the beginning of the command sequence, if any. It is difficult to assign a meaning to "transient", particularly when two distinct sites (Server- and User-processes) have to agree on the interpretation. Each reply in the 4yz category might have a slightly different time value, but the intent is that the user-process is encouraged to try again. A rule of thumb in determining if a reply fits into the 4yz or the 5yz (Permanent Negative) category is that replies are 4yz if the commands can be repeated without any change in command form or in properties of the User or Server (e.g., the command is spelled the same with the same arguments used; the user does not change his file access or user name; the server does not put up a new implementation.)
5yz - Permanent Negative Completion reply
The command was not accepted and the requested action did not take place. The User-process is discouraged from repeating the exact request (in the same sequence). Even some "permanent" error conditions can be corrected, so the human user may want to direct his User-process to reinitiate the command sequence by direct action at some point in the future (e.g., after the spelling has been changed, or the user has altered his directory status.)
Second Digit Function Groupings
The following function groupings are encoded in the second digit:
-
x0z - Syntax - These replies refer to syntax errors, syntactically correct commands that don't fit any functional category, unimplemented or superfluous commands.
-
x1z - Information - These are replies to requests for information, such as status or help.
-
x2z - Connections - Replies referring to the control and data connections.
-
x3z - Authentication and accounting - Replies for the login process and accounting procedures.
-
x4z - Unspecified as yet.
-
x5z - File system - These replies indicate the status of the Server file system vis-a-vis the requested transfer or other file system action.
The third digit gives a finer gradation of meaning in each of the function categories, specified by the second digit. The list of replies below will illustrate this. Note that the text associated with each reply is recommended, rather than mandatory, and may even change according to the command with which it is associated. The reply codes, on the other hand, must strictly follow the specifications in the last section; that is, Server implementations should not invent new codes for situations that are only slightly different from the ones described here, but rather should adapt codes already defined.
A command such as TYPE or ALLO whose successful execution does not offer the user-process any new information will cause a 200 reply to be returned. If the command is not implemented by a particular Server-FTP process because it has no relevance to that computer system, for example ALLO at a TOPS20 site, a Positive Completion reply is still desired so that the simple User-process knows it can proceed with its course of action. A 202 reply is used in this case with, for example, the reply text: "No storage allocation necessary." If, on the other hand, the command requests a non-site-specific action and is unimplemented, the response is 502. A refinement of that is the 504 reply for a command that is implemented, but that requests an unimplemented parameter.
4.2.1 Reply Codes by Function Groups
| Code | Description |
|---|---|
| 200 | Command okay. |
| 500 | Syntax error, command unrecognized. This may include errors such as command line too long. |
| 501 | Syntax error in parameters or arguments. |
| 202 | Command not implemented, superfluous at this site. |
| 502 | Command not implemented. |
| 503 | Bad sequence of commands. |
| 504 | Command not implemented for that parameter. |
| Code | Description |
|---|---|
| 110 | Restart marker reply. In this case, the text is exact and not left to the particular implementation; it must read: MARK yyyy = mmmm. Where yyyy is User-process data stream marker, and mmmm server's equivalent marker (note the spaces between markers and "="). |
| 211 | System status, or system help reply. |
| 212 | Directory status. |
| 213 | File status. |
| 214 | Help message. On how to use the server or the meaning of a particular non-standard command. This reply is useful only to the human user. |
| 215 | NAME system type. Where NAME is an official system name from the list in the Assigned Numbers document. |
| Code | Description |
|---|---|
| 120 | Service ready in nnn minutes. |
| 220 | Service ready for new user. |
| 221 | Service closing control connection. Logged out if appropriate. |
| 421 | Service not available, closing control connection. This may be a reply to any command if the service knows it must shut down. |
| 125 | Data connection already open; transfer starting. |
| 225 | Data connection open; no transfer in progress. |
| 425 | Can't open data connection. |
| 226 | Closing data connection. Requested file action successful (for example, file transfer or file abort). |
| 426 | Connection closed; transfer aborted. |
| 227 | Entering Passive Mode (h1,h2,h3,h4,p1,p2). |
| Code | Description |
|---|---|
| 230 | User logged in, proceed. |
| 530 | Not logged in. |
| 331 | User name okay, need password. |
| 332 | Need account for login. |
| 532 | Need account for storing files. |
| Code | Description |
|---|---|
| 150 | File status okay; about to open data connection. |
| 250 | Requested file action okay, completed. |
| 257 | "PATHNAME" created. |
| 350 | Requested file action pending further information. |
| 450 | Requested file action not taken. File unavailable (e.g., file busy). |
| 550 | Requested action not taken. File unavailable (e.g., file not found, no access). |
| 451 | Requested action aborted. Local error in processing. |
| 551 | Requested action aborted. Page type unknown. |
| 452 | Requested action not taken. Insufficient storage space in system. |
| 552 | Requested file action aborted. Exceeded storage allocation (for current directory or dataset). |
| 553 | Requested action not taken. File name not allowed. |
4.2.2 Numeric Order List of Reply Codes
| Code | Description |
|---|---|
| 110 | Restart marker reply. |
| 120 | Service ready in nnn minutes. |
| 125 | Data connection already open; transfer starting. |
| 150 | File status okay; about to open data connection. |
| 200 | Command okay. |
| 202 | Command not implemented, superfluous at this site. |
| 211 | System status, or system help reply. |
| 212 | Directory status. |
| 213 | File status. |
| 214 | Help message. |
| 215 | NAME system type. |
| 220 | Service ready for new user. |
| 221 | Service closing control connection. |
| 225 | Data connection open; no transfer in progress. |
| 226 | Closing data connection. Requested file action successful. |
| 227 | Entering Passive Mode (h1,h2,h3,h4,p1,p2). |
| 230 | User logged in, proceed. |
| 250 | Requested file action okay, completed. |
| 257 | "PATHNAME" created. |
| 331 | User name okay, need password. |
| 332 | Need account for login. |
| 350 | Requested file action pending further information. |
| 421 | Service not available, closing control connection. |
| 425 | Can't open data connection. |
| 426 | Connection closed; transfer aborted. |
| 450 | Requested file action not taken. File unavailable. |
| 451 | Requested action aborted: local error in processing. |
| 452 | Requested action not taken. Insufficient storage space in system. |
| 500 | Syntax error, command unrecognized. |
| 501 | Syntax error in parameters or arguments. |
| 502 | Command not implemented. |
| 503 | Bad sequence of commands. |
| 504 | Command not implemented for that parameter. |
| 530 | Not logged in. |
| 532 | Need account for storing files. |
| 550 | Requested action not taken. File unavailable. |
| 551 | Requested action aborted: page type unknown. |
| 552 | Requested file action aborted. Exceeded storage allocation. |
| 553 | Requested action not taken. File name not allowed. |