{
    "mode": "perldoc",
    "parameter": "File::Copy::Recursive",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/File%3A%3ACopy%3A%3ARecursive/json",
    "generated": "2026-06-16T04:57:09Z",
    "synopsis": "use File::Copy::Recursive qw(fcopy rcopy dircopy fmove rmove dirmove);\nfcopy($orig,$new[,$buf]) or die $!;\nrcopy($orig,$new[,$buf]) or die $!;\ndircopy($orig,$new[,$buf]) or die $!;\nfmove($orig,$new[,$buf]) or die $!;\nrmove($orig,$new[,$buf]) or die $!;\ndirmove($orig,$new[,$buf]) or die $!;\nrcopyglob(\"orig/stuff-*\", $trg [, $buf]) or die $!;\nrmoveglob(\"orig/stuff-*\", $trg [,$buf]) or die $!;",
    "sections": {
        "NAME": {
            "content": "File::Copy::Recursive - Perl extension for recursively copying files and\ndirectories\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use File::Copy::Recursive qw(fcopy rcopy dircopy fmove rmove dirmove);\n\nfcopy($orig,$new[,$buf]) or die $!;\nrcopy($orig,$new[,$buf]) or die $!;\ndircopy($orig,$new[,$buf]) or die $!;\n\nfmove($orig,$new[,$buf]) or die $!;\nrmove($orig,$new[,$buf]) or die $!;\ndirmove($orig,$new[,$buf]) or die $!;\n\nrcopyglob(\"orig/stuff-*\", $trg [, $buf]) or die $!;\nrmoveglob(\"orig/stuff-*\", $trg [,$buf]) or die $!;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module copies and moves directories recursively (or single files,\nwell... singley) to an optional depth and attempts to preserve each file\nor directory's mode.\n",
            "subsections": []
        },
        "EXPORT": {
            "content": "None by default. But you can export all the functions as in the example\nabove and the path* functions if you wish.\n\nfcopy()\nThis function uses File::Copy's copy() function to copy a file but not a\ndirectory. Any directories are recursively created if need be. One\ndifference to File::Copy::copy() is that fcopy attempts to preserve the\nmode (see Preserving Mode below) The optional $buf in the synopsis is\nthe same as File::Copy::copy()'s 3rd argument. This function returns the\nsame as File::Copy::copy() in scalar context and 1,0,0 in list context\nto accomodate rcopy()'s list context on regular files. (See below for\nmore info)\n\ndircopy()\nThis function recursively traverses the $orig directory's structure and\nrecursively copies it to the $new directory. $new is created if\nnecessary (multiple non existent directories is ok (i.e. foo/bar/baz).\nThe script logically and portably creates all of them if necessary). It\nattempts to preserve the mode (see Preserving Mode below) and by default\nit copies all the way down into the directory (see Managing Depth,\nbelow). If a directory is not specified it croaks just like fcopy croaks\nif its not a file that is specified.\n\nThis function returns true or false: for true in scalar context it\nreturns the number of files and directories copied, whereas in list\ncontext it returns the number of files and directories, number of\ndirectories only, depth level traversed.\n\nmy $numoffilesanddirs = dircopy($orig,$new);\nmy($numoffilesanddirs,$numofdirs,$depthtraversed) = dircopy($orig,$new);\n\nNormally it stops and returns if a copy fails. To continue on\nregardless, set $File::Copy::Recursive::SkipFlop to true.\n\nlocal $File::Copy::Recursive::SkipFlop = 1;\n\nThat way it will copy everythging it can in a directory and won't stop\nbecause of permissions, etc...\n\nrcopy()\nThis function will allow you to specify a file *or* a directory. It\ncalls fcopy() if you passed file and dircopy() if you passed a\ndirectory. If you call rcopy() (or fcopy() for that matter) on a file in\nlist context, the values will be 1,0,0 since no directories and no depth\nare used. This is important because if it's a directory in list context\nand there is only the initial directory the return value is 1,1,1.\n\nrcopyglob()\nThis function lets you specify a pattern suitable for perl's\nFile::Glob::bsdglob() as the first argument. Subsequently each path\nreturned by perl's File::Glob::bsdglob() gets rcopy()ied.\n\nIt returns and array whose items are array refs that contain the return\nvalue of each rcopy() call.\n\nIt forces behavior as if $File::Copy::Recursive::CPRFComp is true.\n\nfmove()\nCopies the file then removes the original. You can manage the path the\noriginal file is in according to $RemvBase.\n\ndirmove()\nUses dircopy() to copy the directory then removes the original. You can\nmanage the path the original directory is in according to $RemvBase.\n\nrmove()\nLike rcopy() but calls fmove() or dirmove() instead.\n\nrmoveglob()\nLike rcopyglob() but calls rmove() instead of rcopy()\n\n$RemvBase\nDefault is false. When set to true the *move() functions will not only\nattempt to remove the original file or directory but will remove the\ngiven path it is in.\n\nSo if you:\n\nrmove('foo/bar/baz', '/etc/');\n# \"baz\" is removed from foo/bar after it is successfully copied to /etc/\n\nlocal $File::Copy::Recursive::Remvbase = 1;\nrmove('foo/bar/baz','/etc/');\n# if baz is successfully copied to /etc/ :\n# first \"baz\" is removed from foo/bar\n# then \"foo/bar is removed via pathrm()\n\n$ForcePth\nDefault is false. When set to true it calls pathempty() before any\ndirectories are removed to empty the directory so it can be rmdir()'ed\nwhen $RemvBase is in effect.\n",
            "subsections": [
                {
                    "name": "Creating and Removing Paths",
                    "content": "$NoFtlPth\nDefault is false. If set to true rmdir(), mkdir(), and pathempty() calls\nin pathrm() and pathmk() do not return() on failure.\n\nIf its set to true they just silently go about their business\nregardless. This isn't a good idea but it's there if you want it.\n\n$DirPerms\nMode to pass to any mkdir() calls. Defaults to 0777 as per umask()'s\nPOD. Explicitly having this allows older perls to be able to use FCR and\nmight add a bit of flexibility for you.\n\nAny value you set it to should be suitable for oct().\n\nPath functions\nThese functions exist solely because they were necessary for the move\nand copy functions to have the features they do and not because they are\nof themselves the purpose of this module. That being said, here is how\nthey work so you can understand how the copy and move functions work and\nuse them by themselves if you wish.\n\npathrm()\nRemoves a given path recursively. It removes the *entire* path so be\ncareful!!!\n\nReturns 2 if the given path is not a directory.\n\nFile::Copy::Recursive::pathrm('foo/bar/baz') or die $!;\n# foo no longer exists\n\nSame as:\n\nrmdir 'foo/bar/baz' or die $!;\nrmdir 'foo/bar' or die $!;\nrmdir 'foo' or die $!;\n\nAn optional second argument makes it call pathempty() before any"
                },
                {
                    "name": "rmdir",
                    "content": "File::Copy::Recursive::pathrm('foo/bar/baz', 1) or die $!;\n# foo no longer exists\n\nSame as:PFSCheck\n\nFile::Copy::Recursive::pathempty('foo/bar/baz') or die $!;\nrmdir 'foo/bar/baz' or die $!;\nFile::Copy::Recursive::pathempty('foo/bar/') or die $!;\nrmdir 'foo/bar' or die $!;\nFile::Copy::Recursive::pathempty('foo/') or die $!;\nrmdir 'foo' or die $!;\n\nAn optional third argument acts like $File::Copy::Recursive::NoFtlPth,\nagain probably not a good idea.\n\npathempty()\nRecursively removes the given directory's contents so it is empty.\nReturns 2 if the given argument is not a directory, 1 on successfully\nemptying the directory.\n\nFile::Copy::Recursive::pathempty($pth) or die $!;\n# $pth is now an empty directory\n\npathmk()\nCreates a given path recursively. Creates foo/bar/baz even if foo does\nnot exist.\n\nFile::Copy::Recursive::pathmk('foo/bar/baz') or die $!;\n\nAn optional second argument if true acts just like\n$File::Copy::Recursive::NoFtlPth, which means you'd never get your die()\nif something went wrong. Again, probably a *bad* idea.\n\npathrmdir()\nSame as rmdir() but it calls pathempty() first to recursively empty it\nfirst since rmdir can not remove a directory with contents. Just removes\nthe top directory the path given instead of the entire path like"
                },
                {
                    "name": "pathrm",
                    "content": "already gone). Returns false if it exists but is not a directory.\n"
                },
                {
                    "name": "Preserving Mode",
                    "content": "By default a quiet attempt is made to change the new file or directory\nto the mode of the old one. To turn this behavior off set\n$File::Copy::Recursive::KeepMode to false;\n"
                },
                {
                    "name": "Managing Depth",
                    "content": "You can set the maximum depth a directory structure is recursed by\nsetting: $File::Copy::Recursive::MaxDepth to a whole number greater than\n0.\n"
                },
                {
                    "name": "SymLinks",
                    "content": "If your system supports symlinks then symlinks will be copied as\nsymlinks instead of as the target file. Perl's symlink() is used instead\nof File::Copy's copy(). You can customize this behavior by setting\n$File::Copy::Recursive::CopyLink to a true or false value. It is already\nset to true or false depending on your system's support of symlinks so\nyou can check it with an if statement to see how it will behave:\n\nif($File::Copy::Recursive::CopyLink) {\nprint \"Symlinks will be preserved\\n\";\n} else {\nprint \"Symlinks will not be preserved because your system does not support it\\n\";\n}\n\nIf symlinks are being copied you can set\n$File::Copy::Recursive::BdTrgWrn to true to make it carp when it copies\na link whose target does not exist. It's false by default.\n\nlocal $File::Copy::Recursive::BdTrgWrn  = 1;\n"
                },
                {
                    "name": "Removing existing target file or directory before copying.",
                    "content": "This can be done by setting $File::Copy::Recursive::RMTrgFil or\n$File::Copy::Recursive::RMTrgDir for file or directory behavior\nrespectively.\n\n0 = off (This is the default)\n\n1 = carp() $! if removal fails\n\n2 = return if removal fails\n\nlocal $File::Copy::Recursive::RMTrgFil = 1;\nfcopy($orig, $target) or die $!;\n# if it fails it does warn() and keeps going\n\nlocal $File::Copy::Recursive::RMTrgDir = 2;\ndircopy($orig, $target) or die $!;\n# if it fails it does your \"or die\"\n\nThis should be unnecessary most of the time but it's there if you need\nit :)\n\nTurning off stat() check\nBy default the files or directories are checked to see if they are the\nsame (i.e. linked, or two paths (absolute/relative or different relative\npaths) to the same file) by comparing the file's stat() info. It's a\nvery efficient check that croaks if they are and shouldn't be turned off\nbut if you must for some weird reason just set\n$File::Copy::Recursive::PFSCheck to a false value. (\"PFS\" stands for\n\"Physical File System\")\n\nEmulating cp -rf dir1/ dir2/\nBy default dircopy($dir1,$dir2) will put $dir1's contents right into\n$dir2 whether $dir2 exists or not.\n\nYou can make dircopy() emulate cp -rf by setting\n$File::Copy::Recursive::CPRFComp to true.\n\nNOTE: This only emulates -f in the sense that it does not prompt. It\ndoes not remove the target file or directory if it exists. If you need\nto do that then use the variables $RMTrgFil and $RMTrgDir described in\n\"Removing existing target file or directory before copying\" above.\n\nThat means that if $dir2 exists it puts the contents into $dir2/$dir1\ninstead of $dir2 just like cp -rf. If $dir2 does not exist then the\ncontents go into $dir2 like normal (also like cp -rf).\n\nSo assuming 'foo/file':\n\ndircopy('foo', 'bar') or die $!;\n# if bar does not exist the result is bar/file\n# if bar does exist the result is bar/file\n\n$File::Copy::Recursive::CPRFComp = 1;\ndircopy('foo', 'bar') or die $!;\n# if bar does not exist the result is bar/file\n# if bar does exist the result is bar/foo/file\n\nYou can also specify a star for cp -rf glob type behavior:\n\ndircopy('foo/*', 'bar') or die $!;\n# if bar does not exist the result is bar/file\n# if bar does exist the result is bar/file\n\n$File::Copy::Recursive::CPRFComp = 1;\ndircopy('foo/*', 'bar') or die $!;\n# if bar does not exist the result is bar/file\n# if bar does exist the result is bar/file\n\nNOTE: The '*' is only like cp -rf foo/* and *DOES NOT EXPAND PARTIAL\nDIRECTORY NAMES LIKE YOUR SHELL DOES* (i.e. not like cp -rf fo* to copy\nfoo/*).\n"
                },
                {
                    "name": "Allowing Copy Loops",
                    "content": "If you want to allow:\n\ncp -rf . foo/\n\ntype behavior set $File::Copy::Recursive::CopyLoop to true.\n\nThis is false by default so that a check is done to see if the source\ndirectory will contain the target directory and croaks to avoid this\nproblem.\n\nIf you ever find a situation where $CopyLoop = 1 is desirable let me\nknow. (i.e. it's a bad bad idea but is there if you want it)\n\n(Note: On Windows this was necessary since it uses stat() to determine\nsameness and stat() is essentially useless for this on Windows. The test\nis now simply skipped on Windows but I'd rather have an actual reliable\ncheck if anyone in Microsoft land would care to share)\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "File::Copy File::Spec\n",
            "subsections": []
        },
        "TO DO": {
            "content": "I am currently working on and reviewing some other modules to use in the\nnew interface so we can lose the horrid globals as well as some other\nundesirable traits and also more easily make available some long\nstanding requests.\n\nTests will be easier to do with the new interface and hence the testing\nfocus will shift to the new interface and aim to be comprehensive.\n\nThe old interface will work, it just won't be brought in until it is\nused, so it will add no overhead for users of the new interface.\n\nI'll add this after the latest version has been out for a while with no\nnew features or issues found :)\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Daniel Muey, <http://drmuey.com/cpancontact.pl>\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright 2004 by Daniel Muey\n\nThis library is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n",
            "subsections": []
        }
    },
    "summary": "File::Copy::Recursive - Perl extension for recursively copying files and directories",
    "flags": [],
    "examples": [],
    "see_also": []
}