{ "mode": "perldoc", "parameter": "File::Copy", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/File%3A%3ACopy/json", "generated": "2026-05-30T06:05:10Z", "synopsis": "use File::Copy;\ncopy(\"sourcefile\",\"destinationfile\") or die \"Copy failed: $!\";\ncopy(\"Copy.pm\",\\*STDOUT);\nmove(\"/dev1/sourcefile\",\"/dev2/destinationfile\");\nuse File::Copy \"cp\";\n$n = FileHandle->new(\"/a/file\",\"r\");\ncp($n,\"x\");", "sections": { "NAME": { "content": "File::Copy - Copy files or filehandles\n", "subsections": [] }, "SYNOPSIS": { "content": "use File::Copy;\n\ncopy(\"sourcefile\",\"destinationfile\") or die \"Copy failed: $!\";\ncopy(\"Copy.pm\",\\*STDOUT);\nmove(\"/dev1/sourcefile\",\"/dev2/destinationfile\");\n\nuse File::Copy \"cp\";\n\n$n = FileHandle->new(\"/a/file\",\"r\");\ncp($n,\"x\");\n", "subsections": [] }, "DESCRIPTION": { "content": "The File::Copy module provides two basic functions, \"copy\" and \"move\",\nwhich are useful for getting the contents of a file from one place to\nanother.\n\ncopy\nThe \"copy\" function takes two parameters: a file to copy from and a\nfile to copy to. Either argument may be a string, a FileHandle\nreference or a FileHandle glob. Obviously, if the first argument is\na filehandle of some sort, it will be read from, and if it is a file\n*name* it will be opened for reading. Likewise, the second argument\nwill be written to. If the second argument does not exist but the\nparent directory does exist, then it will be created. Trying to copy\na file into a non-existent directory is an error. Trying to copy a\nfile on top of itself is also an error. \"copy\" will not overwrite\nread-only files.\n\nIf the destination (second argument) already exists and is a\ndirectory, and the source (first argument) is not a filehandle, then\nthe source file will be copied into the directory specified by the\ndestination, using the same base name as the source file. It's a\nfailure to have a filehandle as the source when the destination is a\ndirectory.\n\nNote that passing in files as handles instead of names may lead to\nloss of information on some operating systems; it is recommended\nthat you use file names whenever possible. Files are opened in\nbinary mode where applicable. To get a consistent behaviour when\ncopying from a filehandle to a file, use \"binmode\" on the\nfilehandle.\n\nAn optional third parameter can be used to specify the buffer size\nused for copying. This is the number of bytes from the first file,\nthat will be held in memory at any given time, before being written\nto the second file. The default buffer size depends upon the file,\nbut will generally be the whole file (up to 2MB), or 1k for\nfilehandles that do not reference files (eg. sockets).\n\nYou may use the syntax \"use File::Copy \"cp\"\" to get at the \"cp\"\nalias for this function. The syntax is *exactly* the same. The\nbehavior is nearly the same as well: as of version 2.15, \"cp\" will\npreserve the source file's permission bits like the shell utility\ncp(1) would do, while \"copy\" uses the default permissions for the\ntarget file (which may depend on the process' \"umask\", file\nownership, inherited ACLs, etc.). If an error occurs in setting\npermissions, \"cp\" will return 0, regardless of whether the file was\nsuccessfully copied.\n\nmove\nThe \"move\" function also takes two parameters: the current name and\nthe intended name of the file to be moved. If the destination\nalready exists and is a directory, and the source is not a\ndirectory, then the source file will be renamed into the directory\nspecified by the destination.\n\nIf possible, move() will simply rename the file. Otherwise, it\ncopies the file to the new location and deletes the original. If an\nerror occurs during this copy-and-delete process, you may be left\nwith a (possibly partial) copy of the file under the destination\nname.\n\nYou may use the \"mv\" alias for this function in the same way that\nyou may use the \"cp\" alias for \"copy\".\n\nsyscopy\nFile::Copy also provides the \"syscopy\" routine, which copies the\nfile specified in the first parameter to the file specified in the\nsecond parameter, preserving OS-specific attributes and file\nstructure. For Unix systems, this is equivalent to the simple \"copy\"\nroutine, which doesn't preserve OS-specific attributes. For VMS\nsystems, this calls the \"rmscopy\" routine (see below). For OS/2\nsystems, this calls the \"syscopy\" XSUB directly. For Win32 systems,\nthis calls \"Win32::CopyFile\".\n\nSpecial behaviour if \"syscopy\" is defined (OS/2, VMS and Win32):\n\nIf both arguments to \"copy\" are not file handles, then \"copy\" will\nperform a \"system copy\" of the input file to a new output file, in\norder to preserve file attributes, indexed file structure, *etc.*\nThe buffer size parameter is ignored. If either argument to \"copy\"\nis a handle to an opened file, then data is copied using Perl\noperators, and no effort is made to preserve file attributes or\nrecord structure.\n\nThe system copy routine may also be called directly under VMS and\nOS/2 as \"File::Copy::syscopy\" (or under VMS as\n\"File::Copy::rmscopy\", which is the routine that does the actual\nwork for syscopy).\n\nrmscopy($from,$to[,$dateflag])\nThe first and second arguments may be strings, typeglobs, typeglob\nreferences, or objects inheriting from IO::Handle; they are used in\nall cases to obtain the *filespec* of the input and output files,\nrespectively. The name and type of the input file are used as\ndefaults for the output file, if necessary.\n\nA new version of the output file is always created, which inherits\nthe structure and RMS attributes of the input file, except for owner\nand protections (and possibly timestamps; see below). All data from\nthe input file is copied to the output file; if either of the first\ntwo parameters to \"rmscopy\" is a file handle, its position is\nunchanged. (Note that this means a file handle pointing to the\noutput file will be associated with an old version of that file\nafter \"rmscopy\" returns, not the newly created version.)\n\nThe third parameter is an integer flag, which tells \"rmscopy\" how to\nhandle timestamps. If it is < 0, none of the input file's timestamps\nare propagated to the output file. If it is > 0, then it is\ninterpreted as a bitmask: if bit 0 (the LSB) is set, then timestamps\nother than the revision date are propagated; if bit 1 is set, the\nrevision date is propagated. If the third parameter to \"rmscopy\" is\n0, then it behaves much like the DCL COPY command: if the name or\ntype of the output file was explicitly specified, then no timestamps\nare propagated, but if they were taken implicitly from the input\nfilespec, then all timestamps other than the revision date are\npropagated. If this parameter is not supplied, it defaults to 0.\n\n\"rmscopy\" is VMS specific and cannot be exported; it must be\nreferenced by its full name, e.g.:\n\nFile::Copy::rmscopy($from, $to) or die $!;\n\nLike \"copy\", \"rmscopy\" returns 1 on success. If an error occurs, it\nsets $!, deletes the output file, and returns 0.\n", "subsections": [] }, "RETURN": { "content": "All functions return 1 on success, 0 on failure. $! will be set if an\nerror was encountered.\n", "subsections": [] }, "NOTES": { "content": "Before calling copy() or move() on a filehandle, the caller should close\nor flush() the file to avoid writes being lost. Note that this is the\ncase even for move(), because it may actually copy the file, depending\non the OS-specific implementation, and the underlying filesystem(s).\n", "subsections": [] }, "AUTHOR": { "content": "File::Copy was written by Aaron Sherman ** in 1995, and\nupdated by Charles Bailey ** in 1996.\n", "subsections": [] } }, "summary": "File::Copy - Copy files or filehandles", "flags": [], "examples": [], "see_also": [] }