NAME
wmget - Background download manager in a dockapp
SYNOPSIS
wmget dock [options]
wmget [options] {URL}
wmget cancel {job-id}
wmget list
DESCRIPTION
wmget is a ‘‘dockapp’’ which makes it more convenient to retrieve files
in the background. Dockapps are applications which run in small windows
intended to be ‘‘docked’’ in window manager-provided locations. wmget
was developed primarily under GNU Window Maker, the author’s preferred
WM, but is known to work under AfterStep as well, and should work with
other dockapp-aware window managers and docks.
It uses the excellent libcurl library, part of the Curl
automated-download program, to perform file retrieval from Web servers,
FTP servers, and other sources.
wmget allows you to perform multiple downloads without keeping a
terminal open (for FTP or curl or something) or another window on your
desktop (e.g. for Mozilla download progress); download progress is
visible any time the Dock is visible.
You start downloads either by ‘‘pasting’’ URLs from Web browsers or
other applications, or by invoking wmget from the command line (or
another script or program) with a source URL. The dockapp has a handful
of configurable download options, such as target directory, HTTP proxy
server, etc.
STARTING UP
To start the dockapp, just run wmget dock &. If you are running Window
Maker, you can then just drag the new appicon onto your Dock,
right-click on an area outside the four progress bars, select Settings,
and select Start when Window Maker is started.
If you are running AfterStep, you can add it to your Wharf by adding
the following line to your ~/GNUstep/Library/AfterStep/wharf file:
*Wharf wmget - Swallow "wmget" wmget dock &
Other window managers support dockapps in different ways. Even in
window managers without any special dockapp support, you can run wmget
as noted above; it will simply show up as a small window or "icon".
USING WMGET
wmget’s user interface is simple: four stacked progress bars, initially
empty, representing four possible simultaneous downloads. The top bar
will say ‘‘wmget’’ when there isn’t a download running there, but any
download will cover that up.
Each running download normally shows up to nine characters of its
filename, overlaid with a progress bar. You can click on any progress
bar to reveal a percentage display and a stop button; clicking on the
percentage display switches back, while clicking on the stop button
stops the download. There is currently no confirmation; it just stops.
You can ‘‘request’’ downloads at any time. If all four places show
running downloads, additional requests will queue up, waiting for one
to complete; wmget will never be downloading more than four files at a
time.
By default, wmget figures out a reasonable filename for any requested
downloads, writes them to your home directory, and won’t overwrite an
existing file by the same name. All of these, along with a few other
options, are configurable. See below.
Requesting Downloads with the Mouse
The easiest way to request a download is by copying and pasting a link.
wmget lets you paste a URL by middle-clicking anywhere on any of its
status bars. Simply copy a link from some other source (for example, by
right-clicking on a link in Mozilla or Netscape and picking Copy Link
Location), and middle-click on one of the progress meter boxes in
wmget.
Requesting Downloads from the Command Line
The wmget command also lets you directly request downloads from the
command line, or from within a script or another program. The syntax is
wmget URL, plus any of the options documented below.
Once you run this command, you’ll either get an error message or a
‘‘job ID’’. The job ID is only useful in conjunction with the wmget
cancel command.
Download Failures
Downloads can fail for a variety of reasons, from running out of disk
space to modem hangups. Since wmget is designed not to interrupt your
workflow or exceed its little square window, it responds to any
download error by aborting the download and writing an error file to
your download directory. This error file has the name file.ERROR, where
file is the name of the actual download target. This error file is a
plain text file containing information on what you were downloading and
what went wrong.
Viewing and Canceling Downloads
As noted above, you can see the currently-running downloads in the four
progress boxes on the dockapp. Clicking on a bar reveals a stop button,
and clicking on that stop button cancels the download (but leaves the
partially-downloaded file on your computer).
At any time, you can also run the wmget list command, which displays
all the running downloads as well as any queued-up requests. The
listing contains entries like this:
Job 10 [linux-2.6]: 1658544/33073407 RUNNING
ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.0-test6.tar.bz2
=> /home/aaron/DOWNLOAD/linux-2.6.0-test6.tar.bz2
What you see in that (admittedly dense) listing are the job ID, the
name of the download as displayed on the dockapp (surrounded in
brackets), the progress in bytes, the total bytes to download, the
current status, the source URL, and the target file on your computer.
Whew.
You can cancel any requested or running download from the command line
by specifying wmget cancel job-id.
COMMAND-LINE OPTIONS AND THE CONFIGURATION FILE
wmget supports a handful of configuration options. You can specify
defaults for all downloads by putting them in a configuration file or
adding command-line options to the wmget dock command at startup, or
you can specify options for one specific download by adding options to
the wmget URL command when you request them. There isn’t any way to
specify options on URLs you paste with the mouse. Dockapp command-line
arguments override config-file settings, and per-URL settings override
dockapp settings.
The configuration file is an optional file named .wmgetrc in your home
directory. If it’s there, it’s parsed by the dockapp at startup. The
syntax is simple: one option per line, all options consisting of a name
and possibly a value. Blank lines are okay, and lines starting with #
are ignored (so you can disable options easily). Option names are just
the same as the command-line option names given below, except you don’t
put the dashes (‘‘--’’) and you can’t use the one-letter abbreviations.
--version, -v
Regardless of any other options, this prints out version and
copyright information and exits.
--help, -h
Regardless of any other options, this prints out a help message
and exits.
--silent, -s
Suppress any output text other than error messages.
--verbose, -V
Write extra debugging information; not very useful unless you’re
debugging or extending the software.
--output pathname, -o pathname
Specifies where to write downloaded files. In the config file or
on the dockapp command line, this can only be used to specify
your default download directory; it must be an existing
directory, and if it’s not absolute then it is assumed to be
relative to your home directory. On a specific download request,
this can provide an alternate save directory or even an
alternate filename; in that case, a non-absolute path is
relative to the default download directory.
--display name, -d name
Display the first nine characters of name in the progress
display for this file. (Only valid on specific download
requests, not on the dockapp or in the config file.)
--overwrite, -O
Allow wmget to overwrite an existing file when downloading.
Normally, it will refuse to do so.
--continue, -C
When fetching a file that already exists locally, assume the
local copy was an aborted download and try to download just the
remainder.
--auth username:password, -a username:password
Provides login information for the server from which you’re
downloading.
--proxy server:port, -p server:port, --proxy_auth user:password, -P
user:password
Specifies a proxy server and optionally a proxy-server
username/password pair for getting past firewalls.
--follow N, -f N
Specifies how many HTTP redirects to follow when resolving a
page; by default, wmget is configured to follow up to 5. Set
this to 0 to disable redirection. (In any real-world situation,
if you’re getting redirected more than 5 times, there’s a
problem...)
--user-agent string, -U string
Specifies which User-Agent string to provide to servers when
performing HTTP downloads. The default User-Agent names both the
wmget and libcurl versions in use.
--ascii, -B
Force FTP downloads to use ASCII mode; normally, they use binary
mode. If you’re downloading text documents, ASCII mode will take
care of any necessary conversions between the text formats of
the server and your computer.
--referer string, -e string
Provides a ‘‘referer’’ string to the Web server.
--interface interface, --n interface
Names a specific network interface to use (e.g., eth0 for the
first Ethernet interface on a Linux system). Rarely needed.
--headers, -h
When performing an HTTP retrieval, include the HTTP message
header in the saved file. This is only really useful for
testing.
FILES
~/.wmgetrc
The (optional) configuration file for the wmget dockapp.
Settings in this file are used to specify defaults for the
dockapp when it starts; see the section on configuration and
command-line options for more details.
~/.wmget.iq
A Unix-domain socket created by the wmget dockapp to accept
requests from wmget commands. Created at startup automatically.
AUTHOR
Aaron Trickey.