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