userguide

最经典的bittorrent协议的实现的源码

                       Enhanced CTorrent User's Guide

   This guide is presented to offer additional information related to
   using [1]Enhanced CTorrent.

   This document is not an introduction to BitTorrent--for that, try
   [2]this, [3]this, or an Internet search.

  Contents

     * Options
          + [4]General
          + [5]Downloading
          + [6]Create Torrent
     * [7]Examples
     * [8]Runtime Commands
          + [9]Operator Menu
     * Usage Notes
          + [10]Bandwidth Limits
          + [11]Startup
          + [12]Status Line
          + [13]Stopping CTorrent

   Options Index
   [14]-a [15]-A [16]-b [17]-c [18]-C [19]-d [20]-D [21]-e [22]-E [23]-f
   [24]-i [25]-l [26]-m [27]-M [28]-n [29]-p [30]-P [31]-s [32]-s [33]-S
   [34]-t [35]-T [36]-u [37]-U [38]-v [39]-x [40]-X [41]-z
     _________________________________________________________________

   Options
   ___________________________________

  General Options


-x          Decode metainfo (torrent) file only, don't download.

          Displays the torrent information and contents from the metainfo
          (.torrent) file. No piece checking or downloading is performed.
          This option is normally used alone.


-c          Check pieces only, don't download.

          Hash-checks all pieces of the torrent to verify completion
          status and exits. Use this when you want to verify that you've
          successfully downloaded the complete torrent, or to make sure
          the files are intact after a system crash. This option is
          normally used alone.


-v          Verbose output (for debugging).

          Generates [a lot of] extra output while CTorrrent is running.
   ___________________________________

  Downloading Options


-e int      Exit while seed <int> hours later. (default 72 hours)

          Indicate how long (in hours) you want to "seed" (continue
          uploading) after download has completed. It is considered
          polite and fair (and required by some tracker sites) to seed
          for some time after downloading.


-E num      Exit after seeding to <num> ratio (UL:DL).

          Specify a desired "seed ratio". After downloading completes,
          the client will continue seeding (uploading) until your total
          upload volume divided by your download volume equals this
          number. Fractional values (such as 1.5) are allowed. It is
          considered polite and fair (and required by some tracker sites)
          to seed until your ratio is at least 1:1.


-i ip       Listen for connections on ip. (default all IP's)

          Specify the IP address on which you want to listen for incoming
          connections. This is only useful if your system has multiple
          network interfaces and you want to restrict access or run
          multiple clients on different interfaces.


-p port     Listen port. (default 2706 -> 2106)

          Specify the TCP port number on which to listen for incoming
          connections. By default, CTorrent starts at 2706 and searches
          for an available port in decreasing order until it finds one or
          exhausts all ports down through 2106. The behavior with this
          option is similar, but starting at the specified port number.


-s filename     Download ("save as") to a different file or directory.

          Download to a different filename or top-level directory name
          than what is given in the metainfo file.


-C cache_size   Cache size, unit MB. (default 16MB)

          Specify the maximum amount of memory to use for caching
          downloaded slices. The program may use less than this; the
          cache size is dynamically tuned based on the download and
          upload rates. You may need to use this option if running on a
          memory-constrained system such as a router or SAN device. If
          you use a value of 0, no memory cache will be used but the
          process will be more disk-intensive.


-f              Force saved bitfield or seed mode (skip hash check at startup).

          Perform a fast startup by skipping the initial (or background)
          hash verification of the files. This option is not generally
          recommended since the client now performs initial hash checking
          in the background. Use this option only if CTorrent was shut
          down cleanly when last downloading this torrent and you are
          absolutely certain that the bitfield (if download is not
          complete) and data files are intact and correct. To emulate the
          old behavior of hash-checking all pieces before beginning
          download or seeding, use -f along with the -c option.


-b filename     Specify bitfield save file (default is torrent+".bf")

          Piece completion status is saved to a bitfield file on exit if
          download has not completed. On startup the file is read to
          determine (and check) available pieces. The -b option can be
          used to specify a filename other than the default. Be
          consistent and careful with this option; it is generally not
          needed.


-M max_peers    Max peers count. (default 100)

          Set the maximum allowable number of peer connections. If this
          number is reached, no new connections will be initiated or
          accepted. If memory or upload bandwidth are constrained, you
          may want to use this option to specify a lower value.


-m min_peers    Min peers count. (default 1)

          Set the desired minimum number of peer connections. If the
          number falls below this value, the client will contact the
          tracker to request more peers.


-z slice_size   Download slice/block size, unit KB. (default 16, max 128).

          Sets the size of the basic unit of download. For greatest
          compatibility with other peer clients, use the default. This
          value can also affect the precision with which bandwidth is
          managed.


-n file_list    Specify file number(s) to download.

          Specify a priority order for downloading files in the torrent.
          A comma-separated list of file numbers and groups can be
          specified; the file numbers can be seen with the -x option. The
          client will preferentially request pieces of the
          highest-priority files, requesting a piece from a
          lower-priority group if a peer has no such pieces.
          A group may consist of:

          + a file number
          + a range of file numbers (x-y)
          + a combination of file numbers and ranges separated with plus
            (+) signs
          + an asterisk (*) or 3-dot ellipsis (...)

          If an asterisk (remember to quote it on the command line!) or
          ellipsis is used, the client will download and seed the
          remainder of the torrent once the prioritized files are
          completed; this is similar to the previous behavior of the
          option. If no such specification is given, the client will
          download and seed only the indicated files.
          Examples:

        -n 3
                Download and seed only file 3.

        -n 3+5+7,8-11
                Download files 3, 5, and 7 simultaneously, then download
                files 8 through 11 simultaneously, then stop downloading
                and seed all downloaded files.

        -n 3-4,...
                Download files 3 and 4 simultaneously, then download and
                seed all remaining content.


-D rate         Max bandwidth down (unit KB/s)

          Specify a download bandwidth limit for this torrent. The client
          will maintain its short-term average download rate at or below
          this value.


-U rate         Max bandwidth up (unit KB/s)

          Specify an upload bandwidth limit for this torrent. The client
          will maintain its short-term average upload rate at or below
          this value.


-P peer_id      Set Peer ID prefix. (default "-CD0301-")

          Specify an alternate peer ID prefix. This can be useful if a
          tracker is set up to only allow client programs that it
          recognizes. (The admin may not even realize it, so you may want
          to try contacting them to request that they change their
          configuration or add Enhanced CTorrent to the list.) If you
          receive a tracker warning message that your client is out of
          date, try using this option with the prefix of another
          well-known client program (such as "-AZ2304-").


-A user_agent   Set User-Agent header. (default "Enhanced-CTorrent/dnh3.1")

          Specify an alternate user-agent header. This can be useful if a
          tracker is set up to only allow client programs that it
          recognizes.


-S host:port    Use CTCS server at host:port.

          Maintain a connection to CTCS for status reporting, bandwidth
          control, and client management. Using a colon at the end of the
          parameter (as in "-S localhost:2780:") will cause the client to
          prompt for a password to send to CTCS when connecting.


-a              Preallocate files on disk

          Use this if you are concerned about file fragmentation or
          out-of-order block storage. This option is only effective when
          initially creating the files and will cause startup to take
          longer as each entire file is written in order to reserve
          physical disk space. Note that all files will be created and
          preallocated even if the "-n" option is used to download a
          particular file.


-T              Convert foreign filenames to printable text

          Substitutes a hex representation of any non-printable
          characters in filenames; an underscore will be inserted between
          any such sequences and regular text. This applies to printing
          the name of the file as well as accessing it on disk, so you
          need to use it (or not) consistently across multiple runs of
          the same torrent. It does not apply to names specified with the
          "-s" option.


-X command      Run command upon download completion ("user exit")

          Specifies a "user exit" command to run upon download
          completion. The string parameter will be passed to the sh shell
          for execution; see the system() man page for further
          clarification. You will need to quote this string on the
          command line in order to identify it as a single parameter and
          prevent special characters from being interpreted. Some
          substitution sequences beginning with ampersand (&) are
          available; note that it's a good idea to quote the sequence
          within the string so that the substituted names will be quoted
          in the final command.

          + &d will be replaced by the name of the directory or filename
            that contains the downloaded data.
          + &t will be replaced by the name of the torrent metainfo file
            (with path, if it was specified that way to ctorrent).
          + &w will be replaced by the client's working directory.

          Note that the fork() and system() system/library functions are
          used for best portability. As a result, significant extra
          memory may be used while the specified command is running. Be
          advised to use this feature as a trigger mechanism to update a
          file or run a short script that kicks off a background task
          rather than for executing a longer task directly.


-d              Daemon mode (fork to background)

          The client will detach itself from the terminal session and