src/copy.h

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