PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

CP(1P)                    POSIX Programmer's Manual                   CP(1P)

PROLOG         top

       This manual page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the
       corresponding Linux manual page for details of Linux behavior), or
       the interface may not be implemented on Linux.

NAME         top

       cp — copy files

SYNOPSIS         top

       cp [−Pfip] source_file target_file

       cp [−Pfip] source_file... target

       cp −R [−H|−L|−P] [−fip] source_file... target

DESCRIPTION         top

       The first synopsis form is denoted by two operands, neither of which
       are existing files of type directory. The cp utility shall copy the
       contents of source_file (or, if source_file is a file of type
       symbolic link, the contents of the file referenced by source_file) to
       the destination path named by target_file.

       The second synopsis form is denoted by two or more operands where the
       −R option is not specified and the first synopsis form is not
       applicable. It shall be an error if any source_file is a file of type
       directory, if target does not exist, or if target does not name a
       directory. The cp utility shall copy the contents of each source_file
       (or, if source_file is a file of type symbolic link, the contents of
       the file referenced by source_file) to the destination path named by
       the concatenation of target, a single <slash> character if target did
       not end in a <slash>, and the last component of source_file.

       The third synopsis form is denoted by two or more operands where the
       −R option is specified. The cp utility shall copy each file in the
       file hierarchy rooted in each source_file to a destination path named
       as follows:

        *  If target exists and names an existing directory, the name of the
           corresponding destination path for each file in the file
           hierarchy shall be the concatenation of target, a single <slash>
           character if target did not end in a <slash>, and the pathname of
           the file relative to the directory containing source_file.

        *  If target does not exist and two operands are specified, the name
           of the corresponding destination path for source_file shall be
           target; the name of the corresponding destination path for all
           other files in the file hierarchy shall be the concatenation of
           target, a <slash> character, and the pathname of the file
           relative to source_file.

       It shall be an error if target does not exist and more than two
       operands are specified, or if target exists and does not name a
       directory.

       In the following description, the term dest_file refers to the file
       named by the destination path. The term source_file refers to the
       file that is being copied, whether specified as an operand or a file
       in a file hierarchy rooted in a source_file operand. If source_file
       is a file of type symbolic link:

        *  If the −R option was not specified, cp shall take actions based
           on the type and contents of the file referenced by the symbolic
           link, and not by the symbolic link itself, unless the −P option
           was specified.

        *  If the −R option was specified:

           --  If none of the options −H, −L, nor −P were specified, it is
               unspecified which of −H, −L, or −P will be used as a default.

           --  If the −H option was specified, cp shall take actions based
               on the type and contents of the file referenced by any
               symbolic link specified as a source_file operand.

           --  If the −L option was specified, cp shall take actions based
               on the type and contents of the file referenced by any
               symbolic link specified as a source_file operand or any
               symbolic links encountered during traversal of a file
               hierarchy.

           --  If the −P option was specified, cp shall copy any symbolic
               link specified as a source_file operand and any symbolic
               links encountered during traversal of a file hierarchy, and
               shall not follow any symbolic links.

       For each source_file, the following steps shall be taken:

        1. If source_file references the same file as dest_file, cp may
           write a diagnostic message to standard error; it shall do nothing
           more with source_file and shall go on to any remaining files.

        2. If source_file is of type directory, the following steps shall be
           taken:

            a. If the −R option was not specified, cp shall write a
               diagnostic message to standard error, do nothing more with
               source_file, and go on to any remaining files.

            b. If source_file was not specified as an operand and
               source_file is dot or dot-dot, cp shall do nothing more with
               source_file and go on to any remaining files.

            c. If dest_file exists and it is a file type not specified by
               the System Interfaces volume of POSIX.1‐2008, the behavior is
               implementation-defined.

            d. If dest_file exists and it is not of type directory, cp shall
               write a diagnostic message to standard error, do nothing more
               with source_file or any files below source_file in the file
               hierarchy, and go on to any remaining files.

            e. If the directory dest_file does not exist, it shall be
               created with file permission bits set to the same value as
               those of source_file, modified by the file creation mask of
               the user if the −p option was not specified, and then
               bitwise-inclusively OR'ed with S_IRWXU. If dest_file cannot
               be created, cp shall write a diagnostic message to standard
               error, do nothing more with source_file, and go on to any
               remaining files. It is unspecified if cp attempts to copy
               files in the file hierarchy rooted in source_file.

            f. The files in the directory source_file shall be copied to the
               directory dest_file, taking the four steps (1 to 4) listed
               here with the files as source_files.

            g. If dest_file was created, its file permission bits shall be
               changed (if necessary) to be the same as those of
               source_file, modified by the file creation mask of the user
               if the −p option was not specified.

            h. The cp utility shall do nothing more with source_file and go
               on to any remaining files.

        3. If source_file is of type regular file, the following steps shall
           be taken:

            a. The behavior is unspecified if dest_file exists and was
               written by a previous step. Otherwise, if dest_file exists,
               the following steps shall be taken:

                i.  If the −i option is in effect, the cp utility shall
                    write a prompt to the standard error and read a line
                    from the standard input. If the response is not
                    affirmative, cp shall do nothing more with source_file
                    and go on to any remaining files.

               ii.  A file descriptor for dest_file shall be obtained by
                    performing actions equivalent to the open() function
                    defined in the System Interfaces volume of POSIX.1‐2008
                    called using dest_file as the path argument, and the
                    bitwise-inclusive OR of O_WRONLY and O_TRUNC as the
                    oflag argument.

               iii. If the attempt to obtain a file descriptor fails and the
                    −f option is in effect, cp shall attempt to remove the
                    file by performing actions equivalent to the unlink()
                    function defined in the System Interfaces volume of
                    POSIX.1‐2008 called using dest_file as the path
                    argument. If this attempt succeeds, cp shall continue
                    with step 3b.

            b. If dest_file does not exist, a file descriptor shall be
               obtained by performing actions equivalent to the open()
               function defined in the System Interfaces volume of
               POSIX.1‐2008 called using dest_file as the path argument, and
               the bitwise-inclusive OR of O_WRONLY and O_CREAT as the oflag
               argument. The file permission bits of source_file shall be
               the mode argument.

            c. If the attempt to obtain a file descriptor fails, cp shall
               write a diagnostic message to standard error, do nothing more
               with source_file, and go on to any remaining files.

            d. The contents of source_file shall be written to the file
               descriptor. Any write errors shall cause cp to write a
               diagnostic message to standard error and continue to step 3e.

            e. The file descriptor shall be closed.

            f. The cp utility shall do nothing more with source_file.  If a
               write error occurred in step 3d, it is unspecified if cp
               continues with any remaining files. If no write error
               occurred in step 3d, cp shall go on to any remaining files.

        4. Otherwise, the −R option was specified, and the following steps
           shall be taken:

            a. The dest_file shall be created with the same file type as
               source_file.

            b. If source_file is a file of type FIFO, the file permission
               bits shall be the same as those of source_file, modified by
               the file creation mask of the user if the −p option was not
               specified. Otherwise, the permissions, owner ID, and group ID
               of dest_file are implementation-defined.

               If this creation fails for any reason, cp shall write a
               diagnostic message to standard error, do nothing more with
               source_file, and go on to any remaining files.

            c. If source_file is a file of type symbolic link, and the
               options require the symbolic link itself to be acted upon,
               the pathname contained in dest_file shall be the same as the
               pathname contained in source_file.

               If this fails for any reason, cp shall write a diagnostic
               message to standard error, do nothing more with source_file,
               and go on to any remaining files.

       If the implementation provides additional or alternate access control
       mechanisms (see the Base Definitions volume of POSIX.1‐2008, Section
       4.4, File Access Permissions), their effect on copies of files is
       implementation-defined.

OPTIONS         top

       The cp utility shall conform to the Base Definitions volume of
       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

       −f        If a file descriptor for a destination file cannot be
                 obtained, as described in step 3.a.ii., attempt to unlink
                 the destination file and proceed.

       −H        Take actions based on the type and contents of the file
                 referenced by any symbolic link specified as a source_file
                 operand.

       −i        Write a prompt to standard error before copying to any
                 existing non-directory destination file. If the response
                 from the standard input is affirmative, the copy shall be
                 attempted; otherwise, it shall not.

       −L        Take actions based on the type and contents of the file
                 referenced by any symbolic link specified as a source_file
                 operand or any symbolic links encountered during traversal
                 of a file hierarchy.

       −P        Take actions on any symbolic link specified as a
                 source_file operand or any symbolic link encountered during
                 traversal of a file hierarchy.

       −p        Duplicate the following characteristics of each source file
                 in the corresponding destination file:

                  1. The time of last data modification and time of last
                     access. If this duplication fails for any reason, cp
                     shall write a diagnostic message to standard error.

                  2. The user ID and group ID. If this duplication fails for
                     any reason, it is unspecified whether cp writes a
                     diagnostic message to standard error.

                  3. The file permission bits and the S_ISUID and S_ISGID
                     bits. Other, implementation-defined, bits may be
                     duplicated as well. If this duplication fails for any
                     reason, cp shall write a diagnostic message to standard
                     error.

                 If the user ID or the group ID cannot be duplicated, the
                 file permission bits S_ISUID and S_ISGID shall be cleared.
                 If these bits are present in the source file but are not
                 duplicated in the destination file, it is unspecified
                 whether cp writes a diagnostic message to standard error.

                 The order in which the preceding characteristics are
                 duplicated is unspecified. The dest_file shall not be
                 deleted if these characteristics cannot be preserved.

       −R        Copy file hierarchies.

       Specifying more than one of the mutually-exclusive options −H, −L,
       and −P shall not be considered an error. The last option specified
       shall determine the behavior of the utility.

OPERANDS         top

       The following operands shall be supported:

       source_file
                 A pathname of a file to be copied. If a source_file operand
                 is '−', it shall refer to a file named ; implementations
                 shall not treat it as meaning standard input.

       target_file
                 A pathname of an existing or nonexistent file, used for the
                 output when a single file is copied. If a target_file
                 operand is '−', it shall refer to a file named ;
                 implementations shall not treat it as meaning standard
                 output.

       target    A pathname of a directory to contain the copied files.

STDIN         top

       The standard input shall be used to read an input line in response to
       each prompt specified in the STDERR section. Otherwise, the standard
       input shall not be used.

INPUT FILES         top

       The input files specified as operands may be of any file type.

ENVIRONMENT VARIABLES         top

       The following environment variables shall affect the execution of cp:

       LANG      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1‐2008, Section 8.2, Internationalization
                 Variables for the precedence of internationalization
                 variables used to determine the values of locale
                 categories.)

       LC_ALL    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       LC_COLLATE
                 Determine the locale for the behavior of ranges,
                 equivalence classes, and multi-character collating elements
                 used in the extended regular expression defined for the
                 yesexpr locale keyword in the LC_MESSAGES category.

       LC_CTYPE  Determine the locale for the interpretation of sequences of
                 bytes of text data as characters (for example, single-byte
                 as opposed to multi-byte characters in arguments and input
                 files) and the behavior of character classes used in the
                 extended regular expression defined for the yesexpr locale
                 keyword in the LC_MESSAGES category.

       LC_MESSAGES
                 Determine the locale used to process affirmative responses,
                 and the locale used to affect the format and contents of
                 diagnostic messages and prompts written to standard error.

       NLSPATH   Determine the location of message catalogs for the
                 processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS         top

       Default.

STDOUT         top

       Not used.

STDERR         top

       A prompt shall be written to standard error under the conditions
       specified in the DESCRIPTION section. The prompt shall contain the
       destination pathname, but its format is otherwise unspecified.
       Otherwise, the standard error shall be used only for diagnostic
       messages.

OUTPUT FILES         top

       The output files may be of any type.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       The following exit values shall be returned:

        0    All files were copied successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       If cp is prematurely terminated by a signal or error, files or file
       hierarchies may be only partially copied and files and directories
       may have incorrect permissions or access and modification times.

       The following sections are informative.

APPLICATION USAGE         top

       The set-user-ID and set-group-ID bits are explicitly cleared when
       files are created. This is to prevent users from creating programs
       that are set-user-ID or set-group-ID to them when copying files or to
       make set-user-ID or set-group-ID files accessible to new groups of
       users.  For example, if a file is set-user-ID and the copy has a
       different group ID than the source, a new group of users has execute
       permission to a set-user-ID program than did previously. In
       particular, this is a problem for superusers copying users' trees.

EXAMPLES         top

       None.

RATIONALE         top

       The −i option exists on BSD systems, giving applications and users a
       way to avoid accidentally removing files when copying. Although the
       4.3 BSD version does not prompt if the standard input is not a
       terminal, the standard developers decided that use of −i is a request
       for interaction, so when the destination path exists, the utility
       takes instructions from whatever responds on standard input.

       The exact format of the interactive prompts is unspecified. Only the
       general nature of the contents of prompts are specified because
       implementations may desire more descriptive prompts than those used
       on historical implementations. Therefore, an application using the −i
       option relies on the system to provide the most suitable dialog
       directly with the user, based on the behavior specified.

       The −p option is historical practice on BSD systems, duplicating the
       time of last data modification and time of last access. This volume
       of POSIX.1‐2008 extends it to preserve the user and group IDs, as
       well as the file permissions. This requirement has obvious problems
       in that the directories are almost certainly modified after being
       copied. This volume of POSIX.1‐2008 requires that the modification
       times be preserved. The statement that the order in which the
       characteristics are duplicated is unspecified is to permit
       implementations to provide the maximum amount of security for the
       user.  Implementations should take into account the obvious security
       issues involved in setting the owner, group, and mode in the wrong
       order or creating files with an owner, group, or mode different from
       the final value.

       It is unspecified whether cp writes diagnostic messages when the user
       and group IDs cannot be set due to the widespread practice of users
       using −p to duplicate some portion of the file characteristics,
       indifferent to the duplication of others. Historic implementations
       only write diagnostic messages on errors other than [EPERM].

       Earlier versions of this standard included support for the −r option
       to copy file hierarchies. The −r option is historical practice on BSD
       and BSD-derived systems. This option is no longer specified by
       POSIX.1‐2008 but may be present in some implementations. The −R
       option was added as a close synonym to the −r option, selected for
       consistency with all other options in this volume of POSIX.1‐2008
       that do recursive directory descent.

       The difference between −R and the removed −r option is in the
       treatment by cp of file types other than regular and directory. It
       was implementation-defined how the option treated special files to
       allow both historical implementations and those that chose to support
       −r with the same abilities as −R defined by this volume of
       POSIX.1‐2008. The original −r flag, for historic reasons, did not
       handle special files any differently from regular files, but always
       read the file and copied its contents. This had obvious problems in
       the presence of special file types; for example, character devices,
       FIFOs, and sockets.

       When a failure occurs during the copying of a file hierarchy, cp is
       required to attempt to copy files that are on the same level in the
       hierarchy or above the file where the failure occurred. It is
       unspecified if cp shall attempt to copy files below the file where
       the failure occurred (which cannot succeed in any case).

       Permissions, owners, and groups of created special file types have
       been deliberately left as implementation-defined. This is to allow
       systems to satisfy special requirements (for example, allowing users
       to create character special devices, but requiring them to be owned
       by a certain group). In general, it is strongly suggested that the
       permissions, owner, and group be the same as if the user had run the
       historical mknod, ln, or other utility to create the file. It is also
       probable that additional privileges are required to create block,
       character, or other implementation-defined special file types.

       Additionally, the −p option explicitly requires that all set-user-ID
       and set-group-ID permissions be discarded if any of the owner or
       group IDs cannot be set. This is to keep users from unintentionally
       giving away special privilege when copying programs.

       When creating regular files, historical versions of cp use the mode
       of the source file as modified by the file mode creation mask. Other
       choices would have been to use the mode of the source file unmodified
       by the creation mask or to use the same mode as would be given to a
       new file created by the user (plus the execution bits of the source
       file) and then modify it by the file mode creation mask. In the
       absence of any strong reason to change historic practice, it was in
       large part retained.

       When creating directories, historical versions of cp use the mode of
       the source directory, plus read, write, and search bits for the
       owner, as modified by the file mode creation mask. This is done so
       that cp can copy trees where the user has read permission, but the
       owner does not. A side-effect is that if the file creation mask
       denies the owner permissions, cp fails. Also, once the copy is done,
       historical versions of cp set the permissions on the created
       directory to be the same as the source directory, unmodified by the
       file creation mask.

       This behavior has been modified so that cp is always able to create
       the contents of the directory, regardless of the file creation mask.
       After the copy is done, the permissions are set to be the same as the
       source directory, as modified by the file creation mask. This latter
       change from historical behavior is to prevent users from accidentally
       creating directories with permissions beyond those they would
       normally set and for consistency with the behavior of cp in creating
       files.

       It is not a requirement that cp detect attempts to copy a file to
       itself; however, implementations are strongly encouraged to do so.
       Historical implementations have detected the attempt in most cases.

       There are two methods of copying subtrees in this volume of
       POSIX.1‐2008. The other method is described as part of the pax
       utility (see pax(1p)).  Both methods are historical practice. The cp
       utility provides a simpler, more intuitive interface, while pax
       offers a finer granularity of control. Each provides additional
       functionality to the other; in particular, pax maintains the hard-
       link structure of the hierarchy, while cp does not. It is the
       intention of the standard developers that the results be similar
       (using appropriate option combinations in both utilities). The
       results are not required to be identical; there seemed insufficient
       gain to applications to balance the difficulty of implementations
       having to guarantee that the results would be exactly identical.

       The wording allowing cp to copy a directory to implementation-defined
       file types not specified by the System Interfaces volume of
       POSIX.1‐2008 is provided so that implementations supporting symbolic
       links are not required to prohibit copying directories to symbolic
       links. Other extensions to the System Interfaces volume of
       POSIX.1‐2008 file types may need to use this loophole as well.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       mv(1p), find(1p), ln(1p), pax(1p)

       The Base Definitions volume of POSIX.1‐2008, Section 4.4, File Access
       Permissions, Chapter 8, Environment Variables, Section 12.2, Utility
       Syntax Guidelines

       The System Interfaces volume of POSIX.1‐2008, open(3p), unlink(3p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) In the event of any discrepancy between this version and
       the original IEEE and The Open Group Standard, the original IEEE and
       The Open Group Standard is the referee document. The original
       Standard can be obtained online at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the
       source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                 2013                              CP(1P)

Pages that refer to this page: mv(1p)pax(1p)