src/copy.h

   1 /* core functions for copying files and directories
   2    Copyright (C) 1989-2024 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   /* Leave existing files, but exit failure if existing files.  */
  73   UPDATE_NONE_FAIL,
  74 };
  75
  76 /* This type is used to help mv (via copy.c) distinguish these cases.  */
  77 enum Interactive
  78 {
  79   I_ALWAYS_YES = 1,
  80   I_ALWAYS_NO,       /* Skip and fail.   */
  81   I_ALWAYS_SKIP,     /* Skip and ignore. */
  82   I_ASK_USER,
  83   I_UNSPECIFIED
  84 };
  85
  86 /* How to handle symbolic links.  */
  87 enum Dereference_symlink
  88 {
  89   DEREF_UNDEFINED = 1,
  90
  91   /* Copy the symbolic link itself.  -P  */
  92   DEREF_NEVER,
  93
  94   /* If the symbolic is a command line argument, then copy
  95      its referent.  Otherwise, copy the symbolic link itself.  -H  */
  96   DEREF_COMMAND_LINE_ARGUMENTS,
  97
  98   /* Copy the referent of the symbolic link.  -L  */
  99   DEREF_ALWAYS
 100 };
 101
 102 # define VALID_SPARSE_MODE(Mode)        \
 103   ((Mode) == SPARSE_NEVER               \
 104    || (Mode) == SPARSE_AUTO             \
 105    || (Mode) == SPARSE_ALWAYS)
 106
 107 # define VALID_REFLINK_MODE(Mode)       \
 108   ((Mode) == REFLINK_NEVER              \
 109    || (Mode) == REFLINK_AUTO            \
 110    || (Mode) == REFLINK_ALWAYS)
 111
 112 /* These options control how files are copied by at least the
 113    following programs: mv (when rename doesn't work), cp, install.
 114    So, if you add a new member, be sure to initialize it in
 115    mv.c, cp.c, and install.c.  */
 116 struct cp_options
 117 {
 118   enum backup_type backup_type;
 119
 120   /* How to handle symlinks in the source.  */
 121   enum Dereference_symlink dereference;
 122
 123   /* This value is used to determine whether to prompt before removing
 124      each existing destination file.  It works differently depending on
 125      whether move_mode is set.  See code/comments in copy.c.  */
 126   enum Interactive interactive;
 127
 128   /* Control creation of sparse files.  */
 129   enum Sparse_type sparse_mode;
 130
 131   /* Set the mode of the destination file to exactly this value
 132      if SET_MODE is nonzero.  */
 133   mode_t mode;
 134
 135   /* If true, copy all files except directories (and, if not dereferencing
 136      them, symbolic links) as if they were regular files.  */
 137   bool copy_as_regular;
 138
 139   /* If true, remove each existing destination nondirectory before
 140      trying to open it.  */
 141   bool unlink_dest_before_opening;
 142
 143   /* If true, first try to open each existing destination nondirectory,
 144      then, if the open fails, unlink and try again.
 145      This option must be set for 'cp -f', in case the destination file
 146      exists when the open is attempted.  It is irrelevant to 'mv' since
 147      any destination is sure to be removed before the open.  */
 148   bool unlink_dest_after_failed_open;
 149
 150   /* If true, create hard links instead of copying files.
 151      Create destination directories as usual. */
 152   bool hard_link;
 153
 154   /* If MOVE_MODE, first try to rename.
 155      If that fails and NO_COPY, fail instead of copying.  */
 156   bool move_mode, no_copy;
 157
 158   /* Exchange instead of renaming.  Valid only if MOVE_MODE and if
 159      BACKUP_TYPE == no_backups.  */
 160   bool exchange;
 161
 162   /* If true, install(1) is the caller.  */
 163   bool install_mode;
 164
 165   /* Whether this process has appropriate privileges to chown a file
 166      whose owner is not the effective user ID.  */
 167   bool chown_privileges;
 168
 169   /* Whether this process has appropriate privileges to do the
 170      following operations on a file even when it is owned by some
 171      other user: set the file's atime, mtime, mode, or ACL; remove or
 172      rename an entry in the file even though it is a sticky directory,
 173      or to mount on the file.  */
 174   bool owner_privileges;
 175
 176   /* If true, when copying recursively, skip any subdirectories that are
 177      on different file systems from the one we started on.  */
 178   bool one_file_system;
 179
 180   /* If true, attempt to give the copies the original files' permissions,
 181      owner, group, and timestamps. */
 182   bool preserve_ownership;
 183   bool preserve_mode;
 184   bool preserve_timestamps;
 185   bool explicit_no_preserve_mode;
 186
 187   /* If non-null, attempt to set specified security context */
 188   struct selabel_handle *set_security_context;
 189
 190   /* Enabled for mv, and for cp by the --preserve=links option.
 191      If true, attempt to preserve in the destination files any
 192      logical hard links between the source files.  If used with cp's
 193      --no-dereference option, and copying two hard-linked files,
 194      the two corresponding destination files will also be hard linked.
 195
 196      If used with cp's --dereference (-L) option, then, as that option implies,
 197      hard links are *not* preserved.  However, when copying a file F and
 198      a symlink S to F, the resulting S and F in the destination directory
 199      will be hard links to the same file (a copy of F).  */
 200   bool preserve_links;
 201
 202   /* Optionally don't copy the data, either with CoW reflink files or
 203      explicitly with the --attributes-only option.  */
 204   bool data_copy_required;
 205
 206   /* If true and any of the above (for preserve) file attributes cannot
 207      be applied to a destination file, treat it as a failure and return
 208      nonzero immediately.  E.g. for cp -p this must be true, for mv it
 209      must be false.  */
 210   bool require_preserve;
 211
 212   /* If true, attempt to preserve the SELinux security context, too.
 213      Set this only if the kernel is SELinux enabled.  */
 214   bool preserve_security_context;
 215
 216   /* Useful only when preserve_context is true.
 217      If true, a failed attempt to preserve file's security context
 218      propagates failure "out" to the caller, along with full diagnostics.
 219      If false, a failure to preserve file's security context does not
 220      change the invoking application's exit status, but may output diagnostics.
 221      For example, with 'cp --preserve=context' this flag is "true",
 222      while with 'cp --preserve=all' or 'cp -a', it is "false". */
 223   bool require_preserve_context;
 224
 225   /* If true, attempt to preserve extended attributes using libattr.
 226      Ignored if coreutils are compiled without xattr support. */
 227   bool preserve_xattr;
 228
 229   /* Useful only when preserve_xattr is true.
 230      If true, a failed attempt to preserve file's extended attributes
 231      propagates failure "out" to the caller, along with full diagnostics.
 232      If false, a failure to preserve file's extended attributes does not
 233      change the invoking application's exit status, but may output diagnostics.
 234      For example, with 'cp --preserve=xattr' this flag is "true",
 235      while with 'cp --preserve=all' or 'cp -a', it is "false". */
 236   bool require_preserve_xattr;
 237
 238   /* This allows us to output warnings in cases 2 and 4 below,
 239      while being quiet for case 1 (when reduce_diagnostics is true).
 240        1. cp -a                       try to copy xattrs with no errors
 241        2. cp --preserve=all           copy xattrs with all but ENOTSUP warnings
 242        3. cp --preserve=xattr,context copy xattrs with all errors
 243        4. mv                          copy xattrs with all but ENOTSUP warnings
 244    */
 245   bool reduce_diagnostics;
 246
 247   /* If true, copy directories recursively and copy special files
 248      as themselves rather than copying their contents. */
 249   bool recursive;
 250
 251   /* If true, set file mode to value of MODE.  Otherwise,
 252      set it based on current umask modified by UMASK_KILL.  */
 253   bool set_mode;
 254
 255   /* If true, create symbolic links instead of copying files.
 256      Create destination directories as usual. */
 257   bool symbolic_link;
 258
 259   /* If true, do not copy a nondirectory that has an existing destination
 260      with the same or newer modification time. */
 261   bool update;
 262
 263   /* If true, display the names of the files before copying them. */
 264   bool verbose;
 265
 266   /* If true, follow existing symlinks to directories when copying. */
 267   bool keep_directory_symlink;
 268
 269   /* If true, display details of how files were copied.  */
 270   bool debug;
 271
 272   /* If true, stdin is a tty.  */
 273   bool stdin_tty;
 274
 275   /* If true, open a dangling destination symlink when not in move_mode.
 276      Otherwise, copy_reg gives a diagnostic (it refuses to write through
 277      such a symlink) and returns false.  */
 278   bool open_dangling_dest_symlink;
 279
 280   /* If true, this is the last filed to be copied.  mv uses this to
 281      avoid some unnecessary work.  */
 282   bool last_file;
 283
 284   /* Zero if the source has already been renamed to the destination; a
 285      positive errno number if this failed with the given errno; -1 if
 286      no attempt has been made to rename.  Always -1, except for mv.  */
 287   int rename_errno;
 288
 289   /* Control creation of COW files.  */
 290   enum Reflink_type reflink_mode;
 291
 292   /* This is a set of destination name/inode/dev triples.  Each such triple
 293      represents a file we have created corresponding to a source file name
 294      that was specified on the command line.  Use it to avoid clobbering
 295      source files in commands like this:
 296        rm -rf a b c; mkdir a b c; touch a/f b/f; mv a/f b/f c
 297      For now, it protects only regular files when copying (i.e., not renaming).
 298      When renaming, it protects all non-directories.
 299      Use dest_info_init to initialize it, or set it to nullptr to disable
 300      this feature.  */
 301   Hash_table *dest_info;
 302
 303   /* FIXME */
 304   Hash_table *src_info;
 305 };
 306
 307 bool copy (char const *src_name, char const *dst_name,
 308            int dst_dirfd, char const *dst_relname,
 309            int nonexistent_dst, const struct cp_options *options,
 310            bool *copy_into_self, bool *rename_succeeded)
 311   _GL_ATTRIBUTE_NONNULL ((1, 2, 4, 6, 7));
 312
 313 extern bool set_process_security_ctx (char const *src_name,
 314                                       char const *dst_name,
 315                                       mode_t mode, bool new_dst,
 316                                       const struct cp_options *x)
 317   _GL_ATTRIBUTE_NONNULL ();
 318
 319 extern bool set_file_security_ctx (char const *dst_name,
 320                                    bool recurse, const struct cp_options *x)
 321   _GL_ATTRIBUTE_NONNULL ();
 322
 323 void dest_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
 324 void dest_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
 325 void src_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
 326 void src_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
 327
 328 void cp_options_default (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
 329 bool chown_failure_ok (struct cp_options const *)
 330   _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;
 331 mode_t cached_umask (void);
 332
 333 #endif