torrentutils - Overview
=======================

The torrentutils are a set of utilities for managing BitTorrent
(`.torrent') files and interactiving with BitTorrent trackers.
The torrentutils contain the following programs:

torrenttool is a script that extracts and displays information
from BitTorrent files, as well as testing and generating
checksums for files listed in them.

defrag is a script that defrags files simply by making a
copy of the file. The original file is then replaced by the
copy. Due to the fact that BitTorrent splits files in pieces,
and downloads these pieces in random order, the downloaded files
are often severely fragmented. This means that reading these files
will be slower, sometimes as much as 30% slower. defrag can
also recurse directories.

torrentmcfs is a read-only virtual file system for Midnight
Commander that can be used to easier access the information
in a BitTorrent file.

Note that newer versions of the official BitTorrent client
does not allocate file contents in advance. It will instead
write pieces in the order they were downloaded, and reorder
them later. This makes defrag unnecessary for files downloaded
with this client. (However, defrag might still be useful as a
file defragmentation tool.)

The torrentutils are written in Perl by Oskar Liljeblad, and is
free software (released under the GNU General Public License).

License
=======

The torrentutils are copyright (C) 2003 Oskar Liljeblad.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Requirements
============

The following programs are required for proper operation of torrenttool:

* Perl 5.004 or later
  The modules File::Spec, File::Basename, Getopt::Long and POSIX must be
  available.

The following programs are required for proper operation of defrag:

* GNU coreutils or GNU fileutils
  defrag uses some GNU extensions to the way arguments to cp, mv
  are handled. For instance, `--' is used to signal end of options.

Installation
============

Run `make install' to install the executable files and the manual pages.
(Note that the torrenttool file installed in the binary directory will
be generated during the installation - it will be merged with the
Bencode.pm Perl module. This is to make installation easier.)

If your Perl binary resides in a different place than /usr/bin/perl,
you need to edit the torrenttool script and update the first line with the
corrent path.

To install the BitTorrent file Virtual File System (VFS) for Midnight
Commander (torrentmcfs), you need to copy torrentmcfs to
/usr/share/mc/extfs and add this line to /usr/share/mc/extfs/extfs.ini:

torrentfs

Usage and Configuration
=======================

A list of options that torrenttool accepts can be displayed by
running torrenttool with the --help option:

  $ torrenttool --help

The same applies to the other included programs.

Please see the manual page for these programs (torrenttool.1
and defrag.1) for full usage and configuration information.
This document can usually be viewed this way:

  $ man ./manpage.1

or

  $ man -l manpage.1

Homepage
========

The latest version of torrentutils can be downloaded from

  http://www.student.lu.se/~nbi98oli/

Feedback
========

The author of torrentutils and this document, Oskar Liljeblad,
can be reached via email address

  oskar@osk.mine.nu
  
Please send bug reports, suggestions, ideas or comments
in general to me.


Known bugs
==========

None so far.

Possible things to do
=====================

Prefix output of info hash etc when multiple torrent files specified?
Complete torrentmcfs (rename torrentfs)
Implement asktracker to get information (like number of seeders) from tracker
Make a tool to write arbitrary data into the torrent - -w option?
  -o FILE		output to file
  -w			write back to original torrent file (not necessary with diff prog)
  -f announce=foobar	alter