premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

fix typos and run hunspell on more documentation

This commit is contained in:
arvidn 2018-10-19 19:56:07 +02:00 committed by Arvid Norberg
parent c57b3be4cc
commit 6eb05e4842
21 changed files with 370 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/building.rst
View File

@ -11,14 +11,14 @@ libtorrent manual
downloading and building
========================
To download the latest version of libtorrent, clone the `github repo`__.
To download the latest version of libtorrent, clone the `github repository`__.
__ https://github.com/arvidn/libtorrent
The build systems supported "out of the box" in libtorrent are boost-build v2
(BBv2) and autotools (for unix-like systems). If you still can't build after
following these instructions, you can usually get help in the ``#libtorrent``
IRC channel on ``irc.freenode.net``.
(BBv2) and cmake. If you still can't build after following these instructions,
you can usually get help in the ``#libtorrent`` IRC channel on
``irc.freenode.net``.
.. warning::
@ -39,7 +39,7 @@ IRC channel on ``irc.freenode.net``.
building from git
-----------------
To build libtorrent from git you need to clone the libtorrent repo from
To build libtorrent from git you need to clone the libtorrent repository from
github. If you downloaded a release `tarball`__, you can skip this section.
__ https://github.com/arvidn/libtorrent/releases/latest
@ -79,10 +79,8 @@ You'll find boost here__.
__ https://www.boost.org/users/download/#live
Extract the archive to some directory where you want it. For the sake of this
guide, let's assume you extract the package to ``c:\boost_1_68_0`` (I'm using
a windows path in this example since if you're on linux/unix you're more likely
to use the autotools). You'll need at least version 1.49 of the boost library
in order to build libtorrent.
guide, let's assume you extract the package to ``c:\boost_1_68_0``. You'll
need at least version 1.56 of the boost library in order to build libtorrent.
Step 2: Setup BBv2
@ -93,11 +91,11 @@ step. If not, you need to build boost build from the boost source package.
First you need to build ``b2``. You do this by opening a terminal (In windows,
run ``cmd``). Change directory to ``c:\boost_1_68_0\tools\build``. Then run the
script called ``bootstrap.bat`` or ``bootstrap.sh`` on a unix system. This will
build ``b2`` and place it in a directory ``src/engine/bin.<os-architecture>``.
Copy the ``b2.exe`` (or ``b2`` on a unix system) to a place that's in you
shell's ``PATH``. On linux systems a place commonly used may be
``/usr/local/bin`` or on windows ``c:\windows`` (you can also add directories to
script called ``bootstrap.bat`` or ``bootstrap.sh`` on a Unix system. This will
build ``b2`` and place it in a directory ``src/engine/bin.<architecture>``.
Copy the ``b2.exe`` (or ``b2`` on a Unix system) to a place that's in you
shell's ``PATH``. On Linux systems a place commonly used may be
``/usr/local/bin`` or on Windows ``c:\windows`` (you can also add directories to
the search paths by modifying the environment variable called ``PATH``).
Now you have ``b2`` installed. ``b2`` can be considered an interpreter
@ -129,13 +127,13 @@ If you use GCC, add the line::
using gcc ;
If you have more than one version of GCC installed, you can add the
commandline used to invoke g++ after the version number, like this::
command line used to invoke g++ after the version number, like this::
using gcc : 6.0 : g++-6 ;
using gcc : 7.0 : g++-7 ;
Another toolset worth mentioning is the ``darwin`` toolset (For MacOS X).
From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
Another toolset worth mentioning is the ``darwin`` toolset (for macOS).
From Tiger (10.4) macOS comes with both GCC 3.3 and GCC 4.0. Then you can
use the following toolsets::
using darwin : 3.3 : g++-3.3 ;
@ -157,7 +155,7 @@ variable is set pointing to one. If you're building boost from source, set
``BOOST_ROOT`` to your boost directory, e.g. ``c:\boost_1_68_0``.
Then the only thing left is simply to invoke ``b2``. If you want to specify
a specific toolset to use (compiler) you can just add that to the commandline.
a specific toolset to use (compiler) you can just add that to the command line.
For example::
b2 msvc-14.0
@ -166,7 +164,7 @@ For example::
.. note::
If the environment variable ``BOOST_ROOT`` is not set, the jamfile will
If the environment variable ``BOOST_ROOT`` is not set, the Jamfile will
attempt to link against "installed" boost libraries. i.e. assume the headers
and libraries are available in default search paths.
In this case it's critical that you build your project with the same version
@ -176,11 +174,11 @@ To build different versions you can also just add the name of the build
variant. Some default build variants in BBv2 are ``release``, ``debug``,
``profile``.
You can build libtorrent as a dll too, by typing ``link=shared``, or
You can build libtorrent as a DLL too, by typing ``link=shared``, or
``link=static`` to build a static library.
If you want to explicitly say how to link against the runtime library, you
can set the ``runtime-link`` feature on the commandline, either to ``shared``
can set the ``runtime-link`` feature on the command line, either to ``shared``
or ``static``. Most operating systems will only allow linking shared against
the runtime, but on windows you can do both. Example::
@ -201,7 +199,7 @@ the runtime, but on windows you can do both. Example::
.. note::
Some linux systems requires linking against ``librt`` in order to access
Some Linux systems requires linking against ``librt`` in order to access
the POSIX clock functions. If you get an error complaining about a missing
symbol ``clock_gettime``, you have to give ``need-librt=yes`` on the
b2 command line. This will make libtorrent link against ``librt``.
@ -222,7 +220,7 @@ Note that if you're building on windows using the ``msvc`` toolset, you cannot r
from a cygwin terminal, you'll have to run it from a ``cmd`` terminal. The same goes for
cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal.
Also, make sure the paths are correct in the different environments. In cygwin, the paths
(``BOOST_BUILD_PATH`` and ``BOOST_ROOT``) should be in the typical unix-format (e.g.
(``BOOST_BUILD_PATH`` and ``BOOST_ROOT``) should be in the typical Unix-format (e.g.
``/cygdrive/c/boost_1_68_0``). In the windows environment, they should have the typical
windows format (``c:/boost_1_68_0``).
@ -237,7 +235,7 @@ For more build configuration flags see `Build configurations`_.
When enabling linking against openssl (by setting the ``crypto`` feature to
``openssl``) the Jamfile will look in some default directory for the openssl
headers and libraries. On macOS, it will look for the homebrew openssl package.
On windows it will look in ``c:\openssl`` and mingw in ``c:\OpenSSL-Win32``.
On windows it will look in ``c:\openssl`` and MinGW in ``c:\OpenSSL-Win32``.
To customize the library path and include path for openssl, set the features
``openssl-lib`` and ``openssl-include`` respectively.
@ -358,7 +356,7 @@ Build features:
| | functions are used. |
+--------------------------+----------------------------------------------------+
| ``iconv`` | * ``auto`` - use iconv for string conversions for |
| | linux and mingw and other posix platforms. |
| | Linux and MinGW and other posix platforms. |
| | * ``on`` - force use of iconv |
| | * ``off`` - force not using iconv (disables locale |
| | awareness except on windows). |
@ -397,15 +395,12 @@ Build features:
The ``variant`` feature is *implicit*, which means you don't need to specify
the name of the feature, just the value.
The logs created when building vlog or log mode are put in a directory called
``libtorrent_logs`` in the current working directory.
When building the example client on windows, you need to build with
``link=static`` otherwise you may get unresolved external symbols for some
boost.program-options symbols.
For more information, see the `Boost build v2 documentation`__, or more
specifically `the section on builtin features`__.
specifically `the section on built-in features`__.
__ https://boostorg.github.io/build/manual/develop/index.html
__ https://boostorg.github.io/build/manual/develop/index.html#bbv2.overview.builtins.features
@ -461,7 +456,7 @@ Other build options are:
| | against the runtime libraries. |
+-----------------------+---------------------------------------------------+
| ``build_tests`` | Defaults ``OFF``. Also build the libtorrent |
| | testa. |
| | tests. |
+-----------------------+---------------------------------------------------+
| ``build_examples`` | Defaults ``OFF``. Also build the examples in the |
| | examples directory. |
@ -557,7 +552,7 @@ defines you can use to control the build.
+----------------------------------------+-------------------------------------------------+
| ``TORRENT_DISABLE_EXTENSIONS`` | When defined, libtorrent plugin support is |
| | disabled along with support for the extension |
| | handskake (BEP 10). |
| | handshake (BEP 10). |
+----------------------------------------+-------------------------------------------------+
| ``TORRENT_USE_INVARIANT_CHECKS`` | If defined to non-zero, this will enable |
| | internal invariant checks in libtorrent. |
@ -570,7 +565,7 @@ defines you can use to control the build.
| | or for running before releases. |
+----------------------------------------+-------------------------------------------------+
| ``TORRENT_NO_DEPRECATE`` | This will exclude all deprecated functions from |
| | the header files and cpp files. |
| | the header files and source files. |
+----------------------------------------+-------------------------------------------------+
| ``TORRENT_PRODUCTION_ASSERTS`` | Define to either 0 or 1. Enables assert logging |
| | in release builds. |
@ -583,7 +578,7 @@ defines you can use to control the build.
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
If you experience that libtorrent uses unreasonable amounts of cpu, it will
If you experience that libtorrent uses unreasonable amounts of CPU, it will
definitely help to define ``NDEBUG``, since it will remove the invariant checks
within the library.

6
docs/client_test.rst
View File

@ -6,11 +6,11 @@ client_test example program
Client test is a, more or less, complete bittorrent client. It lacks most
settings and you can't start or stop torrents once you've started it. All
the settings are hardcoded. The commandline arguments are::
the settings are hard coded. The command line arguments are::
client_test <filename1.torrent> <filename2.torrent> ...
You can start any number of torrent downloads/seeds via the commandline.
You can start any number of torrent downloads/seeds via the command line.
If one argument starts with ``http://`` it is interpreted as a tracker
announce url, and it expects an info-hash as the next argument. The info-hash
has to be hex-encoded. For example: ``2410d4554d5ed856d69f426c38791673c59f4418``.
@ -34,7 +34,7 @@ The commands available in the client are:
* ``d`` toggle download info. Will show the block list for each torrent,
showing downloaded and requested blocks.
* ``p`` pause all torrents.
* ``u`` unpause all torrents.
* ``u`` resume all torrents.
* ``r`` force tracker reannounce for all torrents.
* ``f`` toggle show file progress. Displays a list of all files and the
download progress for each file.

2
docs/contributing.rst
View File

@ -39,7 +39,7 @@ enumerated on this page, please contact arvid@libtorrent.org or the `mailing lis
3. Code
Contributing code for new features or bug-fixes is highly welcome. If you're interested
in adding a feature but not sure where to start, please contact the `mailing list`_ or
``#libtorrent`` @ ``irc.freenode.net``. For proposed fixes or udpates, please
``#libtorrent`` @ ``irc.freenode.net``. For proposed fixes or updates, please
submit a `pull request`_.
New features might be better support for integrating with other services, new choking

4
docs/dht_extensions.rst
View File

@ -28,7 +28,7 @@ client identification
---------------------
In each DHT packet, an extra key is inserted named "v". This is a string
describing the client and version used. This can help alot when debugging
describing the client and version used. This can help a lot when debugging
and finding errors in client implementations. The string is encoded as four
characters, two characters describing the client and two characters interpreted
as a binary number describing the client version.
@ -48,7 +48,7 @@ Currently known clients:
IPv6 support
------------
**This extension is superseeded by** `BEP 32`_.
**This extension is superseded by** `BEP 32`_.
.. _`BEP 32`: https://bittorrent.org/beps/bep_0032.html

6
docs/dht_rss.rst
View File

@ -45,7 +45,7 @@ from them.
linked lists
------------
Items are chained together in a geneal singly linked list. A linked
Items are chained together in a general singly linked list. A linked
list does not necessarily contain RSS items, and no RSS related items
are mandatory. However, RSS items will be used as examples in this BEP::
@ -68,7 +68,7 @@ The ``next`` pointer is at least 20 byte ID in the DHT key space pointing to whe
item in the list is announced. The list is terminated with an ID of all zeros.
The ID an items is announced to is determined by the SHA1 hash of the bencoded representation
of the item iteself. This contains all fields in the item, except the signature.
of the item itself. This contains all fields in the item, except the signature.
The only mandatory fields in an item are ``next``, ``key`` and ``sig``.
The ``key`` field MUST match the public key of the list head node. The ``sig`` field
@ -82,7 +82,7 @@ chain of items considered terminated.
Each item holds a bencoded dictionary with arbitrary keys, except two mandatory keys:
``next`` and ``key``. The signature ``sig`` is transferred outside of this dictionary
and is the signature of all of it. An implementation should stora any arbitrary keys that
and is the signature of all of it. An implementation should store any arbitrary keys that
are announced to an item, within reasonable restriction such as nesting, size and numeric
range of integers.

14
docs/dht_sec.rst
View File

@ -38,7 +38,7 @@ whose hash will be *closest* to the target info-hash. Given the current
size of the DHT, that is quite likely to be possible by anyone in control
of a /8 IP block.
The size of the DHT is approximately 8.4 million nodes. This is estmiated
The size of the DHT is approximately 8.4 million nodes. This is estimated
by observing that a typical routing table typically has about 20 of its
top routing table buckets full. That means the key space is dense enough
to contain 8 nodes for every combination of the 20 top bits of node IDs.
@ -50,7 +50,7 @@ By controlling 8 times that many IP addresses, an attacker could actually
take over any info-hash.
With IPv4, snooping would require a /8 IP block, giving access to 16.7 million
Ips.
IPs.
Another problem with hashing the IP is that multiple users behind a NAT are
forced to run their DHT nodes on the same node ID.
@ -63,7 +63,7 @@ of IPs, as well as allowing more than one node ID per external IP, the node
ID can be restricted at each class level of the IP.
Another important property of the restriction put on node IDs is that the
distribution of the IDs remoain uniform. This is why CRC32C (Castagnoli) was
distribution of the IDs remain uniform. This is why CRC32C (Castagnoli) was
chosen as the hash function.
The expression to calculate a valid ID prefix (from an IPv4 address) is::
@ -79,7 +79,7 @@ representing the masked IP address is supposed to be big-endian before
hashed. The "|" operator means bit-wise OR.
The details of implementing this is to evaluate the expression, store the
result in a big endian 64 bit integer and hash those 8 bytes with CRC32C.
result in a big-endian 64 bit integer and hash those 8 bytes with CRC32C.
The first (most significant) 21 bits of the node ID used in the DHT MUST
match the first 21 bits of the resulting hash. The last byte of the hash MUST
@ -137,7 +137,7 @@ bootstrapping
In order to set ones initial node ID, the external IP needs to be known. This
is not a trivial problem. With this extension, *all* DHT responses SHOULD include
a *top-level* field called ``ip``, containing a compact binary representation of
the requestor's IP and port. That is big endian IP followed by 2 bytes of big endian
the requester's IP and port. That is big-endian IP followed by 2 bytes of big-endian
port.
The IP portion is the same byte sequence used to verify the node ID.
@ -181,7 +181,7 @@ to this property.
This test takes into account IP addresses that are not globally routable, i.e.
reserved for local networks, multicast and other things. It also takes into
account that some /8 blocks are not in use by end-users and exremely unlikely
account that some /8 blocks are not in use by end-users and extremely unlikely
to ever run a DHT node. This makes the results likely to be very similar to
what we would see in the wild.
@ -192,7 +192,7 @@ were to be used, there would be certain node IDs that would be impossible to
have, which would make routing sub-optimal.
The second test is more of a sanity test for the uniform distribution property.
The target space (32 bit interger) is divided up into 1000 buckets. Every valid
The target space (32 bit integer) is divided up into 1000 buckets. Every valid
IP and ``r`` input is run through the algorithm and the result is put in the
bucket it falls in. The expectation is that each bucket has roughly an equal
number of results falling into it. The following graph shows the resulting

2
docs/dht_store.rst
View File

@ -56,7 +56,7 @@ a public key, a sequence number, signature and an optional salt (``k``, ``seq``,
``sig`` and ``salt``).
``get`` requests for mutable items and immutable items cannot be distinguished
from eachother. An implementation can either store mutable and immutable items
from each other. An implementation can either store mutable and immutable items
in the same hash table internally, or in separate ones and potentially do two
lookups for ``get`` requests.

3
docs/examples.rst
View File

@ -13,8 +13,7 @@ examples
Except for the example programs in this manual, there's also a bigger example
of a (little bit) more complete client, ``client_test``. There are separate
instructions for how to use it here__ if you'd like to try it. Note that building
``client_test`` also requires boost.regex and boost.program_options library.
instructions for how to use it here__ if you'd like to try it.
__ client_test.html

16
docs/extension_protocol.rst
View File

@ -38,7 +38,7 @@ follows (including the message headers used by the bittorrent protocol):
| size | description |
+==========+=========================================================+
| uint32_t | length prefix. Specifies the number of bytes for the |
| | entire message. (Big endian) |
| | entire message. (big-endian) |
+----------+---------------------------------------------------------+
| uint8_t | bittorrent message ID, = 20 |
+----------+---------------------------------------------------------+
@ -155,7 +155,7 @@ any other extensions, this message should be sent:
``d11:LT_metadatai0ee``.
As specified above, the value 0 is used to turn off an extension.
The extension IDs must be stored for every peer, becuase every peer may have
The extension IDs must be stored for every peer, because every peer may have
different IDs for the same extension.
This specification, deliberately, does not specify any extensions such as
@ -247,17 +247,17 @@ request metadata:
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | Determines the kind of message this is |
| | | 0 means 'request metadata' |
| | | 0 means *request metadata* |
+-----------+---------------+----------------------------------------+
| uint8_t | start | The start of the metadata block that |
| | | is requested. It is given in 256:ths |
| | | is requested. It is given in 256ths |
| | | of the total size of the metadata, |
| | | since the requesting client don't know |
| | | the size of the metadata. |
+-----------+---------------+----------------------------------------+
| uint8_t | size | The size of the metadata block that is |
| | | requested. This is also given in |
| | | 256:ths of the total size of the |
| | | 256ths of the total size of the |
| | | metadata. The size is given as size-1. |
| | | That means that if this field is set |
| | | 0, the request wants one 256:th of the |
@ -269,7 +269,7 @@ metadata:
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | 1 means 'metadata' |
| uint8_t | msg_type | 1 means *metadata* |
+-----------+---------------+----------------------------------------+
| int32_t | total_size | The total size of the metadata, given |
| | | in number of bytes. |
@ -289,7 +289,7 @@ Don't have metadata:
+-----------+---------------+----------------------------------------+
| size | name | description |
+===========+===============+========================================+
| uint8_t | msg_type | 2 means 'I don't have metadata'. |
| uint8_t | msg_type | 2 means "I don't have metadata". |
| | | This message is sent as a reply to a |
| | | metadata request if the the client |
| | | doesn't have any metadata. |
@ -307,7 +307,7 @@ longer has a specific piece. The extension message should be advertised in the
``m`` dictionary as ``lt_donthave``. The message format mimics the regular
``HAVE`` bittorrent message.
Just like all extension messages, the first 2 bytes in the mssage itself are 20
Just like all extension messages, the first 2 bytes in the message itself are 20
(the bittorrent extension message) and the message ID assigned to this
extension in the ``m`` dictionary in the handshake.

26
docs/features.rst
View File

@ -33,13 +33,13 @@ extensions
* supports the bittorrent `extension protocol`_. See extensions_. `BEP 10`_.
* supports the uTorrent metadata transfer protocol `BEP 9`_ (i.e. magnet links).
* supports the uTorrent peer exchange protocol (PEX).
* supports local peer discovery (multicasts for peers on the same local network)
* multitracker extension support (supports both strict `BEP 12`_ and the
* supports local peer discovery (multicast for peers on the same local network)
* multi-tracker extension support (supports both strict `BEP 12`_ and the
uTorrent interpretation).
* tracker scrapes
* supports lt_trackers extension, to exchange trackers between peers
* `HTTP seeding`_, as specified in `BEP 17`_ and `BEP 19`_.
* supports the udp-tracker protocol. (`BEP 15`_).
* supports the UDP-tracker protocol. (`BEP 15`_).
* supports the ``no_peer_id=1`` extension that will ease the load off trackers.
* supports the ``compact=1`` tracker parameter.
* super seeding/initial seeding (`BEP 16`_).
@ -60,7 +60,7 @@ extensions
disk management
---------------
* can use multipled disk I/O threads to not have the disk block network or
* can use multiple disk I/O threads to not have the disk block network or
client interaction.
* supports verifying the SHA-1 hash of pieces in multiple threads, to take
advantage of multi core machines.
@ -89,7 +89,7 @@ network
It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer.
* supports http proxies and basic proxy authentication
* supports gzipped tracker-responses
* supports gzip tracker-responses
* can limit the upload and download bandwidth usage and the maximum number of
unchoked peers
* possibility to limit the number of connections.
@ -134,7 +134,7 @@ All disk I/O in libtorrent is done asynchronously to the network thread, by the
disk io threads. When a block is read, the disk io thread reads all subsequent
blocks from that piece into the read cache, assuming that the peer requesting
the block will also request more blocks from the same piece. This decreases the
number of syscalls for reading data. It also decreases delay from seeking.
number of system calls for reading data. It also decreases delay from seeking.
Similarly, for write requests, blocks are cached and flushed to disk once one full
piece is complete or the piece is the least recently updated one when more cache
@ -152,7 +152,7 @@ used to flush multiple cache blocks in a single call.
On low-memory systems, the disk cache can be disabled altogether or set to smaller
limit, to save memory.
The disk caching algorithm is configurable between 'LRU' and 'largest contiguous'.
The disk caching algorithm is configurable between *LRU* and *largest contiguous*.
The largest contiguous algorithm is the default and flushes the largest contiguous
block of buffers, instead of flushing all blocks belonging to the piece which was
written to least recently.
@ -168,7 +168,7 @@ for payload data is received directly into a page aligned disk buffer. If the co
is encrypted, the buffer is decrypted in-place. The buffer is then moved into the disk
cache without being copied. Once all the blocks for a piece have been received, or the
cache needs to be flushed, all the blocks are passed directly to ``writev()`` to flush
them in a single syscall. This means a single copy into user space memory, and a single
them in a single system call. This means a single copy into user space memory, and a single
copy back into kernel memory, as illustrated by this figure:
.. image:: write_disk_buffers.png
@ -242,11 +242,11 @@ Another problem with large piece sizes is that it is harder for a client to pinp
the malicious or buggy peer when a piece fails, and it will take longer to re-download
it and take more tries before the piece succeeds the larger the pieces are.
The piece size in regular torrents is a tradeoff between the size of the .torrent file
The piece size in regular torrents is a trade-off between the size of the .torrent file
itself and the piece size. Often, for files that are 4 GB, the piece size is 2 or 4 MB,
just to avoid making the .torrent file too big.
Merkle torrents solves these problems by removing the tradeoff between .torrent size and
Merkle torrents solves these problems by removing the trade-off between .torrent size and
piece size. With merkle torrents, the piece size can be the minimum block size (16 kB),
which lets peers verify every block of data received from peers, immediately. This
gives a minimum turnaround time and completely removes the problem of identifying malicious
@ -269,7 +269,7 @@ long as it can be retrieved and seeded. In that case a new storage class can be
(inheriting from the ``storage_interface`` class) that avoids the unnecessary step of mapping
slots to files and offsets. The storage can ignore the file boundaries and just store the
entire torrent in a single file (which will end up being all the files concatenated). The main
advantage of this, other than a slight cpu performance gain, is that all file operations would
advantage of this, other than a slight CPU performance gain, is that all file operations would
be page (and sector) aligned. This enables efficient unbuffered I/O, and can potentially
lead to more efficient read caching (using the built in disk cache rather than relying on the
operating system's disk cache).
@ -320,14 +320,14 @@ portability
===========
libtorrent runs on most major operating systems, including Windows,
MacOS X, Linux, BSD and Solaris.
macOS, Linux, BSD and Solaris.
It uses Boost.Asio, Boost.Optional, Boost.System, Boost.Multiprecision,
Boost.Intrusive, Boost.Pool, Boost.Python (for bindings), Boost.CRC and various
other boost libraries. At least version 1.49 of boost is required.
Since libtorrent uses Boost.Asio it will take full advantage of high performance
network APIs on the most popular platforms. I/O completion ports on windows,
epoll on linux and kqueue on MacOS X and BSD.
epoll on Linux and kqueue on macOS and BSD.
libtorrent does not build with the following compilers:

12
docs/hacking.rst
View File

@ -22,7 +22,7 @@ helps understanding what's going on.
A *piece* is a part of the data of a torrent that has a SHA-1 hash in
the .torrent file. Pieces are almost always a power of two in size, but not
necessarily. Each piece is plit up in *blocks*, which is a 16 kiB. A block
necessarily. Each piece is split up in *blocks*, which is a 16 kiB. A block
never spans two pieces. If a piece is smaller than 16 kiB or not divisible
by 16 kiB, there are blocks smaller than that.
@ -43,7 +43,7 @@ usage.
A *torrent* object represents all the state of swarm download. This includes
a piece picker, a list of peer connections, file storage (torrent file). One
important distiction is between a connected peer (*peer_connection*) and a peer
important distinction is between a connected peer (*peer_connection*) and a peer
we just know about, and may have been connected to, and may connect to in the
future (*torrent_peer*). The list of (not connected) peers may grow very large
if not limited (through tracker responses, DHT and peer exchange). This list
@ -128,10 +128,10 @@ disk cache
The disk cache implements *ARC*, Adaptive Replacement Cache. This consists of a number of LRUs:
1. lru L1 (recently used)
2. lru L1 ghost (recently evicted)
3. lru L2 (frequently used)
4. lru L2 ghost (recently evicted)
1. LRU L1 (recently used)
2. LRU L1 ghost (recently evicted)
3. LRU L2 (frequently used)
4. LRU L2 ghost (recently evicted)
5. volatile read blocks
6. write cache (blocks waiting to be flushed to disk)

244
docs/hunspell/libtorrent.dic
View File

@ -45,9 +45,11 @@ MiB
DHT
adler32
LRU
LRUs
UPnP
NAT
PMP
arvid
Arvid
Norberg
RTT
@ -59,6 +61,7 @@ plugins
symlink
symlinks
CRC32
CRC
UTF
bitfield
RSS
@ -67,6 +70,7 @@ socks4
metadata
posix
downloaders
downloader
bitset
kB
hostname
@ -217,3 +221,243 @@ lt
tex
natpmp
cancelled
bitcoin
Jamfile
Jamfiles
NDEBUG
Solaris
BitTorrent
BitTyrant
macOS
int8
int16
int32
int64
uint8
uint16
uint32
uint64
Castagnoli
CRC32C
multicast
Linux
kqueue
epoll
LEDBAT
DNS
Nagle's
ACK
ACKed
getaddrinfo
ethernet
gnuplot
peerlist
MTU
ICMP
VPN
DSL
CAS
cas
IRC
PPPoE
cwnd
fullscreen
screenshot
prepend
RSA
DSA
curve25519
nodes6
nodes4
serializer
github
Flattr
Wallin
Reimond
Retz
BEP5
librt
toolset
Wojciechowski
GTK
cmake
libsodium
nightcracker's
Siloti
Magnus
Jonsson
Umeå
freenode
irc
hydri
BBv2
DLL
gettime
toolsets
libgcrypt
CommonCrypto
cygwin
gcc
iOS
memalign
valloc
malloc
libcrypto
libssl
libeay32
ssleay32
libc
iconv
MinGW
config
xbt
tarball
cd
b2
utp
stlport
IETF
BitSlug
BitCo
Tampere
CXX
gui
Multiprecision
gcrypt
peers'
wchar
ccmake
fPIC
Unix
ipv4
ipv6
reqq
homebrew
endian
gzip
KTorrent
Azureus
btih
der
Spek
darwin
dllimport
dllexport
stdlib
Wyzo
bjam
messages'
sonarqube
utorrent
zlib
MooPolice
LeechCraft
FDM
Folx
Tonido
Dumez
qBittorrent
ntx86
Tonidoplug
nodes2
NAS
Tonido
localhost
yourip
declspec
gtkmm
btg
ncurses
Tvitty
Bubba
TVBlob
ISPs
ACKs
uplink's
Lince
hrktorrent
Trolltech
msg
donthave
png
DelCo
Torrent2Exe
ZyXEL
NSA
NSA220
tcp
rlimit
screensaver
GPL
routable
L1
L2
rst
org
DF
TVblob
FatRat
DAAP
fno
BLOBbox
GetRight
py
pyd
cmd
Strigeus
ludde
pic
programmatically
unchokes
ethernet's
BitTorrent's
IPTPS10
loopback
DLNA
EXE
Skype
lru
dll
exe
foobar
256ths
leechers
printability
podcasts
todo
0x10
0x41727101980
0x7fffffffffffffff
2410d4554d5ed856d69f426c38791673c59f4418
2e
373ZDeQgQSQNuxdinNAPnQ63CRNn4iEXzg
BT
ID's
aio
btfd
d1
d11
de
e1
impl
impl
impl
md11
metadatai0ee
metadatai1e6
passwd
pexi2ee1
pi6881e1
pimpl
pre1
recv
requester's
seqi
seqi1e1
txt
un
v12
v2

12
docs/index.rst
View File

@ -35,14 +35,14 @@ Extensions
* `DHT store extension`_
* `UDP tracker protocol`_
* `HTTP seed`_
* multitracker_
* multi-tracker_
--------
Bindings
* python_
* java_
* Java_
* go_
* node_
@ -80,7 +80,7 @@ libtorrent
.. _`DHT store extension`: dht_store.html
.. _`UDP tracker protocol`: udp_tracker_protocol.html
.. _`HTTP seed`: http://www.getright.com/seedtorrent.html
.. _multitracker: https://bittorrent.org/beps/bep_0012.html
.. _multi-tracker: https://bittorrent.org/beps/bep_0012.html
.. _mailing list: https://lists.sourceforge.net/lists/listinfo/libtorrent-discuss
.. _archive: https://sourceforge.net/p/libtorrent/mailman/libtorrent-discuss/
.. _`who's using libtorrent?`: projects.html
@ -88,7 +88,7 @@ libtorrent
.. _`github page`: https://github.com/arvidn/libtorrent
.. _blog: https://blog.libtorrent.org
.. _java: https://github.com/frostwire/frostwire-jlibtorrent/
.. _Java: https://github.com/frostwire/frostwire-jlibtorrent/
.. _python: python_binding.html
.. _go: https://github.com/steeve/libtorrent-go
.. _node: https://github.com/fanatid/node-libtorrent
@ -105,7 +105,7 @@ __ client_test.html
The main goals of libtorrent are:
* to be cpu efficient
* to be CPU efficient
* to be memory efficient
* to be very easy to use
@ -186,7 +186,7 @@ Written by Arvid Norberg. Copyright |copy| 2003-2018
Contributions by Steven Siloti, Alden Torres, Magnus Jonsson, Daniel Wallin and Cory Nelson
Thanks to Reimond Retz for bugfixes, suggestions and testing
Thanks to Reimond Retz for bug fixes, suggestions and testing
See github__ for full list of contributors.

11
docs/makefile
View File

@ -31,7 +31,7 @@ REFERENCE_TARGETS = \
reference-Bdecoding \
reference-ed25519
TARGETS = index \
MANUAL_TARGETS = index \
udp_tracker_protocol \
dht_rss \
dht_store \
@ -50,8 +50,10 @@ TARGETS = index \
tuning \
hacking \
streaming \
tutorial \
single-page-ref \
tutorial
TARGETS = single-page-ref \
$(MANUAL_TARGETS) \
$(REFERENCE_TARGETS)
FIGURES = \
@ -100,8 +102,9 @@ endif
$(REFERENCE_TARGETS:=.rst) plain_text_out.txt:gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp manual.rst settings.rst stats_counters.rst
python gen_reference_doc.py --plain-output
spell-check:plain_text_out.txt
spell-check:plain_text_out.txt $(MANUAL_TARGETS:=.html)
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -l plain_text_out.txt >hunspell-report.txt
hunspell -d hunspell/en_US -p hunspell/libtorrent.dic -H -l $(MANUAL_TARGETS:=.html) >>hunspell-report.txt
@if [ -s hunspell-report.txt ]; then echo 'spellcheck failed, fix words or add to dictionary:'; cat hunspell-report.txt; false; fi;
%.epub:%.rst

34
docs/projects.rst
View File

@ -10,9 +10,9 @@ project listed here, let me_ know.
Wyzo
----
wyzo_ is a media browser with built-in bittorrent support.
Wyzo_ is a media browser with built-in bittorrent support.
.. _wyzo: http://wyzo.findmysoft.com/#
.. _Wyzo: http://wyzo.findmysoft.com/#
deluge
------
@ -26,17 +26,17 @@ background to the system tray.
qBittorrent
-----------
qBittorrent_ is a QT bittorrent client available for linux (likely portable to
qBittorrent_ is a QT bittorrent client available for Linux (likely portable to
most other desktops as well). Written by Christophe Dumez.
.. _qBittorrent: http://www.qbittorrent.org/
tonidoplug
Tonidoplug
----------
Tonidoplug_ is a tiny, low-power, low-cost home server and
NAS device powered by Tonido software that allows you to access
your apps, files, music and media from anywhere.
your applications, files, music and media from anywhere.
.. _Tonidoplug: http://www.tonidoplug.com/
@ -56,7 +56,7 @@ Miro
----
Miro_ is a free application for channels of internet video (also known as
video podcasts and video rss). Miro is designed to be easy to use and to give
video podcasts and video RSS). Miro is designed to be easy to use and to give
you an elegant fullscreen viewing experience.
.. _Miro: http://getmiro.com
@ -90,9 +90,9 @@ GPL License.
btg
---
btg_ is a unix bittorrent client which is run as a daemon. It has multiple user
interfaces which connects to the daemon. One GUI (Gtkmm), one terminal
interface (ncurses) and one web interface (accessable through a web browser).
btg_ is a Unix bittorrent client which is run as a daemon. It has multiple user
interfaces which connects to the daemon. One GUI (gtkmm), one terminal
interface (ncurses) and one web interface (accessible through a web browser).
Written by Michael Wojciechowski and Johan Strom.
.. _btg: https://sourceforge.net/projects/btg/
@ -108,10 +108,10 @@ lets the users vote which one to live on.
Tvitty
------
tvitty_ is a bittorrent client for Vista Media Center, which allows
Tvitty_ is a bittorrent client for Vista Media Center, which allows
searching and downloading of torrents directly on your TV.
.. _tvitty: https://tvitty.soft112.com/
.. _Tvitty: https://tvitty.soft112.com/
hrktorrent
----------
@ -132,7 +132,7 @@ install.
halite BitTorrent
-----------------
Halite_ is a windows bittorrent client controllabel via an xml-rpc
Halite_ is a windows bittorrent client controllable via an XML-RPC
interface.
.. _Halite: http://www.binarynotions.com/halite-bittorrent-client
@ -146,7 +146,7 @@ Written by Cory Nelson.
.. _`Arctic Torrent`: https://www.softpedia.com/get/Internet/File-Sharing/Arctic-Torrent.shtml
bubba
Bubba
-----
Bubba_ is a mini-sized server, designed to fit your home better than
@ -155,7 +155,7 @@ Web, E-mail, printer and FTP server etc.
.. _Bubba: https://excitostore.com/
tvblob
TVblob
------
The BLOBbox_ represents the ability to harness all of the content available
@ -186,21 +186,21 @@ featured client.
BitSlug
-------
BitSlug_ is a MacOSX cocoa client.
BitSlug_ is a macOS cocoa client.
.. _BitSlug: http://bitslug.sourceforge.net/
DelCo
-----
DelCo_ is a research project at Tampere university of technology, finland.
DelCo_ is a research project at Tampere university of technology, Finland.
.. _DelCo: http://delco.cs.tut.fi/
Torrent2Exe
-----------
Torrent2Exe_ Torrent2exe is a small BitTorrent client. Its basic idea is to
Torrent2Exe_ is a small BitTorrent client. Its basic idea is to
let users download a custom-built EXE program with the torrent file
integrated into it.

6
docs/python_binding.rst
View File

@ -42,7 +42,7 @@ Move the file ``user-config.jam`` from ``%BOOST_BUILD_PATH%/example/`` to ``%BOO
Navigate to bindings/python and execute::
python setup.py build --bjam
Note: If you are using 64bits python you should edit setup.py and add this to the b2 command:
Note: If you are using 64 bits python you should edit setup.py and add this to the b2 command:
``address-model=64``
This will create the file libtorrent.pyd inside build/lib/ that contains the binding.
@ -70,7 +70,7 @@ For more information on how to install and set up boost-build, see the
.. __: building.html#step-2-setup-bbv2
Once you have boost-build set up, you cd to the ``bindings/python``
directory and invoke ``bjam`` with the apropriate settings. For the available
directory and invoke ``bjam`` with the appropriate settings. For the available
build variants, see `libtorrent build options`_.
.. _`libtorrent build options`: building.html#step-3-building-libtorrent
@ -91,7 +91,7 @@ the `library reference`_. The main differences are:
asio::tcp::endpoint
The endpoint type is represented as a tuple of a string (as the address) and an int for
the port number. E.g. ``('127.0.0.1', 6881)`` represents the localhost port 6881.
the port number. E.g. ``("127.0.0.1", 6881)`` represents the localhost port 6881.
lt::time_duration
The time duration is represented as a number of seconds in a regular integer.

2
docs/streaming.rst
View File

@ -79,7 +79,7 @@ swarm is well seeded, most peers will send data to you at close to the same
rate. This makes it important to support streaming from many slow peers. For
instance, this means you can't make assumptions about the download time of a
block being less than some absolute time. You may be downloading at well above
the bitrate of the video, but each individual peer only transfers at 5 kiB/s.
the bit rate of the video, but each individual peer only transfers at 5 kiB/s.
In this state, your download rate is a zero-sum-game. Any block you request
that is not urgent, will take away from the bandwidth you get for peers that

8
docs/tuning.rst
View File

@ -142,7 +142,7 @@ significant.
If you're short of memory, you should consider lowering the limit. 500 is probably
enough. You can do this by setting ``settings_pack::max_peerlist_size`` to
the max number of peers you want in a torrent's peer list. This limit applies per
torrent. For 5 torrents, the total number of peers in peerlists will be 5 times
torrent. For 5 torrents, the total number of peers in peer lists will be 5 times
the setting.
You should also lower the same limit but for paused torrents. It might even make sense
@ -197,7 +197,7 @@ One, probably, safe macro to define is ``TORRENT_NO_DEPRECATE`` which removes al
deprecated functions and struct members. As long as no deprecated functions are
relied upon, this should be a simple way to eliminate a little bit of code.
For all available options, see the `building libtorrent`_ secion.
For all available options, see the `building libtorrent`_ section.
.. _`building libtorrent`: building.html
@ -254,9 +254,9 @@ there is a mixed mode algorithm. This attempts to detect congestion on the uTP p
throttle TCP to avoid it taking over all bandwidth. This balances the bandwidth resources
between the two protocols. When running on a network where the bandwidth is in such an
abundance that it's virtually infinite, this algorithm is no longer necessary, and might
even be harmful to throughput. It is adviced to experiment with the
even be harmful to throughput. It is advised to experiment with the
``session_setting::mixed_mode_algorithm``, setting it to ``settings_pack::prefer_tcp``.
This setting entirely disables the balancing and unthrottles all connections. On a typical
This setting entirely disables the balancing and un-throttles all connections. On a typical
home connection, this would mean that none of the benefits of uTP would be preserved
(the modem's send buffer would be full at all times) and uTP connections would for the most
part be squashed by the TCP traffic.

2
docs/tutorial.rst
View File

@ -60,7 +60,7 @@ kind of alert may include additional state, specific to the kind of message. All
alerts implement a message() function that prints out pertinent information
of the alert message. This can be convenient for simply logging events.
For programatically react to certain events, use `alert_cast<>`_ to attempt
For programmatically react to certain events, use `alert_cast<>`_ to attempt
a down cast of an alert object to a more specific type.
In order to print out events from libtorrent as well as exiting when the torrent

16
docs/udp_tracker_protocol.rst
View File

@ -1,4 +1,4 @@
Bittorrent udp-tracker protocol extension
Bittorrent UDP-tracker protocol extension
=========================================
:Author: Arvid Norberg, arvid@libtorrent.org
@ -20,13 +20,13 @@ xbt-tracker_.
.. _xbt-tracker: http://xbtt.sourceforge.net
For additional information and descritptions of
For additional information and descriptions of
the terminology used in this document, see
the `protocol specification`__
__ http://wiki.theory.org/index.php/BitTorrentSpecification
All values are sent in network byte order (big endian). The sizes
All values are sent in network byte order (big-endian). The sizes
are specified with ANSI-C standard types.
If no response to a request is received within 15 seconds, resend
@ -112,7 +112,7 @@ Client sends packet:
+-------------+---------------------+----------------------------------------+
| uint32_t | ip | Your ip address. Set to 0 if you want |
| | | the tracker to use the ``sender`` of |
| | | this udp packet. |
| | | this UDP packet. |
+-------------+---------------------+----------------------------------------+
| uint32_t | key | A unique key that is randomized by the |
| | | client. |
@ -140,7 +140,7 @@ Server replies with packet:
| | | in the announce request. |
+-------------+---------------------+----------------------------------------+
| int32_t | interval | the number of seconds you should wait |
| | | until reannouncing yourself. |
| | | until re-announcing yourself. |
+-------------+---------------------+----------------------------------------+
| int32_t | leechers | The number of peers in the swarm that |
| | | has not finished downloading. |
@ -169,7 +169,7 @@ Client sends packet:
+-------------+---------------------+----------------------------------------+
| size | name | description |
+=============+=====================+========================================+
| int64_t | connection_id | The connection id retreived from the |
| int64_t | connection_id | The connection id retrieved from the |
| | | establishing of the connection. |
+-------------+---------------------+----------------------------------------+
| int32_t | action | The action, in this case, 2 for |
@ -302,13 +302,13 @@ in the tracker URL for each user. The extension body has the following format:
| | | string. |
+-------------+---------------------+----------------------------------------+
| int8_t[] | request string | The string that comes after the host- |
| | | name and port in the udp tracker URL. |
| | | name and port in the UDP tracker URL. |
| | | Typically this starts with "/announce" |
| | | The bittorrent client is not expected |
| | | to append query string arguments for |
| | | stats reporting, like "uploaded" and |
| | | "downloaded" since this is already |
| | | reported in the udp tracker protocol. |
| | | reported in the UDP tracker protocol. |
| | | However, the client is free to add |
| | | arguments as extensions. |
+-------------+---------------------+----------------------------------------+

12
docs/utp.rst
View File

@ -49,7 +49,7 @@ There are two major drawbacks with this technique:
1. The user needs to actively make this setting (very few protocols
require the user to provide this sort of information). This also
means the user needs to figure out what its up-link capacity is.
This is unfortunately a number that many ISPs are not advertizing
This is unfortunately a number that many ISPs are not advertising
(because it's often much lower than the download capacity) which
might make it hard to find.
@ -141,7 +141,7 @@ target, and less for delays that are close to the target. This makes it converge
at the target delay. Although, due to noise there is almost always some amount of
oscillation. This oscillation is typically smaller than the saw tooth TCP forms.
The figure to the right shows how (TCP) cross traffic causese uTP to essentially
The figure to the right shows how (TCP) cross traffic causes uTP to essentially
entirely stop sending anything. Its delay measurements are mostly well above the target
during this time. The cross traffic is only a single TCP stream in this test.
@ -196,7 +196,7 @@ A histogram of typical delay measurements is shown to the right. This is from
a transfer between a cable modem connection and a DSL connection.
The details of the delay measurements are slightly more complicated since the
values needs to be able to wrap (cross the 2^32 boundry and start over at 0).
values needs to be able to wrap (cross the 2^32 boundary and start over at 0).
Path MTU discovery
------------------
@ -270,7 +270,7 @@ we can do a binary search for the MTU. This would let us find it in just a few r
On top of this, libtorrent has an optimization where it figures out which interface a
uTP connection will be sent over, and initialize the MTU ceiling to that interface's MTU.
This means that a VPN tunnel would advertize its MTU as lower, and the uTP connection would
This means that a VPN tunnel would advertise its MTU as lower, and the uTP connection would
immediately know to send smaller packets, no search required. It also has the side-effect
of being able to use much larger packet sizes for non-ethernet interfaces or ethernet links
with jumbo frames.
@ -302,7 +302,7 @@ Clocks progresses at different rates depending on temperature. This means comput
running hot are likely to have a clock drift compared to computers running cool.
So, by updating the delay base periodically based on the lowest seen sample, you'll either
end up changing it upwards (artificaially making the delay samples appear small) without
end up changing it upwards (artificially making the delay samples appear small) without
the congestion or delay actually having changed, or you'll end up with a significant clock
drift and have artificially low samples because of that.
@ -341,6 +341,6 @@ libtorrent's uTP implementation includes the following features:
* Microsecond resolution timestamps.
* Advertised receive window, to support download rate limiting.
* Correct handling of wrapping sequence numbers.
* Easy configuration of target-delay, gain-factor, timeouts, delayed-ack
* Easy configuration of target-delay, gain-factor, timeouts, delayed-ACK
and socket buffers.