27 Input/output library [input.output]

27.10 File systems [filesystems]

27.10.15 Filesystem operation functions [fs.op.funcs]

27.10.15.3 Copy [fs.op.copy]

void copy(const path& from, const path& to); void copy(const path& from, const path& to, error_code& ec) noexcept;

Effects: Equivalent to copy(from, to, copy_options::none) or copy(from, to, copy_options::none, ec), respectively.

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;

Requires: At most one constant from each option group ([enum.copy_options]) is present in options.

Effects: Before the first use of f and t:

  • 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).

  • Otherwise, if

    (options & copy_options::copy_symlinks) != copy_options::none
    

    then auto f = symlink_status(from) and if needed auto t = status(to).

  • Otherwise, auto f = status(from) and if needed auto t = status(to).

Effects are then as follows:

  • An error is reported as specified in [fs.err.report] if:

  • Otherwise, if is_symlink(f), then:

    • If (options & copy_options::skip_symlinks) != copy_options::none then return.

    • Otherwise if

      !exists(t) && (options & copy_options::copy_symlinks) != copy_options::none
      

      then copy_symlink(from, to).

    • Otherwise report an error as specified in [fs.err.report].

  • Otherwise, if is_regular_file(f), then:

    • If (options & copy_options::directories_only) != copy_options::none, then return.

    • Otherwise if (options & copy_options::create_symlinks) != copy_options::none, then create a symbolic link to the source file.

    • Otherwise if (options & copy_options::create_hard_links) != copy_options::none, then create a hard link to the source file.

    • Otherwise if is_directory(t), then copy_file(from, to/from.filename(), options).

    • Otherwise, copy_file(from, to, options).

  • Otherwise, if

    is_directory(f) &&
    ((options & copy_options::recursive) != copy_options::none ||
     options == copy_options::none)
    

    then:

    • If !exists(t), then create_directory(to, from).

    • Then, iterate over the files in from, as if by for (const directory_entry& x : directory_iterator(from)), and for each iteration

      copy(x.path(), to/x.path().filename(), options | copy_options::unspecified)
      
  • Otherwise, for the signature with argument ec, ec.clear().

  • Otherwise, no effects.

Throws: As specified in [fs.err.report].

Remarks: For the signature with argument ec, any library functions called by the implementation shall have an error_code argument if applicable.

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 ]