backup_copy

    $backup_name = backup_copy($orig_name);
    
    $backup_name = backup_copy($orig_name, $scheme);

    $backup_name = backup_copy($orig_name, %opts);

The backup_copy 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:

BACKUP_NONE

Don't create backup.

BACKUP_SINGLE or BACKUP_SIMPLE

Create simple backup (FILE~).

BACKUP_NUMBERED

Create numbered backup (FILE.~N~).

BACKUP_AUTO

Automatic selection of the naming scheme. Create numbered backup if the file has numbered backups already. Otherwise, make simple backup.

If the second argument is omitted, the function will consult the value of the environment variable VERSION_CONTROL. Its possible values are:

none, off

Don't create any backups (BACKUP_NONE).

simple, never

Create simple backups (BACKUP_SIMPLE).

numbered, t

Create numbered backups (BACKUP_NUMBERED).

existing, nil

Automatic selection of the naming scheme (BACKUP_AUTO).

If VERSION_CONTROL is unset or set to any other value than those listed above, BACKUP_AUTO is assumed.

The function returns the name of the backup file it created ("undef" if called with BACKUP_NONE). On error, it calls croak().

When used in the third form, the %opts are keyword arguments that control the function behavior. The following arguments are understood:

type => $scheme

Request a particular backup naming scheme. The following two calls are equivalent:

    backup_copy($file, type => BACKUP_SIMPLE)
    
    backup_copy($file, BACKUP_SIMPLE)
    

dir => $directory

Create backup files in $directory. The directory must exist and be writable.

By default backup files are created in the same directory as the original file.

error => $ref

This changes default error handling. Instead of croaking on error, the error message will be stored in $ref (which should be a reference to a scalar) and "undef" will be returned.

This can be used for an elaborate error handling and recovery, e.g.:

    $bname = backup_copy($file, \my $err);
    unless ($bname && defined($err)) {
        error("can't backup_copy file $file: $err");
        # perhaps more code follows
    }
    ...
    

The following functions are available for using a specific backup naming scheme. These functions must be exported explicitly.

backup_copy_simple

    use File::BackupCopy qw(backup_copy_simple);
    $backup_name = backup_copy_simple($orig_name, %opts);

Creates simple backup. Optional %opts have the same meaning as in backup_copy, except that, obviously, type keyword is not accepted.

backup_copy_numbered

    use File::BackupCopy qw(backup_copy_numbered);
    $backup_name = backup_copy_numbered($orig_name, %opts);

Creates numbered backup. See above for a description of %opts.

backup_copy_auto

    use File::BackupCopy qw(backup_copy_auto);
    $backup_name = backup_copy_auto($orig_name, %opts);

Creates numbered backup if any numbered backup version already exists for the file. Otherwise, creates simple backup.

Optional %opts have the same meaning as in backup_copy, except that, obviously, type keyword is not accepted.