aboutsummaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2020-01-19 11:02:00 +0200
committerSergey Poznyakoff <gray@gnu.org>2020-01-19 11:08:05 +0200
commitbfd076f64698d8985723547726cd6adb9b30eb67 (patch)
tree0cc0f43ce11d5b23fbc3975b415b2817394eb15e /lib
parente3d9037c37a934718c9bc8fb196006fa7c002ac0 (diff)
downloadfile-backup-bfd076f64698d8985723547726cd6adb9b30eb67.tar.gz
file-backup-bfd076f64698d8985723547726cd6adb9b30eb67.tar.bz2
Add documentation
Diffstat (limited to 'lib')
-rw-r--r--lib/File/Backup.pm117
1 files changed, 114 insertions, 3 deletions
diff --git a/lib/File/Backup.pm b/lib/File/Backup.pm
index 8aed3bb..2550bdf 100644
--- a/lib/File/Backup.pm
+++ b/lib/File/Backup.pm
@@ -2,11 +2,12 @@ package File::Backup;
use strict;
use warnings;
use File::Copy;
-use File::Temp qw(tempdir);
+use File::Temp;
use File::Basename;
use Exporter;
use re '/aa';
use Carp;
+use Errno;
our $VERSION = '1.00';
our @ISA = qw(Exporter);
@@ -71,8 +72,7 @@ sub backup_simple {
sub backup_numbered_opt {
my ($file_name, $if_exists) = @_;
- my $dir = tempdir(DIR => dirname($file_name), CLEANUP => 1);
- my $fh = File::Temp->new(DIR => $dir);
+ my $fh = File::Temp->new(DIR => dirname($file_name));
copy($file_name, $fh) or
croak "failed to make a temporary copy of $file_name: $!";
@@ -94,6 +94,9 @@ sub backup_numbered_opt {
while (1) {
$backup_name = "$file_name.~$num~";
last if symlink($fh->filename, $backup_name);
+ unless ($!{EEXIST}) {
+ croak "can't link ".$fh->filename." to $backup_name: $!";
+ }
++$num;
}
@@ -114,4 +117,112 @@ sub backup_auto {
}
1;
+__END__
+
+=head1 NAME
+
+File::Backup - create a backup of the file.
+
+=head1 SYNOPSIS
+
+ use File::Backup;
+
+ $backup_name = backup($file_name);
+
+ $backup_name = backup($file_name, BACKUP_NUMBERED);
+
+=head1 DESCRIPTION
+
+The File::Backup module provides functions for creating backup copies of
+files. Normally, the name of the backup copy is created by appending a
+single C<~> character to the original file name. This naming is called
+I<simple backup>. Another naming scheme is I<numbered backup>. In this
+scheme, the name of the backup is created by suffixing the original file
+name with C<.~I<N>~>, where I<N> is a decimal number starting with 1.
+In this backup naming scheme, the backup copies of file F<test> would be
+called F<test.~1~>, F<test.~2~> and so on.
+
+=head2 backup
+
+ $backup_name = backup($orig_name)
+
+ $backup_name = backup($orig_name, $scheme)
+
+The B<backup> function is the principal interface for managing backup
+copies. Its first argument specifies the name of the existing file for
+which a backup copy is required. Optional second argument controls the
+backup naming scheme. Its possible values are:
+
+=over 4
+
+=item BACKUP_NONE
+
+Don't create backup.
+
+=item BACKUP_SINGLE or BACKUP_SIMPLE
+
+Create simple backup (F<I<FILE>~>).
+
+=item BACKUP_NUMBERED
+
+Create numbered backup (F<I<FILE>.~B<N>~>).
+
+=item BACKUP_AUTO
+
+Automatic selection of the naming scheme. Create numbered backup if the
+file has numbered backups already. Otherwise, make simple backup.
+
+=back
+
+If the second argument is omitted, the function will consult the value of
+the environment variable B<VERSION_CONTROL>. Its possible values are:
+
+=over 4
+
+=item none, off
+
+Don't create any backups (B<BACKUP_NONE>).
+
+=item simple, never
+
+Create simple backups (B<BACKUP_SIMPLE>).
+
+=item numbered, t
+
+Create numbered backups (B<BACKUP_NUMBERED>).
+
+=item existing, nil
+
+Automatic selection of the naming scheme (B<BACKUP_AUTO>).
+
+=back
+
+If B<VERSION_CONTROL> is unset or set to any other value than those listed
+above, B<BACKUP_AUTO> is assumed.
+
+The function returns the name of the backup file it created (C<undef> if
+called with B<BACKUP_NONE>). On error, it calls B<croak()>.
+
+The following functions are provided for explicitly using a specific backup
+naming scheme:
+
+=head2 backup_simple
+
+ $backup_name = backup_simple($orig_name);
+
+Creates simple backup.
+
+=head2 backup_numbered
+ $backup_name = backup_numbered($orig_name);
+
+Creates numbered backup.
+
+=head2 backup_auto
+
+ $backup_name = backup_auto($orig_name);
+
+Creates numbered backup if any numbered backup version already exists for
+the file. Otherwise, creates simple backup.
+
+=cut

Return to:

Send suggestions and report system problems to the System administrator.