src/copy.h

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