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   /* Enabled for mv, and for cp by the --preserve=links option.
 163      If true, attempt to preserve in the destination files any
 164      logical hard links between the source files.  If used with cp's
 165      --no-dereference option, and copying two hard-linked files,
 166      the two corresponding destination files will also be hard linked.
 167
 168      If used with cp's --dereference (-L) option, then, as that option implies,
 169      hard links are *not* preserved.  However, when copying a file F and
 170      a symlink S to F, the resulting S and F in the destination directory
 171      will be hard links to the same file (a copy of F).  */
 172   bool preserve_links;
 173
 174   /* Optionally don't copy the data, either with CoW reflink files or
 175      explicitly with the --attributes-only option.  */
 176   bool data_copy_required;
 177
 178   /* If true and any of the above (for preserve) file attributes cannot
 179      be applied to a destination file, treat it as a failure and return
 180      nonzero immediately.  E.g. for cp -p this must be true, for mv it
 181      must be false.  */
 182   bool require_preserve;
 183
 184   /* If true, attempt to preserve the SELinux security context, too.
 185      Set this only if the kernel is SELinux enabled.  */
 186   bool preserve_security_context;
 187
 188   /* Useful only when preserve_context is true.
 189      If true, a failed attempt to preserve file's security context
 190      propagates failure "out" to the caller, along with full diagnostics.
 191      If false, a failure to preserve file's security context does not
 192      change the invoking application's exit status, but may output diagnostics.
 193      For example, with 'cp --preserve=context' this flag is "true",
 194      while with 'cp --preserve=all' or 'cp -a', it is "false". */
 195   bool require_preserve_context;
 196
 197   /* If true, attempt to preserve extended attributes using libattr.
 198      Ignored if coreutils are compiled without xattr support. */
 199   bool preserve_xattr;
 200
 201   /* Useful only when preserve_xattr is true.
 202      If true, a failed attempt to preserve file's extended attributes
 203      propagates failure "out" to the caller, along with full diagnostics.
 204      If false, a failure to preserve file's extended attributes does not
 205      change the invoking application's exit status, but may output diagnostics.
 206      For example, with 'cp --preserve=xattr' this flag is "true",
 207      while with 'cp --preserve=all' or 'cp -a', it is "false". */
 208   bool require_preserve_xattr;
 209
 210   /* This allows us to output warnings in cases 2 and 4 below,
 211      while being quiet for case 1 (when reduce_diagnostics is true).
 212        1. cp -a                       try to copy xattrs with no errors
 213        2. cp --preserve=all           copy xattrs with all but ENOTSUP warnings
 214        3. cp --preserve=xattr,context copy xattrs with all errors
 215        4. mv                          copy xattrs with all but ENOTSUP warnings
 216    */
 217   bool reduce_diagnostics;
 218
 219   /* If true, copy directories recursively and copy special files
 220      as themselves rather than copying their contents. */
 221   bool recursive;
 222
 223   /* If true, set file mode to value of MODE.  Otherwise,
 224      set it based on current umask modified by UMASK_KILL.  */
 225   bool set_mode;
 226
 227   /* If true, create symbolic links instead of copying files.
 228      Create destination directories as usual. */
 229   bool symbolic_link;
 230
 231   /* If true, do not copy a nondirectory that has an existing destination
 232      with the same or newer modification time. */
 233   bool update;
 234
 235   /* If true, display the names of the files before copying them. */
 236   bool verbose;
 237
 238   /* If true, stdin is a tty.  */
 239   bool stdin_tty;
 240
 241   /* If true, open a dangling destination symlink when not in move_mode.
 242      Otherwise, copy_reg gives a diagnostic (it refuses to write through
 243      such a symlink) and returns false.  */
 244   bool open_dangling_dest_symlink;
 245
 246   /* Control creation of COW files.  */
 247   enum Reflink_type reflink_mode;
 248
 249   /* This is a set of destination name/inode/dev triples.  Each such triple
 250      represents a file we have created corresponding to a source file name
 251      that was specified on the command line.  Use it to avoid clobbering
 252      source files in commands like this:
 253        rm -rf a b c; mkdir a b c; touch a/f b/f; mv a/f b/f c
 254      For now, it protects only regular files when copying (i.e. not renaming).
 255      When renaming, it protects all non-directories.
 256      Use dest_info_init to initialize it, or set it to NULL to disable
 257      this feature.  */
 258   Hash_table *dest_info;
 259
 260   /* FIXME */
 261   Hash_table *src_info;
 262 };
 263
 264 # define XSTAT(X, Src_name, Src_sb) \
 265   ((X)->dereference == DEREF_NEVER \
 266    ? lstat (Src_name, Src_sb) \
 267    : stat (Src_name, Src_sb))
 268
 269 /* Arrange to make rename calls go through the wrapper function
 270    on systems with a rename function that fails for a source file name
 271    specified with a trailing slash.  */
 272 # if RENAME_TRAILING_SLASH_BUG
 273 int rpl_rename (const char *, const char *);
 274 #  undef rename
 275 #  define rename rpl_rename
 276 # endif
 277
 278 bool copy (char const *src_name, char const *dst_name,
 279            bool nonexistent_dst, const struct cp_options *options,
 280            bool *copy_into_self, bool *rename_succeeded);
 281
 282 void dest_info_init (struct cp_options *);
 283 void src_info_init (struct cp_options *);
 284
 285 void cp_options_default (struct cp_options *);
 286 bool chown_failure_ok (struct cp_options const *) _GL_ATTRIBUTE_PURE;
 287 mode_t cached_umask (void);
 288
 289 #endif