NAME

File::Backup - create a backup of the file.

SYNOPSIS

    use File::Backup;

    $backup_name = backup($file_name);

    $backup_name = backup($file_name, BACKUP_NUMBERED);

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 ~ character to the original file name. This naming is called simple backup. Another naming scheme is numbered backup. In this scheme, the name of the backup is created by suffixing the original file name with .~N~, where N is a decimal number starting with 1. In this backup naming scheme, the backup copies of file test would be called test.~1~, test.~2~ and so on.

backup

    $backup_name = backup($orig_name)
    
    $backup_name = backup($orig_name, $scheme)

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

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().

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

backup_simple

    use File::Backup qw(backup_simple);
    $backup_name = backup_simple($orig_name);

Creates simple backup.

backup_numbered

    use File::Backup qw(backup_numbered);
    $backup_name = backup_numbered($orig_name);

Creates numbered backup.

backup_auto

    use File::Backup qw(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.