# copy_file

Definition: | bool res = copy_file(string src, dest, bool overwrite=false) -- or -- bool res = copy_directory(string src, dest, bool overwrite=false)
Description: | Copy a file or directory. src: the name of the file or directory to copy. It must exist. dest: the new name or location of the file. overwrite: false (0/the default) prevents an existing destination file from being overwritten. true (non-zero) permits the overwriting of any existing destination file. Returns: true (1) on success, false (0) on failure.
pwa/p2js: | Not supported.
Comments: | copy_file() can be used to copy files or directories, whereas copy_directory() verifies that src really is a directory (returns false if not) before proceeding. The latter exists mainly just to make code a little more self-documenting, rather than providing any additional functionality. Note there is no routine that verfies src is not a directory before proceeding, for that you must explicitly check that get_file_type(src)==FILETYPE_FILE first. If overwrite is true and dest already exists, the function overwrites the existing file and succeeds. If src is a directory, a full recursive copy occurs. For something more selective see walk_dir(). If dest is a directory, a file of the same name as source is created therein. Unlike some other routines here, any path separators should be appropriate for the operating system, namely backslash ('\\') on Windows and forwardslash ('/') on Linux. If in doubt (not already a result from the top half of the table) pass src/dest through get_proper_path() and/or get_proper_dir() before passing them to this routine. For best results, use fully qualified absolute pathnames. You should not rely on relative paths in dest any more than you do in src; for instance copy_file(`demo\test`,`demo\test2`) is fine, whereas copy_file(`demo\test`,"test2") is likely to copy to the parent directory, and copy_file(`C:\Program Files (x86)\Phix\demo\test`,"test2") is likely to copy it to the current directory. The precise behaviour of path-less operations is operating system dependent. If overwrite was requested but the copy fails, there is no guarantee that any existing destination file is preserved, deleted, corrupted, or all three. The use of a named parameter when setting the overwrite parameter recommended, to make the intent clear and the code easier to read.
Example: |
    if not copy_file("blank.bmp",new_bmp,overwrite:=true) then
        fatal("cannot create "&newname)
    end if
Implementation: | See builtins\pfile.e (an autoinclude) for details of the actual implementation.
See Also: | move_file, rename_file