src/copy.h

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