1 /* core functions for copying files and directories 2 Copyright (C) 1989-2023 Free Software Foundation, Inc. 3 4 This program is free software: you can redistribute it and/or modify 5 it under the terms of the GNU General Public License as published by 6 the Free Software Foundation, either version 3 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 GNU General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with this program. If not, see <https://www.gnu.org/licenses/>. */ 16 17 /* Extracted from cp.c and librarified by Jim Meyering. */ 18 19 #ifndef COPY_H 20 # define COPY_H 21 22 # include "hash.h" 23 24 struct selabel_handle; 25 26 /* Control creation of sparse files (files with holes). */ 27 enum Sparse_type 28 { 29 SPARSE_UNUSED, 30 31 /* Never create holes in DEST. */ 32 SPARSE_NEVER, 33 34 /* This is the default. Use a crude (and sometimes inaccurate) 35 heuristic to determine if SOURCE has holes. If so, try to create 36 holes in DEST. */ 37 SPARSE_AUTO, 38 39 /* For every sufficiently long sequence of bytes in SOURCE, try to 40 create a corresponding hole in DEST. There is a performance penalty 41 here because CP has to search for holes in SRC. But if the holes are 42 big enough, that penalty can be offset by the decrease in the amount 43 of data written to the file system. */ 44 SPARSE_ALWAYS 45 }; 46 47 /* Control creation of COW files. */ 48 enum Reflink_type 49 { 50 /* Do a standard copy. */ 51 REFLINK_NEVER, 52 53 /* Try a COW copy and fall back to a standard copy; this is the default. */ 54 REFLINK_AUTO, 55 56 /* Require a COW copy and fail if not available. */ 57 REFLINK_ALWAYS 58 }; 59 60 /* Control how existing destination files are updated. */ 61 enum Update_type 62 { 63 /* Always update.. */ 64 UPDATE_ALL, 65 66 /* Update if dest older. */ 67 UPDATE_OLDER, 68 69 /* Leave existing files. */ 70 UPDATE_NONE, 71 }; 72 73 /* This type is used to help mv (via copy.c) distinguish these cases. */ 74 enum Interactive 75 { 76 I_ALWAYS_YES = 1, 77 I_ALWAYS_NO, /* Skip and fail. */ 78 I_ALWAYS_SKIP, /* Skip and ignore. */ 79 I_ASK_USER, 80 I_UNSPECIFIED 81 }; 82 83 /* How to handle symbolic links. */ 84 enum Dereference_symlink 85 { 86 DEREF_UNDEFINED = 1, 87 88 /* Copy the symbolic link itself. -P */ 89 DEREF_NEVER, 90 91 /* If the symbolic is a command line argument, then copy 92 its referent. Otherwise, copy the symbolic link itself. -H */ 93 DEREF_COMMAND_LINE_ARGUMENTS, 94 95 /* Copy the referent of the symbolic link. -L */ 96 DEREF_ALWAYS 97 }; 98 99 # define VALID_SPARSE_MODE(Mode) \ 100 ((Mode) == SPARSE_NEVER \ 101 || (Mode) == SPARSE_AUTO \ 102 || (Mode) == SPARSE_ALWAYS) 103 104 # define VALID_REFLINK_MODE(Mode) \ 105 ((Mode) == REFLINK_NEVER \ 106 || (Mode) == REFLINK_AUTO \ 107 || (Mode) == REFLINK_ALWAYS) 108 109 /* These options control how files are copied by at least the 110 following programs: mv (when rename doesn't work), cp, install. 111 So, if you add a new member, be sure to initialize it in 112 mv.c, cp.c, and install.c. */ 113 struct cp_options 114 { 115 enum backup_type backup_type; 116 117 /* How to handle symlinks in the source. */ 118 enum Dereference_symlink dereference; 119 120 /* This value is used to determine whether to prompt before removing 121 each existing destination file. It works differently depending on 122 whether move_mode is set. See code/comments in copy.c. */ 123 enum Interactive interactive; 124 125 /* Control creation of sparse files. */ 126 enum Sparse_type sparse_mode; 127 128 /* Set the mode of the destination file to exactly this value 129 if SET_MODE is nonzero. */ 130 mode_t mode; 131 132 /* If true, copy all files except directories (and, if not dereferencing 133 them, symbolic links) as if they were regular files. */ 134 bool copy_as_regular; 135 136 /* If true, remove each existing destination nondirectory before 137 trying to open it. */ 138 bool unlink_dest_before_opening; 139 140 /* If true, first try to open each existing destination nondirectory, 141 then, if the open fails, unlink and try again. 142 This option must be set for 'cp -f', in case the destination file 143 exists when the open is attempted. It is irrelevant to 'mv' since 144 any destination is sure to be removed before the open. */ 145 bool unlink_dest_after_failed_open; 146 147 /* If true, create hard links instead of copying files. 148 Create destination directories as usual. */ 149 bool hard_link; 150 151 /* If MOVE_MODE, first try to rename. 152 If that fails and NO_COPY, fail instead of copying. */ 153 bool move_mode, no_copy; 154 155 /* If true, install(1) is the caller. */ 156 bool install_mode; 157 158 /* Whether this process has appropriate privileges to chown a file 159 whose owner is not the effective user ID. */ 160 bool chown_privileges; 161 162 /* Whether this process has appropriate privileges to do the 163 following operations on a file even when it is owned by some 164 other user: set the file's atime, mtime, mode, or ACL; remove or 165 rename an entry in the file even though it is a sticky directory, 166 or to mount on the file. */ 167 bool owner_privileges; 168 169 /* If true, when copying recursively, skip any subdirectories that are 170 on different file systems from the one we started on. */ 171 bool one_file_system; 172 173 /* If true, attempt to give the copies the original files' permissions, 174 owner, group, and timestamps. */ 175 bool preserve_ownership; 176 bool preserve_mode; 177 bool preserve_timestamps; 178 bool explicit_no_preserve_mode; 179 180 /* If non-null, attempt to set specified security context */ 181 struct selabel_handle *set_security_context; 182 183 /* Enabled for mv, and for cp by the --preserve=links option. 184 If true, attempt to preserve in the destination files any 185 logical hard links between the source files. If used with cp's 186 --no-dereference option, and copying two hard-linked files, 187 the two corresponding destination files will also be hard linked. 188 189 If used with cp's --dereference (-L) option, then, as that option implies, 190 hard links are *not* preserved. However, when copying a file F and 191 a symlink S to F, the resulting S and F in the destination directory 192 will be hard links to the same file (a copy of F). */ 193 bool preserve_links; 194 195 /* Optionally don't copy the data, either with CoW reflink files or 196 explicitly with the --attributes-only option. */ 197 bool data_copy_required; 198 199 /* If true and any of the above (for preserve) file attributes cannot 200 be applied to a destination file, treat it as a failure and return 201 nonzero immediately. E.g. for cp -p this must be true, for mv it 202 must be false. */ 203 bool require_preserve; 204 205 /* If true, attempt to preserve the SELinux security context, too. 206 Set this only if the kernel is SELinux enabled. */ 207 bool preserve_security_context; 208 209 /* Useful only when preserve_context is true. 210 If true, a failed attempt to preserve file's security context 211 propagates failure "out" to the caller, along with full diagnostics. 212 If false, a failure to preserve file's security context does not 213 change the invoking application's exit status, but may output diagnostics. 214 For example, with 'cp --preserve=context' this flag is "true", 215 while with 'cp --preserve=all' or 'cp -a', it is "false". */ 216 bool require_preserve_context; 217 218 /* If true, attempt to preserve extended attributes using libattr. 219 Ignored if coreutils are compiled without xattr support. */ 220 bool preserve_xattr; 221 222 /* Useful only when preserve_xattr is true. 223 If true, a failed attempt to preserve file's extended attributes 224 propagates failure "out" to the caller, along with full diagnostics. 225 If false, a failure to preserve file's extended attributes does not 226 change the invoking application's exit status, but may output diagnostics. 227 For example, with 'cp --preserve=xattr' this flag is "true", 228 while with 'cp --preserve=all' or 'cp -a', it is "false". */ 229 bool require_preserve_xattr; 230 231 /* This allows us to output warnings in cases 2 and 4 below, 232 while being quiet for case 1 (when reduce_diagnostics is true). 233 1. cp -a try to copy xattrs with no errors 234 2. cp --preserve=all copy xattrs with all but ENOTSUP warnings 235 3. cp --preserve=xattr,context copy xattrs with all errors 236 4. mv copy xattrs with all but ENOTSUP warnings 237 */ 238 bool reduce_diagnostics; 239 240 /* If true, copy directories recursively and copy special files 241 as themselves rather than copying their contents. */ 242 bool recursive; 243 244 /* If true, set file mode to value of MODE. Otherwise, 245 set it based on current umask modified by UMASK_KILL. */ 246 bool set_mode; 247 248 /* If true, create symbolic links instead of copying files. 249 Create destination directories as usual. */ 250 bool symbolic_link; 251 252 /* If true, do not copy a nondirectory that has an existing destination 253 with the same or newer modification time. */ 254 bool update; 255 256 /* If true, display the names of the files before copying them. */ 257 bool verbose; 258 259 /* If true, display details of how files were copied. */ 260 bool debug; 261 262 /* If true, stdin is a tty. */ 263 bool stdin_tty; 264 265 /* If true, open a dangling destination symlink when not in move_mode. 266 Otherwise, copy_reg gives a diagnostic (it refuses to write through 267 such a symlink) and returns false. */ 268 bool open_dangling_dest_symlink; 269 270 /* If true, this is the last filed to be copied. mv uses this to 271 avoid some unnecessary work. */ 272 bool last_file; 273 274 /* Zero if the source has already been renamed to the destination; a 275 positive errno number if this failed with the given errno; -1 if 276 no attempt has been made to rename. Always -1, except for mv. */ 277 int rename_errno; 278 279 /* Control creation of COW files. */ 280 enum Reflink_type reflink_mode; 281 282 /* This is a set of destination name/inode/dev triples. Each such triple 283 represents a file we have created corresponding to a source file name 284 that was specified on the command line. Use it to avoid clobbering 285 source files in commands like this: 286 rm -rf a b c; mkdir a b c; touch a/f b/f; mv a/f b/f c 287 For now, it protects only regular files when copying (i.e., not renaming). 288 When renaming, it protects all non-directories. 289 Use dest_info_init to initialize it, or set it to nullptr to disable 290 this feature. */ 291 Hash_table *dest_info; 292 293 /* FIXME */ 294 Hash_table *src_info; 295 }; 296 297 bool copy (char const *src_name, char const *dst_name, 298 int dst_dirfd, char const *dst_relname, 299 int nonexistent_dst, const struct cp_options *options, 300 bool *copy_into_self, bool *rename_succeeded) 301 _GL_ATTRIBUTE_NONNULL ((1, 2, 4, 6, 7)); 302 303 extern bool set_process_security_ctx (char const *src_name, 304 char const *dst_name, 305 mode_t mode, bool new_dst, 306 const struct cp_options *x) 307 _GL_ATTRIBUTE_NONNULL (); 308 309 extern bool set_file_security_ctx (char const *dst_name, 310 bool recurse, const struct cp_options *x) 311 _GL_ATTRIBUTE_NONNULL (); 312 313 void dest_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL (); 314 void dest_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL (); 315 void src_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL (); 316 void src_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL (); 317 318 void cp_options_default (struct cp_options *) _GL_ATTRIBUTE_NONNULL (); 319 bool chown_failure_ok (struct cp_options const *) 320 _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE; 321 mode_t cached_umask (void); 322 323 #endif 324