Retrieving Files: RETR and REST Commands

The RETR command -- Retrieve a file

A RETR request asks the server to send the contents of a file over the data connection already established by the client. The RETR parameter is an encoded pathname of the file. The file is either a binary file or a text file, depending on the most recent TYPE request.

Normally the server responds with a mark using code 150. It then stops accepting new connections, attempts to send the contents of the file over the data connection, and closes the data connection. Finally it

• accepts the RETR request with code 226 if the entire file was successfully written to the server's TCP buffers;
• rejects the RETR request with code 425 if no TCP connection was established;
• rejects the RETR request with code 426 if the TCP connection was established but then broken by the client or by network failure; or
• rejects the RETR request with code 451 or 551 if the server had trouble reading the file from disk. The server is obliged to close the data connection in each of these cases. The client is not expected to look for a response from the server until the client sees that the data connection is closed.

The server may reject the RETR request without first responding with a mark. In this case the server does not touch the data connection.

The client needs to be prepared for many different ways that RETR can fail:

1.

After sending the RETR request, the client reads one response from the server. If this response is anything but a mark (for example, the server can't find the file, or doesn't have permission to open it, or is temporarily out of memory, or the server crashes and the connection is closed without a response, or the server is overloaded and the client times out before receiving a response), the client stops and reports temporary failure.

2.

After sending the RETR request and reading a mark, the client reads data from the data connection until FIN (end of file), or a TCP error (for example, TCP reset or network unreachable), or timeout. The client saves the data, remembers whether there was a FIN, and closes the data connection.

3.

After sending the RETR request, reading a mark, reading data from the data connection, and closing the data connection, the client reads another response from the server. If this response is acceptance and the data connection ended with FIN, the client knows that it has received the entire file from the server. Otherwise the client reports temporary failure; the file has (probably) been truncated. Note that code 226 from the server does not guarantee that the client has received, or will receive, the entire file. The client must check for TCP errors on the data connection.

Some clients do not close the data connection until they receive the 226 response from the server.

The REST command -- Restart download

The server keeps track of a start position for the client. The start position is a nonnegative integer. At the beginning of the FTP connection, the start position is 0.

The start position changes the meaning of RETR for binary files as follows: if the start position is n, the server will omit the first n bytes of the data that it sends through the data connection.

Some servers also allow start positions for text files, with the same semantics: omit the first n bytes of data transferred through the data connection. However, clients cannot rely on this. Most existing servers skip a different number of bytes for text files.

A REST request sets the start position. REST has a parameter giving a number as ASCII digits. If the server accepts the REST request (required code 350), it has set the start position to that number. If the server rejects the REST request, it has left the start position alone.

The server will set the start position to 0 after a successful RETR, but might not set the start position to 0 after an unsuccessful RETR, so the client must be careful to send a new REST request before the next RETR. The server might set the start position to 0 after responding to any request other than REST, so the client must send REST immediately before RETR.

Servers are not required to implement REST. However, many clients can take advantage of REST to save time if a previous transfer was interrupted in the middle.

Clients beware: the file may have changed since the time of the previous transfer.