30 Input/output library [input.output]

30.10 File systems [filesystems]

30.10.34 Filesystem operation functions [fs.op.funcs]

30.10.34.3 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) noexcept;

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) noexcept;

3
#

Requires: 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), or

    • (4.5.2)

      equivalent(from, to), or

    • (4.5.3)

      is_­other(f) || is_­other(t), or

    • (4.5.4)

      is_­directory(f) && is_­regular_­file(t).

  • (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::recursive) != copy_options::none ||
 options == copy_options::none)

    then:

    • (4.8.1)

      If !exists(t), then create_­directory(to, from).

    • (4.8.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::unspecified)
  • (4.9)

    Otherwise, for the signature with argument ec, ec.clear().

  • (4.10)

    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: 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 ]