restore command

Purpose

Extracts files from archives created with the backup command.

Syntax

To restore files archived by file name:

restore -x [ d M n Q v q e ] [ -b Number ] [ -f Device ] [ -s SeekBackup ] [ -E { force | ignore | warn } ] [ File ... ]

To list files archived by file name:

restore -T | -t [a l n q v Q ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]

To restore files archived by file system:

restore -r [ B n q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]
restore -R [ B n v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]
restore -i [ h m n q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ]
restore -x [ B h n m q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ] [ File ... ]

To restore files beginning at a specified volume number:

restore -X Number [ -Md n q v e Q ] [ -b Number ] [ -f Device ] [ -s Number ] [ -E { force | ignore | warn } ] [ File ... ]

To list files archived by file system:

restore -t | -T [ B a l n h q v y ] [ -b Number ] [ -f Device ] [ -s SeekBackup ] [ File ... ]

To restore file attributes archived by file name:

restore -Pstring [B d q v Q ] [ b Number] [ s SeekNumber ] [-f Device ] [ File ... ]

To restore file attributes archived by file system:

restore -Pstring [ h q v] [ b Number] [ s SeekNumber ] [-f Device] [ File ... ]

Description

The restore command reads archives created by the backup operation and extracts the files stored on them. These archives can be in either file name or file system format. An archive can be stored on disk, diskette, or tape. Files must be restored using the same method by which they were archived. This requires that you know the format of the archive. The archive format can be determined by examining the archive volume header information that is displayed when using the -T flag. When using the -x, -r, -T, or -t flags, the restore command automatically determines the archive format.

Note: The restore command determines the actively sparses files that are being restored. If a file has block aligned and sized areas that are NULL populated, then the restore command does not cause physical space for those file system blocks to be allocated. The size in bytes of the file remain the same, but the actual space taken within the file system is only for the non-NULL areas.

Individual files can be restored from either file name or file system archives by using the -x flag and specifying the file name. The file name must be specified as it exists on the archive. Files can be restored interactively from file system archives using the -i flag. The names of the files on an archive can be written to standard output using the -T flag.

Users must have write access to the file system device or have restore authorization in order to extract the contents of the archive.

The diskette device, /dev/rfd0, is the default media for the restore command. To restore from standard input, specify a dash (-) with the -f flag. You can also specify a range of devices, such as /dev/rmt0-2.

Note:

If you are restoring from a multiple-volume archive, the restore command reads the volume mounted, prompts you for the next volume, and waits for your response. After inserting the next volume, press the Enter key to continue restoring files.
If an archive was created using the backup command and was made to a tape device with the device block size set to 0, it might be necessary for you to have explicit knowledge of the block size that was used when the tape was created to restore from the tape.
Multiple archives can exist on a single tape. When you are restoring multiple archives from tape, the restore command expects the input device to be a no-retension-on-open, no-rewind-on-close tape device. Do not use a no-rewind tape device for restoring unless the -B, -s, or -X flag is specified.

File system archives

File system archives are also known as i-node archives due to the method used to archive the files. A file system name is specified with the backup command, and the files within that file system are archived based on their structure and layout within the file system. The restore command restores the files on a file system archive without any special understanding of the underlying structure of the file system.

When restoring file system archives, the restore command creates and uses a file named restoresymtable. This file is created in the current directory. The file is necessary for the restore command to do incremental file system restore operation.

Note: Do not remove the restoresymtable file if you perform incremental file system backups and restores.

The File parameter is ignored when using either the -r or the -R flag.

File-name archives

File-name archives are created by specifying a list of file names to archive by using the backup command. The restore operation restores the files from a file name archive without any special understanding of the underlying structure of the file system. The restore operation allows for metacharacters to be used when specifying files for archive extraction. This provides the capability to extract files from an archive based on pattern matching. A pattern file name should be enclosed in single quotations, and patterns should be enclosed in parentheses (...).

About sparse files

File system files for the operating system that contain long strings of NULLs can be stored much more efficiently than other files. To be specific, if a string of NULLs spans an entire allocation block, that whole block is not stored on disk at all. Files where one or more blocks are omitted in this way are called sparse files. The missing blocks are also known as holes.

Note: Sparse files are not the same as compressed files. Sparse files are exactly the same as their nonsparse equivalents when they are read.

Sparse files are generally created by database applications. Whenever a database file is created, it is formatted with NULLs. These fragments might be either filled with allocated or unallocated NULLs.

Flags

Flag name	Description
-a	Displays the -a option displays the list of files in the archive, along with their permissions when specified with the -t or -T flag.
-B	Specifies that the archive should be read from standard input. Normally, the restore operation examines the actual medium to determine the backup format. When using a `\|` (pipe), this examination cannot occur. As a result, the archive is assumed to be in file system format, and the device is assumed to be standard input (-f -).
-b Number	For backups done by name, specifies the number of 512-byte blocks. For backups done by i-node, specifies the number of 1024-byte blocks to read in a single output operation. When the restore operation reads from tape devices, the default is 100 for backups by name and 32 for backups by i-node. The read size is the number of blocks multiplied by the block size. The default read size for the restore operation reading from tape devices is 51200 (100 × 512) for backups by name and 32768 (32 × 1024) for backups by i-node. The read size must be an even multiple of the tape's physical block size. If the read size is not an even multiple of the tape's physical block size and it is in fixed block mode (nonzero), the restore command tries to determine a valid value for Number. If successful, the restore operation changes Number to the new value, writes a message about the change to standard output, and continues. If unsuccessful in finding a valid value for Number, the restore operation writes an error message to standard error and exits with a nonzero return code. Larger values for the Number parameter result in larger physical transfers from the tape device. The value of the -b flag is always ignored when the restore command reads from diskette. In this case, the command always reads in clusters that occupy a complete track.
-d	Indicates that, if the File parameter is a directory, all files in that directory should be restored. This flag can only be used when the archive is in file name format.
-e	Restores the nonsparse files because they were archived by the name format of the backup operation for both packed and unpacked files. It is necessary to know the sparseness or nonsparseness of the files before archiving the files, since enabling this flag restores the sparse files as nonsparse. This flag should be enabled only if the files being restored are nonsparsed, consisting of more than 4K NULLs. If the -e flag is specified during the restore opeation, it successfully restores all normal files normally and nonsparse database files as nonsparse.
-E	Extracts beginning at a specified volume number and requires one of the following arguments. If you omit the -E flag, warn is the default behavior. force Fails the restore operation on a file if the fixed extent size or space reservation of the file cannot be preserved. ignore Ignores any errors in preserving extent attributes. warn Issues a warning if the space reservation or the fixed size of the file cannot be preserved.
-f Device	Specifies the input device. To receive input from a named device, specify the Device variable as a path name (such as `/dev/rmt0`). To receive input from the standard output device, specify a dash (`-`) You can also specify a range of archive devices. The range specification must be in the following format: `/dev/deviceXXX-YYY` where `XXX` and `YYY` are whole numbers, and `XXX` must always be less than `YYY`; for example: `/dev/rfd0-3` All devices in the specified range must be of the same type. For example, you can use a set of 8 mm, 2.3 GB tapes or a set of 1.44 MB diskettes. All tape devices must be set to the same physical tape block size. If the Device variable specifies a range, the restore operation automatically goes from one device in the range to the next. After exhausting all of the specified devices, the restore operation halts and requests that new volumes be mounted on the range of devices.
-h	Restores only the actual directory, not the files contained in it. This flag can only be used when the archive is in file system format. This flag is ignored when used with the -r or -R flag.
-i	Allows you to interactively restore selected files from a file system archive. The subcommands for the -i flag are: add [File]: Specifies that the File parameter is added to the list of files to extract. If File is a directory, that directory and all the files contained in it are added to the extraction list (unless the -h flag is used). If File is not specified, the current directory is added to the extraction list. cd Directory: Changes the current directory to the specified directory. delete [File]: Specifies that the File parameter is to be removed from the list of files to be extracted. If File is a directory, that directory and all the files contained in it are removed from the extraction list (unless the -h flag is used). extract: Restores all the directories and files on the extraction list. help: Displays a summary of the subcommands. ls [Directory]: Displays the directories and files contained within the Directory parameter. Directory names are displayed with a slash (/) after the name. Files and directories, within the specified directory, that are on the extraction list are displayed with an asterick (``) before the name. If verbose mode is on, the i-node number of the files and directories is also displayed. If the Directory* parameter is not specified, the current directory is used . pwd: Displays the full path name of the current directory. quit: Causes the restore operation to exit immediately. Any files on the extraction list are not restored. setmodes: Sets the owner, mode, and time for all directories added to the extraction list. verbose: Causes the ls subcommand to display the i-node number of files and directories. Additional information about each file is also displayed as it is extracted from the archive.
-l	Displays a detailed list of files, which includes the time stamp, file permissions, file size, owner, and group when specified with the -t or -T flag.. The -l option overrides the -a option.
-M	Sets the access and modification times of restored files to the time of restoration. You can specify the -M flag only when you are restoring individually named files and only if the -x or -X flags are also specified. When the -M flag is not specified, the restore operation maintains the access and modification times as they appear on the backup medium.
-m	Renames restored files to the file's i-node number as it exists on the archive. This is useful if a few files are being restored and you want these files restored under a different file name. Since any restored archive members are renamed to their i-node numbers, directory hierarchies and links are not preserved. Directories and hard links are restored as regular files. The -m flag is used when the archive is in file system format.
-n	By default the restore operation restores any Access Control List (ACL)s, Printing Color Files (PCL)s, or named extended attributes in the archive. The -n flag causes the restore operation to skip over any ACLs, PCLs, or named extended attributes in the archive and not restore them.
-Pstring	Restore only the file attributes. This flag does not restore the file contents. If the file specified does not exist in the target directory path, the file is not created. This flag restores file attributes selectively depending on the flags specified in the string parameter. The String parameter can be a combination of the following characters: A Restore all attributes. a Restore only the permissions of the files. o Restore only the ownership of the files. t Restore only the time stamp of the files. c Restore only the ACL attributes of the files Note: Among the existing flags for the restore command, flags v, h, b, s, f, B, d, and q are valid with the P flag. The P flag can be used with both file name and file system archives. If the File parameter is a symbolic link, then the metadata of the target file is modified and not that of the symbolic link. Attention: Usage of -P flag overwrites the attributes of files owned by another user when run by the superuser.
-Q	For backups done by name, specifies that the command should exit upon encountering any type of error rather than attempt to recover and continue processing the archive.
-q	Specifies that the first volume is ready to use and that the restore operation should not prompt you to `mount the volume` and press Enter. If the archive spans multiple volumes, the restore command prompts you for the subsequent volumes.
-r	Restores all files in a file system archive. The -r flag is only used to restore complete level 0 backups or to restore incremental backups after a level 0 backup is restored. The `restoresymtable` file is used by the restore operation to pass information between incremental restore operations. This file should be removed after the last incremental backup is restored. The File parameter is ignored when using the -r flag.
-R	Requests a specific volume of a multiple-volume, file system archive. The -R flag allows a previously interrupted restore operation to be restarted. The File parameter is ignored when using the -R flag. Once restarted, the restore command behavior is the same as with the -r flag.
-s SeekBackup	Specifies the backup to seek and restore on a multiple-backup tape archive. The -s flag is only applicable when the archive is written to a tape device. To use the -s flag properly, a no-rewind-on-close and no-retension-on-open tape device, such as `/dev/rmt0.1` or `/dev/rmt0.5`, must be specified. If the -s flag is specified with a rewind tape device, the restore command displays an error message and exits with a nonzero return code. If a no-rewind tape device is used and the -s flag is not specified, a default value of -s 1 is used. The value of the SeekBackup parameter must be in the range of 1 to 100 inclusive. It is necessary to use a no-rewind-on-close, no-retension-on-open tape device because of the behavior of the -s flag. The value specified with -s is relative to the position of the tape's read/write head and not to an archive's position on the tape. For example, to restore the first, second, and fourth backups from a multiple-backup tape archive, the respective values for the -s flag would be -s 1, -s 1, and -s 2.
-t	Displays information about the backup archive. If the archive is in file system format, a list of files found on the archive is written to standard output. The name of each file is preceded by the i-node number of the file as it exists on the archive. The file names displayed are relative to the root (`/`) directory of the file system that was backed up. If the File parameter is not specified, all the files on the archive are listed. If the File parameter is used, then just that file is listed. If the File parameter refers to a directory, all the files contained in that directory are listed. If the archive is in file name format, information contained in the volume header is written to standard error. This flag can be used to determine if the archive is in file name or file system format.
-T	Displays information about the backup archive. If the archive is in file name format, the information contained in the volume header is written to standard error, and a list of files found on the archive is written to standard output. The File parameter is ignored for file name archives. If the archive is in file system format, the behavior is identical to the -t flag.
-v	Displays additional information when restoring. If the archive is in file name format and either the -x or -T flag is specified, the size of the file as it exists on the archive is displayed in bytes. Directory, block, or character device files are archived with a size of 0. Symbolic links are listed with the size of the symbolic link. Hard links are listed with the size of the file, which is how they are archived. Once the archive is read, a total of these sizes is displayed. If the archive is in file system format, directory and nondirectory archive members are distinguished.
-x	Restores individually named files specified by the File parameter. If the File parameter is not specified, all the archive members are restored. If the File parameter is a directory and the archive is in file name format, only the directory is restored. If the File parameter is a directory and the archive is in file system format, all the files contained in the directory are restored. The file names specified by the File parameter must be the same as the names shown by the restore -T flag. Files are restored with the same name they were archived with. If the file name was archived using a relative path name (./filename), the file is restored relative to the current directory. If the archive is in file system format, files are restored relative to the current directory. The restore command automatically creates any needed directories. When using this flag to restore file system backups, you are prompted to enter the beginning volume number. The restore command allows for shell-style pattern matching metacharacters to be used when specifying files for archive extraction. The rules for matching metacharacters are the same as those used in shell pathname "globbing," namely: asterick* (`*` ) Matches zero or more characters, but not a `.` (period) or `/` (slash). question mark (?) Matches any single character, but not a `.` (period) or `/` (slash). brackets ([ ]) Matches any one of the characters enclosed within the brackets. If a pair of characters separated by a dash are contained within the brackets, the pattern matches any character that lexically falls between the two characters in the current local. Additionally, a `.` (period) or a `/` (slash) within the brackets will not match a `.` (period) or a `/` (slash) in a file name. backslash (\) Matches the immediately following character, preventing its possible interpretation as a metacharacter.
-X VolumeNumber	Begins restoring from the specified volume of a multiple-volume, file name backup. Once started, the restore command behavior is the same as with the -x flag. The -X flag applies only to file name archives.
-y	Continues restoring when tape errors are encountered. Normally, the restore command asks you whether or not to continue. In either case, all data in the read buffer is replaced with zeros. The -y flag applies only when the archive is in file system format.
?	Displays a usage message.

Exit Status

This command returns the following exit values:

Return code	Description
0	Successful completion.
>0	An error occurred.

Examples

To list the names of files in either a file name or file system archive on diskette device /dev/rfd0, type the following command:
```
restore -Tq
```
The archive is read from the /dev/rfd0 default restore device. The names of all the files and directories contained in the archive are displayed. For file system archives, the file name is preceded by the i-node number of the file as it exists on the archive. The -q flag tells the restore command that the first volume is available and is ready to be read. As a result, you are not prompted to mount the first volume.
To restore a specific file, type the following command:
```
restore -xvqf myhome.bkup system.data
```
This command extracts the file system.data into the current directory from the archive myhome.bkup. The archive in this example is in the current directory. File and directory names must be specified as they are displayed when using the -T flag. The -v flag displays additional information during the extraction. This example applies to both file name and file system archives.
To restore a specific file from tape into the virtual media repository, type the following command:
```
restore -xvqf /dev/rmt0 /var/vio/VMLibrary/media_file
```
To restore a specific directory and the contents of that directory from a file name archive, type the following command:
```
restore -xdvqf /dev/rmt0 /home/mike/tools
```
The -x flag extracts files by their file name. The -d flag tells the restore command to extract all the files and subdirectories in the /home/mike/tools directory. File and directory names must be specified as they are displayed when using the -T flag. If the directories do not exist, they are created.
To restore a specific directory and the contents of that directory from a file system archive, type the following command:
```
restore -xvqf /dev/rmt0 /home/mike/tools 
```
This command extracts files by file name. File and directory names must be specified as they are displayed when using the -T flag. If the directories do not exist, they are created.
To restore an entire file system archive, type the following command:
```
restore -rvqf /dev/rmt0
```
This command restores the entire file system archived on tape device /dev/rmt0 the current directory. This example assumes you are in the root directory of the file system to be restored. If the archive is part of a set of incremental file system archives, the archives should be restored in increasing backup-level order beginning with level 0 (for example, 0, 1, 2).
To restore the fifth and ninth backups from a single-volume, multiple-backup tape, type the following command:
```
restore -xvqs 5 -f/dev/rmt0.1 
restore -xvqs 4 -f/dev/rmt0.1
```
The first command extracts all files from the fifth archive on the multiple-backup tape specified by /dev/rmt0.1. The .1 designator specifies that the tape device will not be retensioned when it is opened and that it will not be rewound when it is closed. It is necessary to use a no-rewind-on-close, no-retension-on-open tape device because of the behavior of the -s flag. The second command extracts all the files from the fourth archive (relative to the current location of the tape head on the tape). After the fifth archive has been restored, the tape read/write head is in a position to read the archive. Since you want to extract the ninth archive on the tape, you must specify a value of 4 with the -s flag. This is because the -s flag is relative to your position on the tape and not to an archive's position on the tape. The ninth archive is the fourth archive from your current position on the tape.
To restore the fourth backup, which begins on the sixth tape on a 10-tape multiple-backup archive, put the sixth tape into the tape drive and type the following command:
```
restore -xcs 2 -f /dev/rmt0.1 /home/mike/manual/chap3
```
Assuming the fourth backup is the second backup on the sixth tape, specifying -s 2 advances the tape head to the beginning of the second backup on this tape. The restore command then restores the specified file from the archive. If the backup continues onto subsequent volumes and the file has not been restored, the restore command instructs you to insert the next volume until the end of the backup is reached. The -f flag specifies the no-rewind, no-retension tape device name.
Note: The -s flag specifies the backup number relative to the tape inserted in the tape drive, not to the overall 10-tape archive.
To improve the performance on streaming tape devices, pipe the dd command to the restore command and type the following command:
```
dd if=/dev/rmt0 bs=64b | restore -xf- -b64 
```
The dd command reads the archive from the tape using a block size of 64 512-byte blocks and writes the archive to standard output. The restore command reads the standard input using a block size of 64 512-byte blocks. The value of the block size used by the dd command to read the archive from the tape must be an even multiple of the block size that was used to create the tape with the backup command. For example, the following backup command could be used to create the archive that this example extracts:
```
find /home -print | backup -ivqf/dev/rmt0 -b64 
```
This example applies to archives in file name format only. If the archive was in file system format, the restore command should include the -B flag.
To improve the performance of the restore command on 9348 Magnetic Tape Unit Model 12, you can change the block size by typing the following command:
```
chdev -l DeviceName -a BlockSize=32k
```
To restore nonsparse database files, type the following command:
```
restore  -xef  /dev/rmt0
```
To restore files that were archived as sparse, type the following command:
```
restore  -xf  /dev/rmt0
```
To restore only the permissions of the files from the archive, type the following command:
```
restore -Pa -vf /dev/rmt0
```
To restore only the ACL attributes of the files from the archive, type the following command:
```
restore -Pc -vf /dev/rmt0
```
To view the table of contents along with the file permissions, type the following command:
```
restore -Ta -vf /dev/rmt0
```
To view the table of contents of a file name archive along with the time stamps and file permissions, type the following command:
```
restore -Tl -vf /dev/rmt0
```
To view the table of contents of a file system archive along with the time stamps and file permissions, type the following command:
```
restore -tl -vf /dev/rmt0
```

Related Information

The backup command.

Last updated: Wed, November 18, 2020