Net::BitTorrent::Torrent - Class Representing a Single .torrent File


Net::BitTorrent::Torrent objects are typically created by the Net::BitTorrent class.

Standalone Net::BitTorrent::Torrent objects can be made for informational use. See <new|/"new ( { [ARGS] } )"> and queue.


new ( { [ARGS] } )

Creates a Net::BitTorrent::Torrent object. This constructor is called by Net::BitTorrent::add_torrent( ).

new( ) accepts arguments as a hash, using key-value pairs:


The root directory used to store the files related to this torrent. This directory is created if not preexisting.

This is an optional parameter.

Default: ./ (Current working directory)


The Net::BitTorrent object this torrent will eventually be served from.

This is an optional parameter.

No default. Without a defined parent client, his object is very limited in capability. Basic informaion and <hash checking|/hashcheck> only. Orphan objects are obviously not queued automatically and must be added to a client <manually|/"queue ( CLIENT )">.


Filename of the .torrent file to load.

This is the only required parameter.


Initial status of the torrent. This parameter is ORed with the loaded and queued (if applicable) values.

For example, you could set the torrent to automatically start after hashcheck with { [...] Status => 4, [...] }.

This is an optional parameter.

Default: 1 (started)

See also: status

Note: This is alpha code and may not work correctly.


bitfield ( )

Returns a bitfield representing the pieces that have been successfully downloaded.

comment ( )

Returns the (optional) comment the original creator included in the .torrent metadata.

created_by ( )

Returns the (optional) "created by" string included in the .torrent metadata. This is usually a software version.

creation_date ( )

Returns the (optional) creation time of the torrent, in standard UNIX epoch format.

downloaded ( )

Returns the total amount downloaded from remote peers since the client started transfering data related to this .torrent.

See also: uploaded

error ( )

Returns the most recent error that caused the software to set the error status. Torrents with active errors are automatically stopped and must be started.

See also: status, start

files ( )

Returns a list of Net::BitTorrent::Torrent::File objects representing all files contained in the related .torrent file.

hashcheck ( )

Verifies the integrity of all files associated with this torrent.

This is a blocking method; all processing will stop until this function returns.

See also: bitfield, status

infohash ( )

Returns the 20 byte SHA1 hash used to identify this torrent internally, with trackers, and with remote peers.

is_complete ( )

Returns a bool value based on download progress. Returns true when we have completed every file with a priority above 0. Otherwise, returns false.

See also: Net::BitTorrent::Torrent::File->priority()

name ( )

Returns the advisory name used when creating the related files on disk.

In a single file torrent, this is used as the filename by default. In a multiple file torrent, this is used as the containing directory for related files.

path ( )

Returns the filename of the torrent this object represents.

private ( )

Returns bool value dependant on whether the private flag is set in the .torrent metadata. Private torrents disallow information sharing via DHT and PEX.

queue ( CLIENT )

Adds a standalone (or orphan) torrent object to the particular CLIENT object's queue.

See also: remove_torrent ( )

raw_data ( )

Returns the bdecoded metadata. found in the .torrent file.

size ( )

Returns the total size of all files listed in the .torrent file.

status ( )

Returns the internal status of this Net::BitTorrent::Torrent object. States are bitwise AND valuses of...

Value Type Notes
1 Started New peers are accepted and pieces are activly being transfered
2 Checking Currently hashchecking (possibly in another thread)
4 Start after check Unused in this version
8 Checked Files of this torrent have been checked
16 Error Activity is halted and may require user intervention (Unused in this version)
32 Paused New peers are accepted but no piece date is transfered or asked for
64 Loaded Torrent has been parsed without error
128 Queued Has an associated Net::BitTorrent parent

For example, a status of 201 implies the torrent is queued (128), loaded (64), hash checked (8), and is currently active (1). This scheme is inspired by µTorrent.

When torrents have the a status that indicates an error, they must be restarted. The reason for the error may be returned by error.

Note: States are alpha and may not work as advertised. Yet.

start ( )

Starts a paused or stopped torrent.

See also: status, stop, pause

stop ( )

Stops an active or paused torrent. All related sockets (peers) are disconnected and all files are closed.

See also: status, start, pause

pause ( )

Pauses an active torrent without closing related sockets.

See also: status, stop, start


Returns a list of all Net::BitTorrent::Torrent::Tracker objects related to the torrent.

uploaded ( )

Returns the total amount uploaded to remote peers since the client started transfering data related to this .torrent.


Sanko Robinson <> -


License and Legal

Copyright (C) 2008 by Sanko Robinson <>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or For clarification, see

When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See For clarification, see

Neither this module nor the Author is affiliated with BitTorrent, Inc.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1571:

Non-ASCII character seen before =encoding in 'µTorrent.'. Assuming UTF-8