1 /* core functions for copying files and directories
2 Copyright (C) 1989-2023 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 <https://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 "hash.h"
23
24 struct selabel_handle;
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 the file system. */
44 SPARSE_ALWAYS
45 };
46
47 /* Control creation of COW files. */
48 enum Reflink_type
49 {
50 /* Do a standard copy. */
51 REFLINK_NEVER,
52
53 /* Try a COW copy and fall back to a standard copy; this is the default. */
54 REFLINK_AUTO,
55
56 /* Require a COW copy and fail if not available. */
57 REFLINK_ALWAYS
58 };
59
60 /* Control how existing destination files are updated. */
61 enum Update_type
62 {
63 /* Always update.. */
64 UPDATE_ALL,
65
66 /* Update if dest older. */
67 UPDATE_OLDER,
68
69 /* Leave existing files. */
70 UPDATE_NONE,
71 };
72
73 /* This type is used to help mv (via copy.c) distinguish these cases. */
74 enum Interactive
75 {
76 I_ALWAYS_YES = 1,
77 I_ALWAYS_NO, /* Skip and fail. */
78 I_ALWAYS_SKIP, /* Skip and ignore. */
79 I_ASK_USER,
80 I_UNSPECIFIED
81 };
82
83 /* How to handle symbolic links. */
84 enum Dereference_symlink
85 {
86 DEREF_UNDEFINED = 1,
87
88 /* Copy the symbolic link itself. -P */
89 DEREF_NEVER,
90
91 /* If the symbolic is a command line argument, then copy
92 its referent. Otherwise, copy the symbolic link itself. -H */
93 DEREF_COMMAND_LINE_ARGUMENTS,
94
95 /* Copy the referent of the symbolic link. -L */
96 DEREF_ALWAYS
97 };
98
99 # define VALID_SPARSE_MODE(Mode) \
100 ((Mode) == SPARSE_NEVER \
101 || (Mode) == SPARSE_AUTO \
102 || (Mode) == SPARSE_ALWAYS)
103
104 # define VALID_REFLINK_MODE(Mode) \
105 ((Mode) == REFLINK_NEVER \
106 || (Mode) == REFLINK_AUTO \
107 || (Mode) == REFLINK_ALWAYS)
108
109 /* These options control how files are copied by at least the
110 following programs: mv (when rename doesn't work), cp, install.
111 So, if you add a new member, be sure to initialize it in
112 mv.c, cp.c, and install.c. */
113 struct cp_options
114 {
115 enum backup_type backup_type;
116
117 /* How to handle symlinks in the source. */
118 enum Dereference_symlink dereference;
119
120 /* This value is used to determine whether to prompt before removing
121 each existing destination file. It works differently depending on
122 whether move_mode is set. See code/comments in copy.c. */
123 enum Interactive interactive;
124
125 /* Control creation of sparse files. */
126 enum Sparse_type sparse_mode;
127
128 /* Set the mode of the destination file to exactly this value
129 if SET_MODE is nonzero. */
130 mode_t mode;
131
132 /* If true, copy all files except (directories and, if not dereferencing
133 them, symbolic links,) as if they were regular files. */
134 bool copy_as_regular;
135
136 /* If true, remove each existing destination nondirectory before
137 trying to open it. */
138 bool unlink_dest_before_opening;
139
140 /* If true, first try to open each existing destination nondirectory,
141 then, if the open fails, unlink and try again.
142 This option must be set for 'cp -f', in case the destination file
143 exists when the open is attempted. It is irrelevant to 'mv' since
144 any destination is sure to be removed before the open. */
145 bool unlink_dest_after_failed_open;
146
147 /* If true, create hard links instead of copying files.
148 Create destination directories as usual. */
149 bool hard_link;
150
151 /* If MOVE_MODE, first try to rename.
152 If that fails and NO_COPY, fail instead of copying. */
153 bool move_mode, no_copy;
154
155 /* If true, install(1) is the caller. */
156 bool install_mode;
157
158 /* Whether this process has appropriate privileges to chown a file
159 whose owner is not the effective user ID. */
160 bool chown_privileges;
161
162 /* Whether this process has appropriate privileges to do the
163 following operations on a file even when it is owned by some
164 other user: set the file's atime, mtime, mode, or ACL; remove or
165 rename an entry in the file even though it is a sticky directory,
166 or to mount on the file. */
167 bool owner_privileges;
168
169 /* If true, when copying recursively, skip any subdirectories that are
170 on different file systems from the one we started on. */
171 bool one_file_system;
172
173 /* If true, attempt to give the copies the original files' permissions,
174 owner, group, and timestamps. */
175 bool preserve_ownership;
176 bool preserve_mode;
177 bool preserve_timestamps;
178 bool explicit_no_preserve_mode;
179
180 /* If non-null, attempt to set specified security context */
181 struct selabel_handle *set_security_context;
182
183 /* Enabled for mv, and for cp by the --preserve=links option.
184 If true, attempt to preserve in the destination files any
185 logical hard links between the source files. If used with cp's
186 --no-dereference option, and copying two hard-linked files,
187 the two corresponding destination files will also be hard linked.
188
189 If used with cp's --dereference (-L) option, then, as that option implies,
190 hard links are *not* preserved. However, when copying a file F and
191 a symlink S to F, the resulting S and F in the destination directory
192 will be hard links to the same file (a copy of F). */
193 bool preserve_links;
194
195 /* Optionally don't copy the data, either with CoW reflink files or
196 explicitly with the --attributes-only option. */
197 bool data_copy_required;
198
199 /* If true and any of the above (for preserve) file attributes cannot
200 be applied to a destination file, treat it as a failure and return
201 nonzero immediately. E.g. for cp -p this must be true, for mv it
202 must be false. */
203 bool require_preserve;
204
205 /* If true, attempt to preserve the SELinux security context, too.
206 Set this only if the kernel is SELinux enabled. */
207 bool preserve_security_context;
208
209 /* Useful only when preserve_context is true.
210 If true, a failed attempt to preserve file's security context
211 propagates failure "out" to the caller, along with full diagnostics.
212 If false, a failure to preserve file's security context does not
213 change the invoking application's exit status, but may output diagnostics.
214 For example, with 'cp --preserve=context' this flag is "true",
215 while with 'cp --preserve=all' or 'cp -a', it is "false". */
216 bool require_preserve_context;
217
218 /* If true, attempt to preserve extended attributes using libattr.
219 Ignored if coreutils are compiled without xattr support. */
220 bool preserve_xattr;
221
222 /* Useful only when preserve_xattr is true.
223 If true, a failed attempt to preserve file's extended attributes
224 propagates failure "out" to the caller, along with full diagnostics.
225 If false, a failure to preserve file's extended attributes does not
226 change the invoking application's exit status, but may output diagnostics.
227 For example, with 'cp --preserve=xattr' this flag is "true",
228 while with 'cp --preserve=all' or 'cp -a', it is "false". */
229 bool require_preserve_xattr;
230
231 /* This allows us to output warnings in cases 2 and 4 below,
232 while being quiet for case 1 (when reduce_diagnostics is true).
233 1. cp -a try to copy xattrs with no errors
234 2. cp --preserve=all copy xattrs with all but ENOTSUP warnings
235 3. cp --preserve=xattr,context copy xattrs with all errors
236 4. mv copy xattrs with all but ENOTSUP warnings
237 */
238 bool reduce_diagnostics;
239
240 /* If true, copy directories recursively and copy special files
241 as themselves rather than copying their contents. */
242 bool recursive;
243
244 /* If true, set file mode to value of MODE. Otherwise,
245 set it based on current umask modified by UMASK_KILL. */
246 bool set_mode;
247
248 /* If true, create symbolic links instead of copying files.
249 Create destination directories as usual. */
250 bool symbolic_link;
251
252 /* If true, do not copy a nondirectory that has an existing destination
253 with the same or newer modification time. */
254 bool update;
255
256 /* If true, display the names of the files before copying them. */
257 bool verbose;
258
259 /* If true, display details of how files were copied. */
260 bool debug;
261
262 /* If true, stdin is a tty. */
263 bool stdin_tty;
264
265 /* If true, open a dangling destination symlink when not in move_mode.
266 Otherwise, copy_reg gives a diagnostic (it refuses to write through
267 such a symlink) and returns false. */
268 bool open_dangling_dest_symlink;
269
270 /* If true, this is the last filed to be copied. mv uses this to
271 avoid some unnecessary work. */
272 bool last_file;
273
274 /* Zero if the source has already been renamed to the destination; a
275 positive errno number if this failed with the given errno; -1 if
276 no attempt has been made to rename. Always -1, except for mv. */
277 int rename_errno;
278
279 /* Control creation of COW files. */
280 enum Reflink_type reflink_mode;
281
282 /* This is a set of destination name/inode/dev triples. Each such triple
283 represents a file we have created corresponding to a source file name
284 that was specified on the command line. Use it to avoid clobbering
285 source files in commands like this:
286 rm -rf a b c; mkdir a b c; touch a/f b/f; mv a/f b/f c
287 For now, it protects only regular files when copying (i.e., not renaming).
288 When renaming, it protects all non-directories.
289 Use dest_info_init to initialize it, or set it to nullptr to disable
290 this feature. */
291 Hash_table *dest_info;
292
293 /* FIXME */
294 Hash_table *src_info;
295 };
296
297 /* Arrange to make rename calls go through the wrapper function
298 on systems with a rename function that fails for a source file name
299 specified with a trailing slash. */
300 # if RENAME_TRAILING_SLASH_BUG
301 int rpl_rename (char const *, char const *);
302 # undef rename
303 # define rename rpl_rename
304 # endif
305
306 bool copy (char const *src_name, char const *dst_name,
307 int dst_dirfd, char const *dst_relname,
308 int nonexistent_dst, const struct cp_options *options,
309 bool *copy_into_self, bool *rename_succeeded)
310 _GL_ATTRIBUTE_NONNULL ((1, 2, 4, 6, 7));
311
312 extern bool set_process_security_ctx (char const *src_name,
313 char const *dst_name,
314 mode_t mode, bool new_dst,
315 const struct cp_options *x)
316 _GL_ATTRIBUTE_NONNULL ();
317
318 extern bool set_file_security_ctx (char const *dst_name,
319 bool recurse, const struct cp_options *x)
320 _GL_ATTRIBUTE_NONNULL ();
321
322 void dest_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
323 void dest_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
324 void src_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
325 void src_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
326
327 void cp_options_default (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
328 bool chown_failure_ok (struct cp_options const *)
329 _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;
330 mode_t cached_umask (void);
331
332 #endif