src/copy.h

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