src/copy.h

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