{
    "mode": "perldoc",
    "parameter": "File::Fetch",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/File%3A%3AFetch/json",
    "generated": "2026-06-03T01:22:06Z",
    "synopsis": "use File::Fetch;\n### build a File::Fetch object ###\nmy $ff = File::Fetch->new(uri => 'http://some.where.com/dir/a.txt');\n### fetch the uri to cwd() ###\nmy $where = $ff->fetch() or die $ff->error;\n### fetch the uri to /tmp ###\nmy $where = $ff->fetch( to => '/tmp' );\n### parsed bits from the uri ###\n$ff->uri;\n$ff->scheme;\n$ff->host;\n$ff->path;\n$ff->file;",
    "sections": {
        "NAME": {
            "content": "File::Fetch - A generic file fetching mechanism\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use File::Fetch;\n\n### build a File::Fetch object ###\nmy $ff = File::Fetch->new(uri => 'http://some.where.com/dir/a.txt');\n\n### fetch the uri to cwd() ###\nmy $where = $ff->fetch() or die $ff->error;\n\n### fetch the uri to /tmp ###\nmy $where = $ff->fetch( to => '/tmp' );\n\n### parsed bits from the uri ###\n$ff->uri;\n$ff->scheme;\n$ff->host;\n$ff->path;\n$ff->file;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "File::Fetch is a generic file fetching mechanism.\n\nIt allows you to fetch any file pointed to by a \"ftp\", \"http\", \"file\", \"git\" or \"rsync\" uri by a\nnumber of different means.\n\nSee the \"HOW IT WORKS\" section further down for details.\n",
            "subsections": []
        },
        "ACCESSORS": {
            "content": "A \"File::Fetch\" object has the following accessors\n\n$ff->uri\nThe uri you passed to the constructor\n\n$ff->scheme\nThe scheme from the uri (like 'file', 'http', etc)\n\n$ff->host\nThe hostname in the uri. Will be empty if host was originally 'localhost' for a 'file://'\nurl.\n\n$ff->vol\nOn operating systems with the concept of a volume the second element of a file:// is\nconsidered to the be volume specification for the file. Thus on Win32 this routine returns\nthe volume, on other operating systems this returns nothing.\n\nOn Windows this value may be empty if the uri is to a network share, in which case the\n'share' property will be defined. Additionally, volume specifications that use '|' as ':'\nwill be converted on read to use ':'.\n\nOn VMS, which has a volume concept, this field will be empty because VMS file specifications\nare converted to absolute UNIX format and the volume information is transparently included.\n\n$ff->share\nOn systems with the concept of a network share (currently only Windows) returns the\nsharename from a file://// url. On other operating systems returns empty.\n\n$ff->path\nThe path from the uri, will be at least a single '/'.\n\n$ff->file\nThe name of the remote file. For the local file name, the result of $ff->outputfile will be\nused.\n\n$ff->filedefault\nThe name of the default local file, that $ff->outputfile falls back to if it would\notherwise return no filename. For example when fetching a URI like http://www.abc.net.au/\nthe contents retrieved may be from a remote file called 'index.html'. The default value of\nthis attribute is literally 'filedefault'.\n\n$ff->outputfile\nThe name of the output file. This is the same as $ff->file, but any query parameters are\nstripped off. For example:\n\nhttp://example.com/index.html?x=y\n\nwould make the output file be \"index.html\" rather than \"index.html?x=y\".\n",
            "subsections": []
        },
        "METHODS": {
            "content": "$ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );\nParses the uri and creates a corresponding File::Fetch::Item object, that is ready to be\n\"fetch\"ed and returns it.\n\nReturns false on failure.\n\n$where = $ff->fetch( [to => /my/output/dir/ | \\$scalar] )\nFetches the file you requested and returns the full path to the file.\n\nBy default it writes to \"cwd()\", but you can override that by specifying the \"to\" argument:\n\n### file fetch to /tmp, full path to the file in $where\n$where = $ff->fetch( to => '/tmp' );\n\n### file slurped into $scalar, full path to the file in $where\n### file is downloaded to a temp directory and cleaned up at exit time\n$where = $ff->fetch( to => \\$scalar );\n\nReturns the full path to the downloaded file on success, and false on failure.\n\n$ff->error([BOOL])\nReturns the last encountered error as string. Pass it a true value to get the \"Carp::longmess()\"\noutput instead.\n",
            "subsections": []
        },
        "HOW IT WORKS": {
            "content": "File::Fetch is able to fetch a variety of uris, by using several external programs and modules.\n\nBelow is a mapping of what utilities will be used in what order for what schemes, if available:\n\nfile    => LWP, lftp, file\nhttp    => LWP, HTTP::Tiny, wget, curl, lftp, fetch, HTTP::Lite, lynx, iosock\nftp     => LWP, Net::FTP, wget, curl, lftp, fetch, ncftp, ftp\nrsync   => rsync\ngit     => git\n\nIf you'd like to disable the use of one or more of these utilities and/or modules, see the\n$BLACKLIST variable further down.\n\nIf a utility or module isn't available, it will be marked in a cache (see the $METHODFAIL\nvariable further down), so it will not be tried again. The \"fetch\" method will only fail when\nall options are exhausted, and it was not able to retrieve the file.\n\nThe \"fetch\" utility is available on FreeBSD. NetBSD and Dragonfly BSD may also have it from\n\"pkgsrc\". We only check for \"fetch\" on those three platforms.\n\n\"iosock\" is a very limited IO::Socket::INET based mechanism for retrieving \"http\" schemed urls.\nIt doesn't follow redirects for instance.\n\n\"git\" only supports \"git://\" style urls.\n\nA special note about fetching files from an ftp uri:\n\nBy default, all ftp connections are done in passive mode. To change that, see the $FTPPASSIVE\nvariable further down.\n\nFurthermore, ftp uris only support anonymous connections, so no named user/password pair can be\npassed along.\n\n\"/bin/ftp\" is blacklisted by default; see the $BLACKLIST variable further down.\n",
            "subsections": []
        },
        "GLOBAL VARIABLES": {
            "content": "The behaviour of File::Fetch can be altered by changing the following global variables:\n\n$File::Fetch::FROMEMAIL\nThis is the email address that will be sent as your anonymous ftp password.\n\nDefault is \"File-Fetch@example.com\".\n\n$File::Fetch::USERAGENT\nThis is the useragent as \"LWP\" will report it.\n\nDefault is \"File::Fetch/$VERSION\".\n\n$File::Fetch::FTPPASSIVE\nThis variable controls whether the environment variable \"FTPPASSIVE\" and any passive switches\nto commandline tools will be set to true.\n\nDefault value is 1.\n\nNote: When $FTPPASSIVE is true, \"ncftp\" will not be used to fetch files, since passive mode can\nonly be set interactively for this binary\n\n$File::Fetch::TIMEOUT\nWhen set, controls the network timeout (counted in seconds).\n\nDefault value is 0.\n\n$File::Fetch::WARN\nThis variable controls whether errors encountered internally by \"File::Fetch\" should be \"carp\"'d\nor not.\n\nSet to false to silence warnings. Inspect the output of the \"error()\" method manually to see\nwhat went wrong.\n\nDefaults to \"true\".\n\n$File::Fetch::DEBUG\nThis enables debugging output when calling commandline utilities to fetch files. This also\nenables \"Carp::longmess\" errors, instead of the regular \"carp\" errors.\n\nGood for tracking down why things don't work with your particular setup.\n\nDefault is 0.\n\n$File::Fetch::BLACKLIST\nThis is an array ref holding blacklisted modules/utilities for fetching files with.\n\nTo disallow the use of, for example, \"LWP\" and \"Net::FTP\", you could set $File::Fetch::BLACKLIST\nto:\n\n$File::Fetch::BLACKLIST = [qw|lwp netftp|]\n\nThe default blacklist is [qw|ftp|], as \"/bin/ftp\" is rather unreliable.\n\nSee the note on \"MAPPING\" below.\n\n$File::Fetch::METHODFAIL\nThis is a hashref registering what modules/utilities were known to fail for fetching files\n(mostly because they weren't installed).\n\nYou can reset this cache by assigning an empty hashref to it, or individually remove keys.\n\nSee the note on \"MAPPING\" below.\n",
            "subsections": []
        },
        "MAPPING": {
            "content": "Here's a quick mapping for the utilities/modules, and their names for the $BLACKLIST,\n$METHODFAIL and other internal functions.\n\nLWP         => lwp\nHTTP::Lite  => httplite\nHTTP::Tiny  => httptiny\nNet::FTP    => netftp\nwget        => wget\nlynx        => lynx\nncftp       => ncftp\nftp         => ftp\ncurl        => curl\nrsync       => rsync\nlftp        => lftp\nfetch       => fetch\nIO::Socket  => iosock\n",
            "subsections": []
        },
        "FREQUENTLY ASKED QUESTIONS": {
            "content": "So how do I use a proxy with File::Fetch?\n\"File::Fetch\" currently only supports proxies with LWP::UserAgent. You will need to set your\nenvironment variables accordingly. For example, to use an ftp proxy:\n\n$ENV{ftpproxy} = 'foo.com';\n\nRefer to the LWP::UserAgent manpage for more details.\n\nI used 'lynx' to fetch a file, but its contents is all wrong!\n\"lynx\" can only fetch remote files by dumping its contents to \"STDOUT\", which we in turn\ncapture. If that content is a 'custom' error file (like, say, a \"404 handler\"), you will get\nthat contents instead.\n\nSadly, \"lynx\" doesn't support any options to return a different exit code on non-\"200 OK\"\nstatus, giving us no way to tell the difference between a 'successful' fetch and a custom error\npage.\n\nTherefor, we recommend to only use \"lynx\" as a last resort. This is why it is at the back of our\nlist of methods to try as well.\n\nFiles I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?\n\"File::Fetch\" is relatively smart about things. When trying to write a file to disk, it removes\nthe \"query parameters\" (see the \"outputfile\" method for details) from the file name before\ncreating it. In most cases this suffices.\n\nIf you have any other characters you need to escape, please install the \"URI::Escape\" module\nfrom CPAN, and pre-encode your URI before passing it to \"File::Fetch\". You can read about the\ndetails of URIs and URI encoding here:\n\nhttp://www.faqs.org/rfcs/rfc2396.html\n",
            "subsections": []
        },
        "TODO": {
            "content": "Implement $PREFERBIN\nTo indicate to rather use commandline tools than modules\n",
            "subsections": []
        },
        "BUG REPORTS": {
            "content": "Please report bugs or other issues to <bug-file-fetch@rt.cpan.org<gt>.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "This module by Jos Boumans <kane@cpan.org>.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "This library is free software; you may redistribute and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        }
    },
    "summary": "File::Fetch - A generic file fetching mechanism",
    "flags": [],
    "examples": [],
    "see_also": []
}