libtorrent
Description: A feature complete BitTorrent protocol implementation as a C++ library

Version: | 2.0.8

home

Table of contents

- storage_params
- file_slice
- file_storage
  - is_valid()
  - reserve()
  - add_file() add_file_borrow()
  - rename_file()
  - map_block()
  - map_file()
  - num_files()
  - end_file()
  - file_range()
  - total_size()
  - num_pieces() set_num_pieces()
  - end_piece()
  - last_piece()
  - piece_range()
  - piece_length() set_piece_length()
  - piece_size()
  - piece_size2()
  - blocks_in_piece2()
  - set_name() name()
  - swap()
  - canonicalize()
  - file_size() file_name() root_ptr() hash() file_path() root() pad_file_at() mtime() symlink() file_offset()
  - file_num_blocks() file_num_pieces() file_piece_range()
  - file_first_piece_node() file_first_block_node()
  - file_path_hash()
  - all_path_hashes()
  - file_flags()
  - file_absolute_path()
  - file_index_at_offset() file_index_at_piece()
  - file_index_for_root()
  - piece_index_at_file()
  - sanitize_symlinks()
  - v2()
- default_disk_io_constructor()
- posix_disk_io_constructor()
- mmap_disk_io_constructor()
- disabled_disk_io_constructor()
- enum storage_mode_t
- enum status_t
- enum move_flags_t

[report issue]

# storage_params

Declared in "libtorrent/storage_defs.hpp"

a parameter pack used to construct the storage for a torrent, used in disk_interface

    struct storage_params
    {
       storage_params (file_storage const& f, file_storage const* mf
          , std::string const& sp, storage_mode_t const sm
          , aux::vector<download_priority_t, file_index_t> const& prio
          , sha1_hash const& ih);

       file_storage const& files;
       file_storage const* mapped_files  = nullptr;
       std::string const& path;
       storage_mode_t mode {storage_mode_sparse};
       aux::vector<download_priority_t, file_index_t> const& priorities;
       sha1_hash info_hash;
    };

[report issue]

# file_slice

Declared in "libtorrent/file_storage.hpp"

represents a window of a file in a torrent.

The `file_index` refers to the index of the file (in the torrent_info). To get the path and filename, use `file_path()` and give the `file_index` as argument. The `offset` is the byte offset in the file where the range starts, and `size` is the number of bytes this range is. The size + offset will never be greater than the file size.

    struct file_slice
    {
       file_index_t file_index;
       std::int64_t offset;
       std::int64_t size;
    };

[report issue]

file_index
  the index of the file

[report issue]

offset
  the offset from the start of the file, in bytes

[report issue]

size
  the size of the window, in bytes

[report issue]

# file_storage

Declared in "libtorrent/file_storage.hpp"

The `file_storage` class represents a file list and the piece size. Everything necessary to interpret a regular bittorrent storage file structure.

    class file_storage
    {
       bool is_valid () const;
       void reserve (int num_files);
       void add_file (std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}
          , std::time_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
       void add_file_borrow (error_code& ec, string_view filename
          , std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}, char const* filehash = nullptr
          , std::int64_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
       void add_file (error_code& ec, std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}
          , std::time_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
       void add_file_borrow (string_view filename
          , std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}, char const* filehash = nullptr
          , std::int64_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
       void rename_file (file_index_t index, std::string const& new_filename);
       std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
          , std::int64_t size) const;
       peer_request map_file (file_index_t file, std::int64_t offset, int size) const;
       int num_files () const noexcept;
       file_index_t end_file () const noexcept;
       index_range<file_index_t> file_range () const noexcept;
       std::int64_t total_size () const;
       void set_num_pieces (int n);
       int num_pieces () const;
       piece_index_t end_piece () const;
       piece_index_t last_piece () const;
       index_range<piece_index_t> piece_range () const noexcept;
       void set_piece_length (int l);
       int piece_length () const;
       int piece_size (piece_index_t index) const;
       int piece_size2 (piece_index_t index) const;
       int blocks_in_piece2 (piece_index_t index) const;
       std::string const& name () const;
       void set_name (std::string const& n);
       void swap (file_storage& ti) noexcept;
       void canonicalize ();
       sha1_hash hash (file_index_t index) const;
       std::int64_t file_size (file_index_t index) const;
       char const* root_ptr (file_index_t const index) const;
       std::time_t mtime (file_index_t index) const;
       std::string symlink (file_index_t index) const;
       sha256_hash root (file_index_t index) const;
       bool pad_file_at (file_index_t index) const;
       std::string file_path (file_index_t index, std::string const& save_path = "") const;
       std::int64_t file_offset (file_index_t index) const;
       string_view file_name (file_index_t index) const;
       index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
       int file_num_blocks (file_index_t index) const;
       int file_num_pieces (file_index_t index) const;
       int file_first_piece_node (file_index_t index) const;
       int file_first_block_node (file_index_t index) const;
       std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;
       void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;
       file_flags_t file_flags (file_index_t index) const;
       bool file_absolute_path (file_index_t index) const;
       file_index_t file_index_at_offset (std::int64_t offset) const;
       file_index_t file_index_at_piece (piece_index_t piece) const;
       file_index_t file_index_for_root (sha256_hash const& root_hash) const;
       piece_index_t piece_index_at_file (file_index_t f) const;
       void sanitize_symlinks ();
       bool v2 () const;

       static constexpr file_flags_t flag_pad_file  = 0_bit;
       static constexpr file_flags_t flag_hidden  = 1_bit;
       static constexpr file_flags_t flag_executable  = 2_bit;
       static constexpr file_flags_t flag_symlink  = 3_bit;
    };

[report issue]

## is_valid()

    bool is_valid () const;

returns true if the piece length has been initialized on the file_storage. This is typically taken as a proxy of whether the file_storage as a whole is initialized or not.

[report issue]

## reserve()

    void reserve (int num_files);

allocates space for `num_files` in the internal file list. This can be used to avoid reallocating the internal file list when the number of files to be added is known up-front.

[report issue]

## add_file() add_file_borrow()

    void add_file (std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}
          , std::time_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
    void add_file_borrow (error_code& ec, string_view filename
          , std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}, char const* filehash = nullptr
          , std::int64_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
    void add_file (error_code& ec, std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}
          , std::time_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);
    void add_file_borrow (string_view filename
          , std::string const& path, std::int64_t file_size
          , file_flags_t file_flags = {}, char const* filehash = nullptr
          , std::int64_t mtime = 0, string_view symlink_path = string_view()
          , char const* root_hash = nullptr);

Adds a file to the file storage. The `add_file_borrow` version expects that `filename` is the file name (without a path) of the file that's being added. This memory is borrowed, i.e. it is the caller's responsibility to make sure it stays valid throughout the lifetime of this file_storage object or any copy of it. The same thing applies to `filehash`, which is an optional pointer to a 20 byte binary SHA-1 hash of the file.

if `filename` is empty, the filename from `path` is used and not borrowed.

The `path` argument is the full path (in the torrent file) to the file to add. Note that this is not supposed to be an absolute path, but it is expected to include the name of the torrent as the first path element.

`file_size` is the size of the file in bytes.

The `file_flags` argument sets attributes on the file. The file attributes is an extension and may not work in all bittorrent clients.

For possible file attributes, see file_storage::flags_t.

The `mtime` argument is optional and can be set to 0. If non-zero, it is the posix time of the last modification time of this file.

`symlink_path` is the path the file is a symlink to. To make this a symlink you also need to set the file_storage::flag_symlink file flag.

`root_hash` is an optional pointer to a 32 byte SHA-256 hash, being the merkle tree root hash for this file. This is only used for v2 torrents. If the `root hash` is specified for one file, it has to be specified for all, otherwise this function will fail. Note that the buffer `root_hash` points to must out-live the file_storage object, it will not be copied. This parameter is only used when loading torrents, that already have their file hashes computed. When creating torrents, the file hashes will be computed by the piece hashes.

If more files than one are added, certain restrictions to their paths apply. In a multi-file file storage (torrent), all files must share the same root directory.

That is, the first path element of all files must be the same. This shared path element is also set to the name of the torrent. It can be changed by calling `set_name`.

The overloads that take an error_code reference will report failures via that variable, otherwise system_error is thrown.

[report issue]

## rename_file()

    void rename_file (file_index_t index, std::string const& new_filename);

renames the file at `index` to `new_filename`. Keep in mind that filenames are expected to be UTF-8 encoded.

[report issue]

## map_block()

    std::vector<file_slice> map_block (piece_index_t piece, std::int64_t offset
          , std::int64_t size) const;

returns a list of file_slice objects representing the portions of files the specified piece index, byte offset and size range overlaps. this is the inverse mapping of map_file().

Preconditions of this function is that the input range is within the torrents address space. `piece` may not be negative and

> `piece` * piece_size + `offset` + `size`

may not exceed the total size of the torrent.

[report issue]

## map_file()

    peer_request map_file (file_index_t file, std::int64_t offset, int size) const;

returns a peer_request representing the piece index, byte offset and size the specified file range overlaps. This is the inverse mapping over map_block(). Note that the `peer_request` return type is meant to hold bittorrent block requests, which may not be larger than 16 kiB. Mapping a range larger than that may return an overflown integer.

[report issue]

## num_files()

    int num_files () const noexcept;

returns the number of files in the file_storage

[report issue]

## end_file()

    file_index_t end_file () const noexcept;

returns the index of the one-past-end file in the file storage

[report issue]

## file_range()

    index_range<file_index_t> file_range () const noexcept;

returns an implementation-defined type that can be used as the container in a range-for loop. Where the values are the indices of all files in the file_storage.

[report issue]

## total_size()

    std::int64_t total_size () const;

returns the total number of bytes all the files in this torrent spans

[report issue]

## num_pieces() set_num_pieces()

    void set_num_pieces (int n);
    int num_pieces () const;

set and get the number of pieces in the torrent

[report issue]

## end_piece()

    piece_index_t end_piece () const;

returns the index of the one-past-end piece in the file storage

[report issue]

## last_piece()

    piece_index_t last_piece () const;

returns the index of the last piece in the torrent. The last piece is special in that it may be smaller than the other pieces (and the other pieces are all the same size).

[report issue]

## piece_range()

    index_range<piece_index_t> piece_range () const noexcept;

returns an implementation-defined type that can be used as the container in a range-for loop. Where the values are the indices of all pieces in the file_storage.

[report issue]

## piece_length() set_piece_length()

    void set_piece_length (int l);
    int piece_length () const;

set and get the size of each piece in this torrent. It must be a power of two and at least 16 kiB.

[report issue]

## piece_size()

    int piece_size (piece_index_t index) const;

returns the piece size of `index`. This will be the same as piece_length(), except for the last piece, which may be shorter.

[report issue]

## piece_size2()

    int piece_size2 (piece_index_t index) const;

Returns the size of the given piece. If the piece spans multiple files, only the first file is considered part of the piece. This is used for v2 torrents, where all files are piece aligned and padded. i.e. The pad files are not considered part of the piece for this purpose.

[report issue]

## blocks_in_piece2()

    int blocks_in_piece2 (piece_index_t index) const;

returns the number of blocks in the specified piece, for v2 torrents.

[report issue]

## set_name() name()

    std::string const& name () const;
    void set_name (std::string const& n);

set and get the name of this torrent. For multi-file torrents, this is also the name of the root directory all the files are stored in.

[report issue]

## swap()

    void swap (file_storage& ti) noexcept;

swap all content of this with ti.

[report issue]

## canonicalize()

    void canonicalize ();

arrange files and padding to match the canonical form required by BEP 52

[report issue]

## file_size() file_name() root_ptr() hash() file_path() root() pad_file_at() mtime() symlink() file_offset()

    sha1_hash hash (file_index_t index) const;
    std::int64_t file_size (file_index_t index) const;
    char const* root_ptr (file_index_t const index) const;
    std::time_t mtime (file_index_t index) const;
    std::string symlink (file_index_t index) const;
    sha256_hash root (file_index_t index) const;
    bool pad_file_at (file_index_t index) const;
    std::string file_path (file_index_t index, std::string const& save_path = "") const;
    std::int64_t file_offset (file_index_t index) const;
    string_view file_name (file_index_t index) const;

These functions are used to query attributes of files at a given index.

The `hash()` is a SHA-1 hash of the file, or 0 if none was provided in the torrent file. This can potentially be used to join a bittorrent network with other file sharing networks.

`root()` returns the SHA-256 merkle tree root of the specified file, in case this is a v2 torrent. Otherwise returns zeros. `root_ptr()` returns a pointer to the SHA-256 merkle tree root hash for the specified file. The pointer points into storage referred to when the file was added, it is not owned by this object. Torrents that are not v2 torrents return nullptr.

The `mtime()` is the modification time is the posix time when a file was last modified when the torrent was created, or 0 if it was not included in the torrent file.

`file_path()` returns the full path to a file.

`file_size()` returns the size of a file.

`pad_file_at()` returns true if the file at the given index is a pad-file.

`file_name()` returns just the name of the file, whereas `file_path()` returns the path (inside the torrent file) with the filename appended.

`file_offset()` returns the byte offset within the torrent file where this file starts. It can be used to map the file to a piece index (given the piece size).

[report issue]

## file_num_blocks() file_num_pieces() file_piece_range()

    index_range<piece_index_t::diff_type> file_piece_range (file_index_t) const;
    int file_num_blocks (file_index_t index) const;
    int file_num_pieces (file_index_t index) const;

Returns the number of pieces or blocks the file at index spans, under the assumption that the file is aligned to the start of a piece. This is only meaningful for v2 torrents, where files are guaranteed such alignment. These numbers are used to size and navigate the merkle hash tree for each file.

[report issue]

## file_first_piece_node() file_first_block_node()

    int file_first_piece_node (file_index_t index) const;
    int file_first_block_node (file_index_t index) const;

index of first piece node in the merkle tree

[report issue]

## file_path_hash()

    std::uint32_t file_path_hash (file_index_t index, std::string const& save_path) const;

returns the crc32 hash of file_path(index)

[report issue]

## all_path_hashes()

    void all_path_hashes (std::unordered_set<std::uint32_t>& table) const;

this will add the CRC32 hash of all directory entries to the table. No filename will be included, just directories. Every depth of directories are added separately to allow test for collisions with files at all levels. i.e. if one path in the torrent is `foo/bar/baz`, the CRC32 hashes for `foo`, `foo/bar` and `foo/bar/baz` will be added to the set.

[report issue]

## file_flags()

    file_flags_t file_flags (file_index_t index) const;

returns a bitmask of flags from file_flags_t that apply to file at `index`.

[report issue]

## file_absolute_path()

    bool file_absolute_path (file_index_t index) const;

returns true if the file at the specified index has been renamed to have an absolute path, i.e. is not anchored in the save path of the torrent.

[report issue]

## file_index_at_offset() file_index_at_piece()

    file_index_t file_index_at_offset (std::int64_t offset) const;
    file_index_t file_index_at_piece (piece_index_t piece) const;

returns the index of the file at the given offset in the torrent

[report issue]

## file_index_for_root()

    file_index_t file_index_for_root (sha256_hash const& root_hash) const;

finds the file with the given root hash and returns its index if there is no file with the root hash, file_index_t{-1} is returned

[report issue]

## piece_index_at_file()

    piece_index_t piece_index_at_file (file_index_t f) const;

returns the piece index the given file starts at

[report issue]

## sanitize_symlinks()

    void sanitize_symlinks ();

validate any symlinks, to ensure they all point to other files or directories inside this storage. Any invalid symlinks are updated to point to themselves.

[report issue]

## v2()

    bool v2 () const;

returns true if this torrent contains v2 metadata.

[report issue]

flag_pad_file
  the file is a pad file. It's required to contain zeros at it will not be saved to disk. Its purpose is to make the following file start on a piece boundary.

[report issue]

flag_hidden
  this file has the hidden attribute set. This is primarily a windows attribute

[report issue]

flag_executable
  this file has the executable attribute set.

[report issue]

flag_symlink
  this file is a symbolic link. It should have a link target string associated with it.

[report issue]

# default_disk_io_constructor()

Declared in "libtorrent/session.hpp"

    std::unique_ptr<disk_interface> default_disk_io_constructor (
       io_context& ios, settings_interface const&, counters& cnt);

the constructor function for the default storage. On systems that support memory mapped files (and a 64 bit address space) the memory mapped storage will be constructed, otherwise the portable posix storage.

[report issue]

# posix_disk_io_constructor()

Declared in "libtorrent/posix_disk_io.hpp"

    std::unique_ptr<disk_interface> posix_disk_io_constructor (
       io_context& ios, settings_interface const&, counters& cnt);

this is a simple posix disk I/O back-end, used for systems that don't have a 64 bit virtual address space or don't support memory mapped files. It's implemented using portable C file functions and is single-threaded.

[report issue]

# mmap_disk_io_constructor()

Declared in "libtorrent/mmap_disk_io.hpp"

    std::unique_ptr<disk_interface> mmap_disk_io_constructor (
       io_context& ios, settings_interface const&, counters& cnt);

constructs a memory mapped file disk I/O object.

[report issue]

# disabled_disk_io_constructor()

Declared in "libtorrent/disabled_disk_io.hpp"

    std::unique_ptr<disk_interface> disabled_disk_io_constructor (
       io_context& ios, settings_interface const&, counters& cnt);

creates a disk io object that discards all data written to it, and only returns zero-buffers when read from. May be useful for testing and benchmarking.

[report issue]

# enum storage_mode_t

Declared in "libtorrent/storage_defs.hpp"

name | value | description
--- | --- | ---
storage_mode_allocate | 0 | All pieces will be written to their final position, all files will be allocated in full when the torrent is first started. This mode minimizes fragmentation but could be a costly operation.
storage_mode_sparse | 1 | All pieces will be written to the place where they belong and sparse files will be used. This is the recommended, and default mode.

[report issue]

# enum status_t

Declared in "libtorrent/storage_defs.hpp"

name | value | description
--- | --- | ---
no_error | 0 |
fatal_disk_error | 1 |
need_full_check | 2 |
file_exist | 3 |
oversized_file | 16 | this is not an enum value, but a flag that can be set in the return from async_check_files, in case an existing file was found larger than specified in the torrent. i.e. it has garbage at the end the status_t field is used for this to preserve ABI.

[report issue]

# enum move_flags_t

Declared in "libtorrent/storage_defs.hpp"

name | value | description
--- | --- | ---
always_replace_files | 0 | replace any files in the destination when copying or moving the storage
fail_if_exist | 1 | if any files that we want to copy exist in the destination exist, fail the whole operation and don't perform any copy or move. There is an inherent race condition in this mode. The files are checked for existence before the operation starts. In between the check and performing the copy, the destination files may be created, in which case they are replaced.
dont_replace | 2 | if any file exist in the target, take those files instead of the ones we may have in the source.