libftp

A cross-platform FTP/FTPS client library built on Boost.Asio.

Table of contents

1. Overview
2. Features
3. Examples
4. Integration
5. Building
6. References

Overview

This library provides client-side functionality for the File Transfer Protocol (FTP), offering a flexible solution for transferring files between a client and a server.

Connections

FTP employs two separate connections:

• Control connection: A persistent connection used to exchange commands and replies between the client and the server.
• Data connection: A temporary connection established solely for transferring files. It remains open only for the duration of the transfer.

Transfer modes

The transfer mode determines how the data connection is established.

Active mode

• The client uses the control connection to send the server its own IP address and a port number where it will accept an incoming data connection.
• The server then uses this information to initiate and open the data connection to the client.

Passive mode

• The client uses the control connection to request the server's IP address and a port number where the server will accept an incoming data connection.
• The client then uses this information to initiate and open the data connection to the server.

This mode is useful in scenarios where the client is unable to accept incoming connections, such as when operating behind a firewall or NAT.

Transfer types

The transfer type determines how data is transferred.

ASCII type

• The sender converts newline characters from system style to CRLF style, and the receiver performs the reverse conversion.
• Suitable for transferring text files between systems with different newline conventions.

Binary type

• Transfers files byte by byte without modifications.
• Ideal for binary files, including images, videos, and archives.

Features

• Windows, Linux and macOS are supported.
• Supports FTP and FTP over TLS/SSL (FTPS).
• Supports IPv4 and IPv6.
• Supports active and passive transfer modes.
• Supports ASCII and binary transfer types.

Examples

Download the README.TXT file from ftp.freebsd.org and output its contents to stdout:

#include <iostream>
#include <sstream>

#include <ftp/ftp.hpp>

int main(int argc, char *argv[])
{
    ftp::client client;

    client.connect("ftp.freebsd.org", 21, "anonymous");

    std::ostringstream oss;

    client.download_file(ftp::ostream_adapter(oss), "pub/FreeBSD/README.TXT");

    std::cout << oss.str();

    client.disconnect();

    return 0;
}

See more examples in the example folder.

Integration

This library can be integrated into a project via CMake's FetchContent, for example:

cmake_minimum_required(VERSION 3.14)
project(application)

include(FetchContent)
FetchContent_Declare(
        libftp
        GIT_REPOSITORY https://github.com/deniskovalchuk/libftp.git
        GIT_TAG        v1.5.0)
FetchContent_MakeAvailable(libftp)

add_executable(application main.cpp)
target_link_libraries(application ftp::ftp)

Building

Prerequisites

• A C++17-compliant compiler
• CMake 3.14 or newer
• Boost 1.88 or newer
• OpenSSL
• Python3, pyOpenSSL (only for tests)

Windows

Build and run tests:

tool/windows/build.ps1 [-BuildType Debug|Release] [-RunTest]

Clean the builds:

tool/windows/clean.ps1

Linux/macOS

Build and run tests:

tool/unix/build.sh [--debug | --release] [--test]

Clean the builds:

tool/unix/clean.sh

Custom environment

Build:

$ mkdir -p build
$ cd build
$ cmake ..
$ cmake --build .

To run tests, set the LIBFTP_TEST_SERVER_PATH environment variable to the path to the server.py file:

$ export LIBFTP_TEST_SERVER_PATH="/path/to/server.py"
$ cd test
$ ctest -V

References

• RFC 959 File Transfer Protocol (FTP). J. Postel, J. Reynolds. October 1985.
• RFC 2228 FTP Security Extensions. October 1997.
• RFC 2428 Extensions for IPv6, NAT, and Extended passive mode. September 1998.
• RFC 3659 Extensions to FTP. P. Hethmon. March 2007.
• RFC 4217 Securing FTP with TLS. October 2005.