src/copy.h

   1 /* core functions for copying files and directories
   2    Copyright (C) 89, 90, 91, 1995-2007 Free Software Foundation.
   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   /* If true, copy all files except (directories and, if not dereferencing
  86      them, symbolic links,) as if they were regular files.  */
  87   bool copy_as_regular;
  88
  89   /* How to handle symlinks in the source.  */
  90   enum Dereference_symlink dereference;
  91
  92   /* If true, remove each existing destination nondirectory before
  93      trying to open it.  */
  94   bool unlink_dest_before_opening;
  95
  96   /* If true, first try to open each existing destination nondirectory,
  97      then, if the open fails, unlink and try again.
  98      This option must be set for `cp -f', in case the destination file
  99      exists when the open is attempted.  It is irrelevant to `mv' since
 100      any destination is sure to be removed before the open.  */
 101   bool unlink_dest_after_failed_open;
 102
 103   /* If true, create hard links instead of copying files.
 104      Create destination directories as usual. */
 105   bool hard_link;
 106
 107   /* This value is used to determine whether to prompt before removing
 108      each existing destination file.  It works differently depending on
 109      whether move_mode is set.  See code/comments in copy.c.  */
 110   enum Interactive interactive;
 111
 112   /* If true, rather than copying, first attempt to use rename.
 113      If that fails, then resort to copying.  */
 114   bool move_mode;
 115
 116   /* Whether this process has appropriate privileges to chown a file
 117      whose owner is not the effective user ID.  */
 118   bool chown_privileges;
 119
 120   /* If true, when copying recursively, skip any subdirectories that are
 121      on different file systems from the one we started on.  */
 122   bool one_file_system;
 123
 124   /* If true, attempt to give the copies the original files' permissions,
 125      owner, group, and timestamps. */
 126   bool preserve_ownership;
 127   bool preserve_mode;
 128   bool preserve_timestamps;
 129
 130   /* Enabled for mv, and for cp by the --preserve=links option.
 131      If true, attempt to preserve in the destination files any
 132      logical hard links between the source files.  If used with cp's
 133      --no-dereference option, and copying two hard-linked files,
 134      the two corresponding destination files will also be hard linked.
 135
 136      If used with cp's --dereference (-L) option, then, as that option implies,
 137      hard links are *not* preserved.  However, when copying a file F and
 138      a symlink S to F, the resulting S and F in the destination directory
 139      will be hard links to the same file (a copy of F).  */
 140   bool preserve_links;
 141
 142   /* If true and any of the above (for preserve) file attributes cannot
 143      be applied to a destination file, treat it as a failure and return
 144      nonzero immediately.  E.g. for cp -p this must be true, for mv it
 145      must be false.  */
 146   bool require_preserve;
 147
 148   /* If true, attempt to preserve the SELinux security context, too.
 149      Set this only if the kernel is SELinux enabled.  */
 150   bool preserve_security_context;
 151
 152   /* Useful only when preserve_security_context is true.
 153      If true, a failed attempt to preserve a file's security context
 154      propagates failure "out" to the caller.  If false, a failure to
 155      preserve a file's security context does not change the invoking
 156      application's exit status.  Give diagnostics for failed syscalls
 157      regardless of this setting.  For example, with "cp --preserve=context"
 158      this flag is "true", while with "cp -a", it is false.  That means
 159      "cp -a" attempts to preserve any security context, but does not
 160      fail if it is unable to do so.  */
 161   bool require_preserve_context;
 162
 163   /* If true, copy directories recursively and copy special files
 164      as themselves rather than copying their contents. */
 165   bool recursive;
 166
 167   /* If true, set file mode to value of MODE.  Otherwise,
 168      set it based on current umask modified by UMASK_KILL.  */
 169   bool set_mode;
 170
 171   /* Set the mode of the destination file to exactly this value
 172      if SET_MODE is nonzero.  */
 173   mode_t mode;
 174
 175   /* Control creation of sparse files.  */
 176   enum Sparse_type sparse_mode;
 177
 178   /* If true, create symbolic links instead of copying files.
 179      Create destination directories as usual. */
 180   bool symbolic_link;
 181
 182   /* If true, do not copy a nondirectory that has an existing destination
 183      with the same or newer modification time. */
 184   bool update;
 185
 186   /* If true, display the names of the files before copying them. */
 187   bool verbose;
 188
 189   /* If true, stdin is a tty.  */
 190   bool stdin_tty;
 191
 192   /* This is a set of destination name/inode/dev triples.  Each such triple
 193      represents a file we have created corresponding to a source file name
 194      that was specified on the command line.  Use it to avoid clobbering
 195      source files in commands like this:
 196        rm -rf a b c; mkdir a b c; touch a/f b/f; mv a/f b/f c
 197      For now, it protects only regular files when copying (i.e. not renaming).
 198      When renaming, it protects all non-directories.
 199      Use dest_info_init to initialize it, or set it to NULL to disable
 200      this feature.  */
 201   Hash_table *dest_info;
 202
 203   /* FIXME */
 204   Hash_table *src_info;
 205 };
 206
 207 # define XSTAT(X, Src_name, Src_sb) \
 208   ((X)->dereference == DEREF_NEVER \
 209    ? lstat (Src_name, Src_sb) \
 210    : stat (Src_name, Src_sb))
 211
 212 /* Arrange to make rename calls go through the wrapper function
 213    on systems with a rename function that fails for a source file name
 214    specified with a trailing slash.  */
 215 # if RENAME_TRAILING_SLASH_BUG
 216 int rpl_rename (const char *, const char *);
 217 #  undef rename
 218 #  define rename rpl_rename
 219 # endif
 220
 221 bool copy (char const *src_name, char const *dst_name,
 222            bool nonexistent_dst, const struct cp_options *options,
 223            bool *copy_into_self, bool *rename_succeeded);
 224
 225 void dest_info_init (struct cp_options *);
 226 void src_info_init (struct cp_options *);
 227
 228 bool chown_privileges (void);
 229 bool chown_failure_ok (struct cp_options const *);
 230 mode_t cached_umask (void);
 231
 232 #endif