.. include:: header.rst

`home`__

__ reference.html

.. contents:: Table of contents
  :depth: 2
  :backlinks: none

.. raw:: html

	<a name="storage_params"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+storage_params&labels=documentation&body=Documentation+under+heading+%22class+storage_params%22+could+be+improved">report issue</a>]</span>



storage_params
--------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/libtorrent/storage_defs.hpp

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


__ reference-Custom_Storage.html#disk_interface


.. parsed-literal::
	

	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;
	};

.. raw:: html

	<a name="file_slice"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_slice&labels=documentation&body=Documentation+under+heading+%22class+file_slice%22+could+be+improved">report issue</a>]</span>



file_slice
----------

Declared in "`libtorrent/file_storage.hpp`__"


__ include/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.


__ reference-Torrent_Info.html#torrent_info


.. parsed-literal::
	

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

.. raw:: html

	<a name="file_index"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_slice%3A%3A%5Bfile_index%5D&labels=documentation&body=Documentation+under+heading+%22file_slice%3A%3A%5Bfile_index%5D%22+could+be+improved">report issue</a>]</span>


file_index
	the index of the file
	


.. raw:: html

	<a name="offset"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_slice%3A%3A%5Boffset%5D&labels=documentation&body=Documentation+under+heading+%22file_slice%3A%3A%5Boffset%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="size"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_slice%3A%3A%5Bsize%5D&labels=documentation&body=Documentation+under+heading+%22file_slice%3A%3A%5Bsize%5D%22+could+be+improved">report issue</a>]</span>


size
	the size of the window, in bytes
	


.. raw:: html

	<a name="file_storage"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+file_storage&labels=documentation&body=Documentation+under+heading+%22class+file_storage%22+could+be+improved">report issue</a>]</span>



file_storage
------------

Declared in "`libtorrent/file_storage.hpp`__"


__ include/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.




.. parsed-literal::
	

	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;
	};

.. raw:: html

	<a name="is_valid()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bis_valid%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bis_valid%28%29%5D%22+could+be+improved">report issue</a>]</span>



is_valid()
..........

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_storage
__ reference-Storage.html#file_storage

.. raw:: html

	<a name="reserve()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Breserve%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Breserve%28%29%5D%22+could+be+improved">report issue</a>]</span>



reserve()
.........

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="add_file()"></a>
	<a name="add_file_borrow()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Badd_file%28%29+add_file_borrow%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Badd_file%28%29+add_file_borrow%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_file() add_file_borrow()
............................

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_storage
__ reference-Storage.html#flag_symlink
__ reference-Storage.html#file_storage

.. raw:: html

	<a name="rename_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Brename_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Brename_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



rename_file()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="map_block()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bmap_block%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bmap_block%28%29%5D%22+could+be+improved">report issue</a>]</span>



map_block()
...........

.. parsed-literal::
	
	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.


__ reference-Storage.html#file_slice
__ reference-Torrent_Info.html#map_file()

.. raw:: html

	<a name="map_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bmap_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bmap_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



map_file()
..........

.. parsed-literal::
	
	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.


__ reference-Core.html#peer_request
__ reference-Torrent_Info.html#map_block()

.. raw:: html

	<a name="num_files()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bnum_files%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bnum_files%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_files()
...........

.. parsed-literal::
	
	int **num_files** () const noexcept;
	

returns the number of files in the `file_storage`__


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="end_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bend_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bend_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



end_file()
..........

.. parsed-literal::
	
	file_index_t **end_file** () const noexcept;
	

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



.. raw:: html

	<a name="file_range()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_range%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_range%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_range()
............

.. parsed-literal::
	
	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`__.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="total_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Btotal_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Btotal_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



total_size()
............

.. parsed-literal::
	
	std::int64_t **total_size** () const;
	

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



.. raw:: html

	<a name="num_pieces()"></a>
	<a name="set_num_pieces()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bnum_pieces%28%29+set_num_pieces%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bnum_pieces%28%29+set_num_pieces%28%29%5D%22+could+be+improved">report issue</a>]</span>



num_pieces() set_num_pieces()
.............................

.. parsed-literal::
	
	void **set_num_pieces** (int n);
	int **num_pieces** () const;
	

set and get the number of pieces in the torrent



.. raw:: html

	<a name="end_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bend_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bend_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



end_piece()
...........

.. parsed-literal::
	
	piece_index_t **end_piece** () const;
	

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



.. raw:: html

	<a name="last_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Blast_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Blast_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



last_piece()
............

.. parsed-literal::
	
	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).



.. raw:: html

	<a name="piece_range()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_range%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_range%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_range()
.............

.. parsed-literal::
	
	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`__.


__ reference-Storage.html#file_storage

.. raw:: html

	<a name="piece_length()"></a>
	<a name="set_piece_length()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_length%28%29+set_piece_length%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_length%28%29+set_piece_length%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_length() set_piece_length()
.................................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="piece_size()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_size%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_size%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_size()
............

.. parsed-literal::
	
	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.


__ reference-Torrent_Info.html#piece_length()

.. raw:: html

	<a name="piece_size2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_size2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_size2%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_size2()
.............

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="blocks_in_piece2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bblocks_in_piece2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bblocks_in_piece2%28%29%5D%22+could+be+improved">report issue</a>]</span>



blocks_in_piece2()
..................

.. parsed-literal::
	
	int **blocks_in_piece2** (piece\_index\_t index) const;
	

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



.. raw:: html

	<a name="set_name()"></a>
	<a name="name()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bset_name%28%29+name%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bset_name%28%29+name%28%29%5D%22+could+be+improved">report issue</a>]</span>



set_name() name()
.................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="swap()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bswap%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bswap%28%29%5D%22+could+be+improved">report issue</a>]</span>



swap()
......

.. parsed-literal::
	
	void **swap** (file\_storage& ti) noexcept;
	

swap all content of *this* with *ti*.



.. raw:: html

	<a name="canonicalize()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bcanonicalize%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bcanonicalize%28%29%5D%22+could+be+improved">report issue</a>]</span>



canonicalize()
..............

.. parsed-literal::
	
	void **canonicalize** ();
	

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



.. raw:: html

	<a name="file_size()"></a>
	<a name="file_name()"></a>
	<a name="root_ptr()"></a>
	<a name="hash()"></a>
	<a name="file_path()"></a>
	<a name="root()"></a>
	<a name="pad_file_at()"></a>
	<a name="mtime()"></a>
	<a name="symlink()"></a>
	<a name="file_offset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_size%28%29+file_name%28%29+root_ptr%28%29+hash%28%29+file_path%28%29+root%28%29+pad_file_at%28%29+mtime%28%29+symlink%28%29+file_offset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_size%28%29+file_name%28%29+root_ptr%28%29+hash%28%29+file_path%28%29+root%28%29+pad_file_at%28%29+mtime%28%29+symlink%28%29+file_offset%28%29%5D%22+could+be+improved">report issue</a>]</span>



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

.. parsed-literal::
	
	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).



.. raw:: html

	<a name="file_num_blocks()"></a>
	<a name="file_num_pieces()"></a>
	<a name="file_piece_range()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_num_blocks%28%29+file_num_pieces%28%29+file_piece_range%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_num_blocks%28%29+file_num_pieces%28%29+file_piece_range%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_num_blocks() file_num_pieces() file_piece_range()
......................................................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="file_first_piece_node()"></a>
	<a name="file_first_block_node()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_first_piece_node%28%29+file_first_block_node%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_first_piece_node%28%29+file_first_block_node%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_first_piece_node() file_first_block_node()
...............................................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="file_path_hash()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_path_hash%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_path_hash%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_path_hash()
................

.. parsed-literal::
	
	std::uint32_t **file_path_hash** (file\_index\_t index, std\:\:string const& save\_path) const;
	

returns the crc32 hash of file_path(index)



.. raw:: html

	<a name="all_path_hashes()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Ball_path_hashes%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Ball_path_hashes%28%29%5D%22+could+be+improved">report issue</a>]</span>



all_path_hashes()
.................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="file_flags()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_flags%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_flags%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_flags()
............

.. parsed-literal::
	
	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``.



.. raw:: html

	<a name="file_absolute_path()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_absolute_path%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_absolute_path%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_absolute_path()
....................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="file_index_at_offset()"></a>
	<a name="file_index_at_piece()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_index_at_offset%28%29+file_index_at_piece%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_index_at_offset%28%29+file_index_at_piece%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_index_at_offset() file_index_at_piece()
............................................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="file_index_for_root()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bfile_index_for_root%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bfile_index_for_root%28%29%5D%22+could+be+improved">report issue</a>]</span>



file_index_for_root()
.....................

.. parsed-literal::
	
	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



.. raw:: html

	<a name="piece_index_at_file()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bpiece_index_at_file%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bpiece_index_at_file%28%29%5D%22+could+be+improved">report issue</a>]</span>



piece_index_at_file()
.....................

.. parsed-literal::
	
	piece_index_t **piece_index_at_file** (file\_index\_t f) const;
	

returns the piece index the given file starts at



.. raw:: html

	<a name="sanitize_symlinks()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bsanitize_symlinks%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bsanitize_symlinks%28%29%5D%22+could+be+improved">report issue</a>]</span>



sanitize_symlinks()
...................

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="v2()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bv2%28%29%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bv2%28%29%5D%22+could+be+improved">report issue</a>]</span>



v2()
....

.. parsed-literal::
	
	bool **v2** () const;
	

returns true if this torrent contains v2 metadata.



.. raw:: html

	<a name="flag_pad_file"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_pad_file%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_pad_file%5D%22+could+be+improved">report issue</a>]</span>


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.
	


.. raw:: html

	<a name="flag_hidden"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_hidden%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_hidden%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="flag_executable"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_executable%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_executable%5D%22+could+be+improved">report issue</a>]</span>


flag_executable
	this file has the executable attribute set.
	


.. raw:: html

	<a name="flag_symlink"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:file_storage%3A%3A%5Bflag_symlink%5D&labels=documentation&body=Documentation+under+heading+%22file_storage%3A%3A%5Bflag_symlink%5D%22+could+be+improved">report issue</a>]</span>


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


.. raw:: html

	<a name="default_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:default_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22default_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



default_disk_io_constructor()
-----------------------------

Declared in "`libtorrent/session.hpp`__"


__ include/libtorrent/session.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="posix_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:posix_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22posix_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



posix_disk_io_constructor()
---------------------------

Declared in "`libtorrent/posix_disk_io.hpp`__"


__ include/libtorrent/posix_disk_io.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="mmap_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:mmap_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22mmap_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



mmap_disk_io_constructor()
--------------------------

Declared in "`libtorrent/mmap_disk_io.hpp`__"


__ include/libtorrent/mmap_disk_io.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="disabled_disk_io_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:disabled_disk_io_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22disabled_disk_io_constructor%28%29%22+could+be+improved">report issue</a>]</span>



disabled_disk_io_constructor()
------------------------------

Declared in "`libtorrent/disabled_disk_io.hpp`__"


__ include/libtorrent/disabled_disk_io.hpp

.. parsed-literal::
	
	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.



.. raw:: html

	<a name="storage_mode_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+storage_mode_t&labels=documentation&body=Documentation+under+heading+%22enum+storage_mode_t%22+could+be+improved">report issue</a>]</span>



enum storage_mode_t
-------------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/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.                   |
|                       |       |                                                                            |
+-----------------------+-------+----------------------------------------------------------------------------+



.. raw:: html

	<a name="status_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+status_t&labels=documentation&body=Documentation+under+heading+%22enum+status_t%22+could+be+improved">report issue</a>]</span>



enum status_t
-------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/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.               |
|                  |       |                                                                        |
+------------------+-------+------------------------------------------------------------------------+


__ reference-Storage.html#status_t

.. raw:: html

	<a name="move_flags_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+move_flags_t&labels=documentation&body=Documentation+under+heading+%22enum+move_flags_t%22+could+be+improved">report issue</a>]</span>



enum move_flags_t
-----------------

Declared in "`libtorrent/storage_defs.hpp`__"


__ include/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.                     |
|                      |       |                                                            |
+----------------------+-------+------------------------------------------------------------+





.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 52`: https://www.bittorrent.org/beps/bep_0052.html
.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
