diff --git a/docs/building.rst b/docs/building.rst index 47fbafb13..3931b96b7 100644 --- a/docs/building.rst +++ b/docs/building.rst @@ -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.``. -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.``. +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. diff --git a/docs/client_test.rst b/docs/client_test.rst index a8757d956..b4753a031 100644 --- a/docs/client_test.rst +++ b/docs/client_test.rst @@ -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 ... -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. diff --git a/docs/contributing.rst b/docs/contributing.rst index 2fd59c433..d1bda72cc 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -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 diff --git a/docs/dht_extensions.rst b/docs/dht_extensions.rst index c5716658e..4880b7587 100644 --- a/docs/dht_extensions.rst +++ b/docs/dht_extensions.rst @@ -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 diff --git a/docs/dht_rss.rst b/docs/dht_rss.rst index 4ead96f29..6601c9cee 100644 --- a/docs/dht_rss.rst +++ b/docs/dht_rss.rst @@ -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. diff --git a/docs/dht_sec.rst b/docs/dht_sec.rst index 1443434cf..8b3728979 100644 --- a/docs/dht_sec.rst +++ b/docs/dht_sec.rst @@ -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 diff --git a/docs/dht_store.rst b/docs/dht_store.rst index 711cdab50..195c4ca38 100644 --- a/docs/dht_store.rst +++ b/docs/dht_store.rst @@ -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. diff --git a/docs/examples.rst b/docs/examples.rst index 6bba4d1d5..f8778d018 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -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 diff --git a/docs/extension_protocol.rst b/docs/extension_protocol.rst index 3f8c848e3..2f9785357 100644 --- a/docs/extension_protocol.rst +++ b/docs/extension_protocol.rst @@ -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. diff --git a/docs/features.rst b/docs/features.rst index fadcd8ce3..74c49ebe7 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -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: diff --git a/docs/hacking.rst b/docs/hacking.rst index c9072e843..975d322af 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -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) diff --git a/docs/hunspell/libtorrent.dic b/docs/hunspell/libtorrent.dic index 667901d0a..7412805a0 100644 --- a/docs/hunspell/libtorrent.dic +++ b/docs/hunspell/libtorrent.dic @@ -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 diff --git a/docs/index.rst b/docs/index.rst index 3b9aa41cf..2082cb823 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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. diff --git a/docs/makefile b/docs/makefile index 90a70dba1..ae1e36cd3 100644 --- a/docs/makefile +++ b/docs/makefile @@ -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 diff --git a/docs/projects.rst b/docs/projects.rst index 75da4e81f..1b9d6e505 100644 --- a/docs/projects.rst +++ b/docs/projects.rst @@ -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. diff --git a/docs/python_binding.rst b/docs/python_binding.rst index 5861055fa..d322f5d43 100644 --- a/docs/python_binding.rst +++ b/docs/python_binding.rst @@ -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. diff --git a/docs/streaming.rst b/docs/streaming.rst index 553428718..6ee4bea79 100644 --- a/docs/streaming.rst +++ b/docs/streaming.rst @@ -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 diff --git a/docs/tuning.rst b/docs/tuning.rst index 9d7ee622e..9a9bb671f 100644 --- a/docs/tuning.rst +++ b/docs/tuning.rst @@ -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. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 3b6275f71..f53faa10c 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -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 diff --git a/docs/udp_tracker_protocol.rst b/docs/udp_tracker_protocol.rst index c3efb0059..5f785592d 100644 --- a/docs/udp_tracker_protocol.rst +++ b/docs/udp_tracker_protocol.rst @@ -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. | +-------------+---------------------+----------------------------------------+ diff --git a/docs/utp.rst b/docs/utp.rst index 8b1e285b6..060722144 100644 --- a/docs/utp.rst +++ b/docs/utp.rst @@ -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.