bf(Copy_options):

hi(copy_options)
Defined in the tt((std::filesystem) enum class copy_options).

The enumeration supports bitwise operators.
The tt(copy_options) enum values are used to fine-tune the behavior of
tt(filesystem) functions copying file system elements.

    centertbl(lrll)(\
    tline()()\
    tr(xcell(4)(std::filesystem::copy_options))\
    tr(tlc()(Symbol) tlc()(Value) cell() tlc()(Meaning))\
    tline()()\
    threecols(none)(0)(default: copy like tt(cp))

    COMMENT(Files:)
    threecols(overwrite_existing)(2)(replace the destination file)
    threecols(update_existing)(4)(
            replace the destination file only if it is nl()
            older than the file being copied)

    COMMENT(Directories:)
    threecols(recursive)(8)(
        recursively copy subdirectories and their+nl()
        content)
    COMMENT(Symlinks:)
    threecols(copy_symlinks)(16)(copy symlinks as symlinks)
    threecols(skip_symlinks)(32)(ignore symlinks)

    COMMENT(copy itself)
    threecols(directories_only)(64)(
        copy the directory structure, but do not copy nl()
        any non-directory files)
    threecols(create_symlinks)(128)(
        create symlinks instead of copying files.nl() 
        The source path must be an absolute path unless nl()
        the destination path is in the current directory)
    threecols(create_hard_links)(256)(
        instead of copying files create hard links nl()
        resolving to the same files as the original)
    tline()()\
    )


bf(Functions):

    itemization(
    ithtq(absolute)(path absolute(path const &src,  [, error_code &ec]))
       (returns tt(src) as an absolute path (i.e., starting at the
        filesystem's root (and maybe disk) name). It can be called as, e.g.,
        tt(absolute("tmp/filename")), returning the (absolute) current working
        directory to which tt(absolute's) argument is appended as a final
        element, separated by a directory separator.  Relative path indicators
        (like tt(../) and tt(./)) are kept;)  

    ithtq(canonical)(path canonical(path const &src [, error_code &ec]))
       (returns tt(src's) canonical path. tt(Src) must exist. Example:
        verb(    canonical("/usr/local/bin/../../share/man");
     // returns path{ "/usr/share/man" } ))

    ithtq(copy)(void copy(path const &src, path const &dest [, copy_options
        opts [, error_code &ec]]))
       (tt(src) must exist. By default copies tt(src) to tt(dest) if the
            tt(cp) program would also succeed. Use tt(opts) to fine-tune
            tt(copy's) behavior.nl()
       If tt(src) is a directory, and tt(dest) does not exist, tt(dest) is
        created. Directories are recursively copied if copy options
        tt(recursive) or tt(none) were specified;)

    ithtq(copy_file)(bool copy_file(path const &src, path const &dest [,
        copy_options opts [, error_code &ec]]))
       (tt(src) must exist. Copies tt(src) to tt(dest) if the tt(cp) program
        would also succeed. Symbolic links are followed. The value tt(true) is
        returned if copying succeeded;)

    ithtq(copy_symlink)(void copy_symlink(path const &src, path const &dest [,
        error_code &ec]))
       (creates the symlink tt(dest) as a copy of the symlink tt(src);)

    ithtq(create_directories)(bool create_directories(path const &dest [,
        error_code &ec]))
       (creates each component of tt(dest), unless already existing. E.g.,
        using argument tt("a/b/c") and tt("a") doesn't yet exist then
        tt("a/b/c") are all created. The value tt(true) is returned if
        tt(dest) was actually created. If tt(false) is returned tt(ec)
        contains an error-code, which is zero (tt(ec.value() == 0)) if
        tt(dest) already existed. See also tt(create_directory) below;)

    ithtq(create_directory)(bool create_directory(path const &dest [, path
        const &existing] [, error_code &ec]))
       (tt(dest's) parent directory must exist. This function creates
        directory tt(dest) if it does not yet exist. Nested subdirectories are
        not created by tt(create_directory): using argument tt("a/b/c") and
        neither tt("a") nor tt("a/b") exist then this function fails. The
        value tt(true) is returned if tt(dest) was actually created. If
        tt(false) is returned tt(ec) contains an error-code, which is zero
        (tt(ec.value() == 0)) if tt(dest) already existed. If tt(existing) is
        specified, then tt(dest) receives the same attributes as
        tt(existing);)

    ithtq(create_directory_symlink)(void create_directory_symlink(path const
        &dir, path const &link [, error_code &ec]))
       (like tt(create_symlink) (see below), but is used to create a
        symbolic link to a directory;)

    ithtq(create_hard_link)(void create_hard_link(path const &dest, path const
        &link [, error_code &ec]))
       (creates a hard link from tt(link) to tt(dest). tt(Dest) must exist;)

    ithtq(create_symlink)(void create_symlink(path const &dest, path const
        &link [, error_code &ec]))
       (creates a symbolic (soft) link from tt(link) to tt(dest); tt(dest)
        does em(not) have to exist;)

    itht(current_path)(path current_path([error_code &ec])), tt(void
        current_path(path const &toPath [, error_code &ec])):nl()
       the former function returns the current working directory (cwd),
        the latter changes the cwd to tt(toPath). The returned path's last
        character is not a slash, unless called from the root-directory;

    ithtq(equivalent)(bool equivalent(path const &path1, path const &path2 [,
        error_code &ec]))
       (tt(true) is returned if tt(path1) and tt(path2) refer to the same file
        or directory, and have identical statuses. Both paths must exist;)

    itht(exists)(bool exists(path const &dest [, error_code &ec])),
        tt(exists(file_status status)):nl()
       tt(true) is returned if tt(dest) exists (actually: if
        tt(status(dest[, ec])) (see below) returns tt(true)). Note: when
        iterating over directories, the iterator usually provides the entries'
        statuses. In those cases calling tt(exists(iterator->status())) is
        more efficient than calling tt(exists(*iterator)). When tt(dest) is
        the path to a symbolic reference then tt(exists) returns whether the
        link's destination exists or not (see also the functions tt(status)
        and tt(symlink_status) in section ref(DIRENTRY));

    ithtq(file_size)(std::unintmax_t file_size(path const &dest [, error_code
        &ec]))
       (returns the size in bytes of a regular file (or symlink destination);)

    ithtq(hard_link_count)(std::uintmax_t hard_link_count(path const &dest [,
        error_code &ec]))
       (returns the number of hard links associated with tt(dest);)

    itht(last_write_time)(file_clock::time_point
        last_write_time(path const &dest [, error_code &ec])),
       tt(void last_write_time(path const &dest,
            file_clock::time_point newTime [, error_code &ec])):nl()
       the former function returns tt(dest's) last modification time;
        the latter function changes tt(dest's) last modification time to
        tt(newTime).
       tt(last_write_time's) return type is defined through a tt(using) alias
        for tt(chrono::time_point) (cf. section ref(TIMEPOINT)). The returned
        tt(time_point) is guaranteed to cover all file time values that may be
        encountered in the current file system. The function
        tt(file_clock::to_sys) (see below) can be used to convert
        tt(file_clock) time points to tt(system_clock) time_points;

    ithtq(permissions)(void permissions(Path const &entry, 
                perms newPerms [, perm_options opts = perm_options::replace ] 
                        [, error_code &ec]))
       (Modifies the permissions of tt(entry). Each of the two last arguments
        is optional. E.g., when specifying an tt(error_code) as third argument
        then tt(opts) is implicitly specified as tt(replace);)

    ithtq(read_symlink)(path read_symlink(path const &src [, error_code &ec]))
       (tt(src) must refer to a symbolic link or an error is generated. The
        link's target is returned;)

    itht(remove)(bool remove(path const &dest [, error_code &ec])),
        hi(remove_all) tt(std::uintmax_t remove_all(path const &dest [,
        error_code &ec])):nl()
       tt(remove) removes the file, symlink, or empty directory
        tt(dest), returning tt(true) if tt(dest) could be removed;
        tt(remove_all) removes tt(dest) if it's a file (or symlink); and
        recursively removes directory tt(dest), returning the number of
        removed entries;

    ithtq(rename)(void rename(path const &src, path const &dest [, error_code
        &ec]))
       (renames tt(src) to tt(dest), as if using the standard bf(mv)(1)
        command (if tt(dest) exists it is overwritten);)

    ithtq(resize_file)(void resize_file(path const &src, std::uintmax_t size [,
        error_code &ec]))
       (tt(src's) size is changed to tt(size) as if using the standard
        bf(truncate)(1) command;)

    ithtq(space)(space_info space(path const &src [, error_code &ec]))
       (returns information about the file system in which tt(src) is
        located;)

    ithtq(status)(file_status status(path const &entry [, error_code &ec]))
       (returns tt(entry's file_status). If tt(entry) is the name of a symbolic
        link then the status of the link's destination is returned;)

    ithtq(symlink_status)(file_status symlink_status(path const &entry [,
        error_code &ec])) 
       (returns tt(entry's) own tt(file_status);)

    ithtq(system_complete)(path system_complete(path const &src[, error_code&
        ec]))
       (returns the absolute path matching tt(src), using tt(current_path) as
        its base;)

    ithtq(temp_directory_path)(path temp_directory_path([error_code& ec]))
       ( returns the path to a directory that can be used for temporary
        files. The directory is not created, but its name is commonly
        available from the environment variables ti(TMPDIR), tt(TMP, TEMP), or
        tt(TEMPDIR). Otherwise, tt(/tmp) is returned.)

    ithtq(to_sys)(system_clock::time_point
        file_clock::to_sys(file_clock::time_point timePoint))
        (here is how
        the time returned by tt(last_write_time) can be represented using the
        tt(system_clock's) epoch:
            verbinsert(//demo examples/lastwritetime2.cc))
    )
