src/copy.h

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