1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-29 08:20:20 +02:00
guile/doc/ref
Tomas Volf e1690f3fd2
Add copy-on-write support to scm_copy_file.
On modern file-systems (BTRFS, ZFS) it is possible to copy a file using
copy-on-write method.  For large files it has the advantage of being
much faster and saving disk space (since identical extents are not
duplicated).  This feature is stable and for example coreutils' `cp'
does use it automatically (see --reflink).

This commit adds support for this feature into our copy-file procedure.
Same as `cp', it defaults to 'auto, meaning the copy-on-write is
attempted, and in case of failure the regular copy is performed.

No tests are provided, because the behavior depends on the system,
underlying file-system and its configuration.  That makes it challenging
to write a test for it.  Manual testing was performed instead:

    $ btrfs filesystem du /tmp/cow*
         Total   Exclusive  Set shared  Filename
      36.00KiB    36.00KiB       0.00B  /tmp/cow

    $ cat cow-test.scm
    (copy-file "/tmp/cow" "/tmp/cow-unspecified")
    (copy-file "/tmp/cow" "/tmp/cow-always" #:copy-on-write 'always)
    (copy-file "/tmp/cow" "/tmp/cow-auto" #:copy-on-write 'auto)
    (copy-file "/tmp/cow" "/tmp/cow-never" #:copy-on-write 'never)
    (copy-file "/tmp/cow" "/dev/shm/cow-unspecified")
    (copy-file "/tmp/cow" "/dev/shm/cow-auto" #:copy-on-write 'auto)
    (copy-file "/tmp/cow" "/dev/shm/cow-never" #:copy-on-write 'never)
    $ ./meta/guile -s cow-test.scm

    $ btrfs filesystem du /tmp/cow*
         Total   Exclusive  Set shared  Filename
      36.00KiB       0.00B    36.00KiB  /tmp/cow
      36.00KiB       0.00B    36.00KiB  /tmp/cow-always
      36.00KiB       0.00B    36.00KiB  /tmp/cow-auto
      36.00KiB    36.00KiB       0.00B  /tmp/cow-never
      36.00KiB       0.00B    36.00KiB  /tmp/cow-unspecified

    $ sha1sum /tmp/cow* /dev/shm/cow*
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /tmp/cow
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /tmp/cow-always
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /tmp/cow-auto
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /tmp/cow-never
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /tmp/cow-unspecified
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /dev/shm/cow-auto
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /dev/shm/cow-never
    4c665f87b5dc2e7d26279c4b48968d085e1ace32  /dev/shm/cow-unspecified

This commit also adds to new failure modes for (copy-file).

Failure to copy-on-write when 'always was passed in:

    scheme@(guile-user)> (copy-file "/tmp/cow" "/dev/shm/cow" #:copy-on-write 'always)
    ice-9/boot-9.scm:1676:22: In procedure raise-exception:
    In procedure copy-file: copy-on-write failed: Invalid cross-device link

Passing in invalid value for the #:copy-on-write keyword argument:

    scheme@(guile-user)> (copy-file "/tmp/cow" "/dev/shm/cow" #:copy-on-write 'nevr)
    ice-9/boot-9.scm:1676:22: In procedure raise-exception:
    In procedure copy-file: invalid value for #:copy-on-write: nevr

* NEWS: Add note for copy-file supporting copy-on-write.
* configure.ac: Check for linux/fs.h.
* doc/ref/posix.texi (File System)[copy-file]: Document the new
signature.
* libguile/filesys.c (clone_file): New function cloning a file using
FICLONE, if supported.
(k_copy_on_write): New keyword.
(sym_always, sym_auto, sym_never): New symbols.
(scm_copy_file2): Renamed from scm_copy_file.  New #:copy-on-write
keyword argument.  Attempt copy-on-write copy by default.
(scm_copy_file): Call scm_copy_file2.
* libguile/filesys.h: Add scm_copy_file2 as SCM_INTERNAL.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
2024-03-12 14:04:41 +01:00
..
.gitignore
api-binding.texi Document multiple-value returns in forms taking a let-expression body 2023-01-25 12:52:29 +01:00
api-control.texi Fix no-clause case-lambda in peval 2023-03-17 21:17:10 +01:00
api-coverage.texi doc: Fix typo in 'coverage-data->lcov' example. 2022-10-01 16:00:05 +02:00
api-data.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-debug.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-deprecated.texi
api-evaluation.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-foreign-objects.texi Remove SMOB tutorial; update manual. 2014-04-28 17:45:07 +02:00
api-foreign.texi Support C99 complex types in (system foreign) 2021-11-15 11:34:09 +01:00
api-i18n.texi Use "G_" as the conventional alias for gettext 2019-09-12 21:50:35 +02:00
api-init.texi
api-io.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-lalr.texi doc: Update LALR URL. 2018-08-07 11:33:06 +02:00
api-languages.texi Improve the documentation for 'nil?'. 2019-05-23 15:53:55 +02:00
api-macros.texi Fix example in syntax-rules doc 2023-09-28 12:11:10 +02:00
api-memory.texi Clarify use of the term "scanning" in the manual 2016-06-24 08:56:21 +02:00
api-modules.texi Minor typo in the manual 2023-11-28 11:18:05 +01:00
api-options.texi Update effective version to 3.0 2017-05-22 14:15:40 +02:00
api-overview.texi
api-peg.texi Fix minor typo in the PEG documentation. 2018-08-07 11:41:06 +02:00
api-procedures.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-regex.texi Doc: clarification on regexes and encodings 2023-01-17 07:20:10 +01:00
api-scheduling.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-scm.texi
api-smobs.texi Remove SMOB tutorial; update manual. 2014-04-28 17:45:07 +02:00
api-snarf.texi
api-undocumented.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
api-utility.texi Doc: document that eq?, eqv? and equal? take any number of arguments 2022-12-11 02:19:19 +01:00
api.txt
ChangeLog-2008
ChangeLog-goops-2008
ChangeLog-guile-doc-ref
compiler.texi doc: Fix typo under "CPS Soup". 2022-10-01 16:00:05 +02:00
curried.texi Document (ice-9 curried definitions) 2012-09-06 22:15:40 +01:00
data-rep.texi Spelling fixes 2018-10-21 14:54:38 +02:00
effective-version.texi.in
expect.texi
fdl.texi
gds.dia
gds.eps
gds.pdf
gds.txt
goops-tutorial.texi
goops.texi Document class redefinition change 2017-09-14 11:09:02 +02:00
guile-invoke.texi Bignums avoid both custom GMP allocator and finalizers 2022-01-13 09:37:17 +01:00
guile.texi Add copy-on-write support to scm_copy_file. 2024-03-12 14:04:41 +01:00
hierarchy.dot doc/ref/hierarchy.png: conform to hierarchy.txt and manual 2013-01-15 19:17:55 +01:00
hierarchy.eps doc/ref/hierarchy.png: conform to hierarchy.txt and manual 2013-01-15 19:17:55 +01:00
hierarchy.pdf doc/ref/hierarchy.png: conform to hierarchy.txt and manual 2013-01-15 19:17:55 +01:00
hierarchy.png doc/ref/hierarchy.png: conform to hierarchy.txt and manual 2013-01-15 19:17:55 +01:00
hierarchy.txt
history.texi doc: Lee Thomas suggested the name change. 2022-12-10 18:23:52 +01:00
indices.texi
intro.texi doc: Remove reference to “benevolent dictators”. 2024-01-24 11:12:06 +01:00
libguile-autoconf.texi
libguile-concepts.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00
libguile-extensions.texi
libguile-foreign-objects.texi doc: Fix typo. 2018-08-07 12:09:33 +02:00
libguile-linking.texi doc: embedding example more readable. 2014-01-17 22:22:02 +01:00
libguile-parallel.texi Replace libltdl with raw dlopen, dlsym 2021-02-03 23:02:21 +01:00
libguile-program.texi Review REFFIXME 2021-12-13 08:11:29 +01:00
libguile-snarf.texi Prefer foreign objects over smobs in manual 2014-04-28 18:00:05 +02:00
Makefile.am Add R7RS documentation and --r7rs command-line option 2019-11-17 15:30:59 +01:00
match.texi doc: Fix argument list in match-lambda docs 2019-06-24 15:24:33 +02:00
misc-modules.texi doc: Document how (ice-9 format) replaces 'format'. 2022-10-12 22:49:00 +02:00
mod-getopt-long.texi doc: fix documented keyword argument default to match code default 2022-12-21 08:29:42 +01:00
mop.text
new-docstrings.texi
posix.texi Add copy-on-write support to scm_copy_file. 2024-03-12 14:04:41 +01:00
preface.texi doc: Use gender-neutral language in Preface 2020-01-20 10:23:33 +01:00
r6rs.texi Implement R6RS custom textual ports 2023-06-08 10:21:02 +02:00
r7rs.texi Document R7RS functions related to bytevectors 2023-01-17 16:07:48 +01:00
repl-modules.texi readline: Avoid interpreting control characters in pastes. 2017-05-17 22:29:08 +02:00
scheme-ideas.texi Update documentation for mixed definitions and expressions 2019-08-25 17:05:38 +02:00
scheme-indices.texi
scheme-intro.texi Add R7RS documentation and --r7rs command-line option 2019-11-17 15:30:59 +01:00
scheme-reading.texi
scheme-scripts.texi Fix scheme-scripts markup. 2017-03-01 21:44:53 +01:00
scheme-using.texi doc: Mention (ice-9 time) module path. 2020-06-18 00:30:30 +02:00
scheme.dia
scheme.eps
scheme.pdf
scheme.txt
scsh.texi
slib.texi
srfi-modules.texi bug#68507: [PATCH] doc: Fix example in list-transduce example. 2024-01-24 11:14:10 +01:00
statprof.texi Check for working profiling and virtual itimers 2017-03-06 23:06:12 -08:00
sxml-match.texi doc: Replace square brackets with round brackets. 2020-03-25 22:50:26 +01:00
sxml.texi doc: Clarify reference to (sxml transform) module. 2022-10-01 16:00:05 +02:00
texinfo.texi texinfo: Add '*line-width*' fluid to control line wrapping. 2020-01-29 15:19:37 +01:00
tools.texi Prefer foreign objects over smobs in manual 2014-04-28 18:00:05 +02:00
tour.texi Replace libltdl with raw dlopen, dlsym 2021-02-03 23:02:21 +01:00
vm.texi Better compilation of calls to raise-exception 2023-08-28 12:11:19 +02:00
web.texi Fix typos throughout codebase. 2023-07-16 22:09:01 +02:00