29 Input/output library [input.output]

29.11 File systems [filesystems]

29.11.13 Filesystem operation functions [fs.op.funcs]

29.11.13.4 Copy [fs.op.copy]

🔗
void copy(const path& from, const path& to);
1
#
Effects: Equivalent to copy(from, to, copy_­options​::​none).
🔗
void copy(const path& from, const path& to, error_code& ec);
2
#
Effects: Equivalent to copy(from, to, copy_­options​::​none, ec).
🔗
void copy(const path& from, const path& to, copy_options options); void copy(const path& from, const path& to, copy_options options, error_code& ec);
3
#
Preconditions: At most one element from each option group ([fs.enum.copy.opts]) is set in options.
4
#
Effects: Before the first use of f and t:
  • (4.1)
    If (options & copy_options::create_symlinks) != copy_options::none || (options & copy_options::skip_symlinks) != copy_options::none then auto f = symlink_­status(from) and if needed auto t = symlink_­status(to).
  • (4.2)
    Otherwise, if (options & copy_options::copy_symlinks) != copy_options::none then auto f = symlink_­status(from) and if needed auto t = status(to).
  • (4.3)
    Otherwise, auto f = status(from) and if needed auto t = status(to).
Effects are then as follows:
  • (4.4)
    If f.type() or t.type() is an implementation-defined file type ([fs.enum.file.type]), then the effects are implementation-defined.
  • (4.5)
    Otherwise, an error is reported as specified in [fs.err.report] if:
    • (4.5.1)
      exists(f) is false, or
    • (4.5.2)
      equivalent(from, to) is true, or
    • (4.5.3)
      is_­other(f) || is_­other(t) is true, or
    • (4.5.4)
      is_­directory(f) && is_­regular_­file(t) is true.
  • (4.6)
    Otherwise, if is_­symlink(f), then:
    • (4.6.1)
      If (options & copy_­options​::​skip_­symlinks) != copy_­options​::​none then return.
    • (4.6.2)
      Otherwise if !exists(t) && (options & copy_options::copy_symlinks) != copy_options::none then copy_­symlink(from, to).
    • (4.6.3)
      Otherwise report an error as specified in [fs.err.report].
  • (4.7)
    Otherwise, if is_­regular_­file(f), then:
    • (4.7.1)
      If (options & copy_­options​::​directories_­only) != copy_­options​::​none, then return.
    • (4.7.2)
      Otherwise, if (options & copy_­options​::​create_­symlinks) != copy_­options​::​none, then create a symbolic link to the source file.
    • (4.7.3)
      Otherwise, if (options & copy_­options​::​create_­hard_­links) != copy_­options​::​none, then create a hard link to the source file.
    • (4.7.4)
      Otherwise, if is_­directory(t), then copy_­file(from, to/from.filename(), options).
    • (4.7.5)
      Otherwise, copy_­file(from, to, options).
  • (4.8)
    Otherwise, if is_directory(f) && (options & copy_options::create_symlinks) != copy_options::none then report an error with an error_­code argument equal to make_­error_­code(errc​::​is_­a_­directory).
  • (4.9)
    Otherwise, if is_directory(f) && ((options & copy_options::recursive) != copy_options::none || options == copy_options::none) then:
    • (4.9.1)
      If exists(t) is false, then create_­directory(to, from).
    • (4.9.2)
      Then, iterate over the files in from, as if by for (const directory_entry& x : directory_iterator(from)) copy(x.path(), to/x.path().filename(), options | copy_options::in-recursive-copy); where in-recursive-copy is a bitmask element of copy_­options that is not one of the elements in [fs.enum.copy.opts].
  • (4.10)
    Otherwise, for the signature with argument ec, ec.clear().
  • (4.11)
    Otherwise, no effects.
5
#
Throws: As specified in [fs.err.report].
6
#
Remarks: For the signature with argument ec, any library functions called by the implementation shall have an error_­code argument if applicable.
7
#
[Example 1:
Given this directory structure: 
/dir1
  file1
  file2
  dir2
    file3
Calling copy("/dir1", "/dir3") would result in: 
/dir1
  file1
  file2
  dir2
    file3
/dir3
  file1
  file2
Alternatively, calling copy("/dir1", "/dir3", copy_­options​::​recursive) would result in: 
/dir1
  file1
  file2
  dir2
    file3
/dir3
  file1
  file2
  dir2
    file3
— end example]