GNU file utilities - 6. Basic operations

Go to the first, previous, next, last section, table of contents.

# 6. Basic operations

This chapter describes the commands for basic file manipulation: copying, moving (renaming), and deleting (removing).

## 6.1 `cp`: Copy files and directories

`cp` copies files (or, optionally, directories). The copy is completely independent of the original. You can either copy one file to another, or copy arbitrarily many files to a destination directory. Synopsis:

    cp [option]... source dest
    cp [option]... source... directory

If the last argument names an existing directory, `cp` copies each source file into that directory (retaining the same name). Otherwise, if only two files are given, it copies the first onto the second. It is an error if the last argument is not a directory and more than two non-option arguments are given.

Generally, files are written just as they are read. For exceptions, see the ``--sparse'` option below.

By default, `cp` does not copy directories (see ``-r'` below).

`cp` generally refuses to copy a file onto itself, with the following exception: if ``--force --backup'` is specified with source and dest identical, and referring to a regular file, `cp` will make a backup file, either regular or numbered, as specified in the usual ways (see section 2.1 Backup options). This is useful when you simply want to make a backup of an existing file before changing it.

The program accepts the following options. Also see section 2. Common options.

``-a'`
``--archive'`
  Preserve as much as possible of the structure and attributes of the original files in the copy (but do not preserve directory structure). Equivalent to ``-dpR'`.
``-b'`
``--backup'`
  Make a backup of each file that would otherwise be overwritten or removed. See section 2.1 Backup options.
``-d'`
``--no-dereference'`
  Copy symbolic links as symbolic links rather than copying the files that they point to, and preserve hard links between source files in the copies.
``-f'`
``--force'`
  Remove existing destination files.
``-i'`
``--interactive'`
  Prompt whether to overwrite existing regular destination files.
``-l'`
``--link'`
  Make hard links instead of copies of non-directories.
``-p'`
``--preserve'`
  Preserve the original files' owner, group, permissions, and timestamps.
``-P'`
``--parents'`
  Form the name of each destination file by appending to the target directory a slash and the specified name of the source file. The last argument given to `cp` must be the name of an existing directory. For example, the command:

      cp --parents a/b/c existing_dir

  copies the file ``a/b/c'` to ``existing_dir/a/b/c'`, creating any missing intermediate directories.
``-r'`
  Copy directories recursively, copying any non-directories and non-symbolic links (that is, FIFOs and special files) as if they were regular files. This means trying to read the data in each source file and writing it to the destination. It is usually a mistake to apply `cp -r` to special files like FIFOs and the ones typically found in the ``/dev'` directory. In most cases, `cp -r` will hang indefinitely trying to read from FIFOs and special files like ``/dev/console'`, and it will fill up your destination disk if you use it to copy ``/dev/zero'`. Use the ``--recursive'` (``-R'`) option instead if you want to copy special files, preserving their special nature rather than reading from them to copy their contents.
``-R'`
``--recursive'`
  Copy directories recursively, preserving non-directories (contrast with ``-r'` just above).
``--sparse=when'`
  A sparse file contains holes---a sequence of zero bytes that does not occupy any physical disk blocks; the ``read'` system call reads these as zeroes. This can both save considerable disk space and increase speed, since many binary files contain lots of consecutive zero bytes. By default, `cp` detects holes in input source files via a crude heuristic and makes the corresponding output file sparse as well. The when value can be one of the following:
  ``auto'`
    The default behavior: the output file is sparse if the input file is sparse.
  ``always'`
    Always make the output file sparse. This is useful when the input file resides on a filesystem that does not support sparse files (the most notable example is ``efs'` filesystems in SGI IRIX 5.3 and earlier), but the output file is on another type of filesystem.
  ``never'`
    Never make the output file sparse. If you find an application for this option, let us know.
``-s'`
``--symbolic-link'`
  Make symbolic links instead of copies of non-directories. All source file names must be absolute (starting with ``/'`) unless the destination files are in the current directory. This option merely results in an error message on systems that do not support symbolic links.
``-S suffix'`
``--suffix=suffix'`
  Append suffix to each backup file made with ``-b'`. See section 2.1 Backup options.
``-u'`
``--update'`
  Do not copy a nondirectory that has an existing destination with the same or newer modification time.
``-v'`
``--verbose'`
  Print the name of each file before copying it.
``-V method'`
``--version-control=method'`
  Change the type of backups made with ``-b'`. The method argument can be ``numbered'` (or ``t'`), ``existing'` (or ``nil'`), or ``never'` (or ``simple'`). See section 2.1 Backup options.
``-x'`
``--one-file-system'`
  Skip subdirectories that are on different filesystems from the one that the copy started on. However, mount point directories are copied.

## 6.2 `dd`: Convert and copy a file

`dd` copies a file (from standard input to standard output, by default) with a changeable I/O block size, while optionally performing conversions on it. Synopsis:

    dd [option]...

The program accepts the following options. Also see section 2. Common options.

The numeric-valued options below (bytes and blocks) can be followed by a multiplier: ``b'`=512, ``c'`=1, ``w'`=2, ``xm'`=m, or any of the standard block size suffixes like ``k'`=1024 (see section 2.2 Block size).

``if=file'`
  Read from file instead of standard input.
``of=file'`
  Write to file instead of standard output. Unless ``conv=notrunc'` is given, `dd` truncates file to zero bytes (or the size specified with ``seek='`).
``ibs=bytes'`
  Read bytes bytes at a time.
``obs=bytes'`
  Write bytes bytes at a time.
``bs=bytes'`
  Both read and write bytes bytes at a time. This overrides ``ibs'` and ``obs'`.
``cbs=bytes'`
  Convert bytes bytes at a time.
``skip=blocks'`
  Skip blocks ``ibs'`-byte blocks in the input file before copying.
``seek=blocks'`
  Skip blocks ``obs'`-byte blocks in the output file before copying.
``count=blocks'`
  Copy blocks ``ibs'`-byte blocks from the input file, instead of everything until the end of the file.
``conv=conversion[,conversion]...'`
  Convert the file as specified by the conversion argument(s). (No spaces around any comma(s).) Conversions:
  ``ascii'`
    Convert EBCDIC to ASCII.
  ``ebcdic'`
    Convert ASCII to EBCDIC.
  ``ibm'`
    Convert ASCII to alternate EBCDIC.
  ``block'`
    For each line in the input, output ``cbs'` bytes, replacing the input newline with a space and padding with spaces as necessary.
  ``unblock'`
    Replace trailing spaces in each ``cbs'`-sized input block with a newline.
  ``lcase'`
    Change uppercase letters to lowercase.
  ``ucase'`
    Change lowercase letters to uppercase.
  ``swab'`
    Swap every pair of input bytes. GNU `dd`, unlike others, works when an odd number of bytes are read--the last byte is simply copied (since there is nothing to swap it with).
  ``noerror'`
    Continue after read errors.
  ``notrunc'`
    Do not truncate the output file.
  ``sync'`
    Pad every input block to size of ``ibs'` with trailing zero bytes.

## 6.3 `install`: Copy files and set attributes

`install` copies files while setting their permission modes and, if possible, their owner and group. Synopses:

    install [option]... source dest
    install [option]... source... directory
    install -d [option]... directory...

In the first of these, the source file is copied to the dest target file. In the second, each of the source files are copied to the destination directory. In the last, each directory (and any missing parent directories) is created.

`install` is similar to `cp`, but allows you to control the attributes of destination files. It is typically used in Makefiles to copy programs into their destination directories. It refuses to copy files onto themselves.

The program accepts the following options. Also see section 2. Common options.

``-b'`
``--backup'`
  Make a backup of each file that would otherwise be overwritten or removed. See section 2.1 Backup options.
``-c'`
  Ignored; for compatibility with old Unix versions of `install`.
``-d'`
``--directory'`
  Create each given directory and any missing parent directories, setting the owner, group and mode as given on the command line or to the defaults. It also gives any parent directories it creates those attributes. (This is different from the SunOS 4.x `install`, which gives directories that it creates the default attributes.)
``-g group'`
``--group=group'`
  Set the group ownership of installed files or directories to group. The default is the process's current group. group may be either a group name or a numeric group id.
``-m mode'`
``--mode=mode'`
  Set the permissions for the installed file or directory to mode, which can be either an octal number, or a symbolic mode as in `chmod`, with 0 as the point of departure (see section 3. File permissions). The default mode is 0755--read, write, and execute for the owner, and read and execute for group and other.
``-o owner'`
``--owner=owner'`
  If `install` has appropriate privileges (is run as root), set the ownership of installed files or directories to owner. The default is `root`. owner may be either a user name or a numeric user ID.
``-p'`
``--preserve-timestamps'`
  Set the time of last access and the time of last modification of each installed file to match those of each corresponding original file. When a file is installed without this option, its last access and last modification times are both set to the time of installation. This option is useful if you want to use the last modification times of installed files to keep track of when they were last built as opposed to when they were last installed.
``-s'`
``--strip'`
  Strip the symbol tables from installed binary executables.
``-S suffix'`
``--suffix=suffix'`
  Append suffix to each backup file made with ``-b'`. See section 2.1 Backup options.
``-v'`
``--verbose'`
  Print the name of each file before copying it.
``-V method'`
``--version-control=method'`
  Change the type of backups made with ``-b'`. The method argument can be ``numbered'` (or ``t'`), ``existing'` (or ``nil'`), or ``never'` (or ``simple'`). See section 2.1 Backup options.

## 6.4 `mv`: Move (rename) files

`mv` moves or renames files (or directories). Synopsis:

    mv [option]... source dest
    mv [option]... source... directory

If the last argument names an existing directory, `mv` moves each other given file into a file with the same name in that directory. Otherwise, if only two files are given, it renames the first as the second. It is an error if the last argument is not a directory and more than two files are given.

`mv` can move only regular files across filesystems.

If a destination file exists but is normally unwritable, standard input is a terminal, and the ``-f'` or ``--force'` option is not given, `mv` prompts the user for whether to replace the file. (You might own the file, or have write permission on its directory.) If the response does not begin with ``y'` or ``Y'`, the file is skipped.

The program accepts the following options. Also see section 2. Common options.

``-b'`
``--backup'`
  Make a backup of each file that would otherwise be overwritten or removed. See section 2.1 Backup options.
``-f'`
``--force'`
  Remove existing destination files and never prompt the user.
``-i'`
``--interactive'`
  Prompt whether to overwrite each existing destination file, regardless of its permissions. If the response does not begin with ``y'` or ``Y'`, the file is skipped.
``-u'`
``--update'`
  Do not move a nondirectory that has an existing destination with the same or newer modification time.
``-v'`
``--verbose'`
  Print the name of each file before moving it.
``-S suffix'`
``--suffix=suffix'`
  Append suffix to each backup file made with ``-b'`. See section 2.1 Backup options.
``-V method'`
``--version-control=method'`
  Change the type of backups made with ``-b'`. The method argument can be ``numbered'` (or ``t'`), ``existing'` (or ``nil'`), or ``never'` (or ``simple'`). See section 2.1 Backup options.

## 6.5 `rm`: Remove files or directories

`rm` removes each given file. By default, it does not remove directories. Synopsis:

    rm [option]... [file]...

If a file is unwritable, standard input is a terminal, and the ``-f'` or ``--force'` option is not given, or the ``-i'` or ``--interactive'` option is given, `rm` prompts the user for whether to remove the file. If the response does not begin with ``y'` or ``Y'`, the file is skipped.

The program accepts the following options. Also see section 2. Common options.

``-d'`
``--directory'`
  Remove directories with `unlink` instead of `rmdir`, and don't require a directory to be empty before trying to unlink it. Only works if you have appropriate privileges. Because unlinking a directory causes any files in the deleted directory to become unreferenced, it is wise to `fsck` the filesystem after doing this.
``-f'`
``--force'`
  Ignore nonexistent files and never prompt the user. Ignore any previous ``--interactive'` (``-i'`) option.
``-i'`
``--interactive'`
  Prompt whether to remove each file. If the response does not begin with ``y'` or ``Y'`, the file is skipped. Ignore any previous ``--force'` (``-f'`) option.
``-r'`
``-R'`
``--recursive'`
  Remove the contents of directories recursively.
``-v'`
``--verbose'`
  Print the name of each file before removing it.

One common question is how to remove files whose names begin with a ``-'`. GNU `rm`, like every program that uses the `getopt` function to parse its arguments, lets you use the ``--'` option to indicate that all following arguments are non-options. To remove a file called ``-f'` in the current directory, you could type either:

    rm -- -f

or:

    rm ./-f

The Unix `rm` program's use of a single ``-'` for this purpose predates the development of the getopt standard syntax.

Go to the first, previous, next, last section, table of contents.