Provided by: manpages-posix_2017a-2_all bug

PROLOG

       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

       cp — copy files

SYNOPSIS

       cp [-Pfip] source_file target_file

       cp [-Pfip] source_file... target

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

DESCRIPTION

       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‐2017, 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‐2017 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‐2017 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‐2017  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‐2017, Section  4.5,  File  Access  Permissions),  their
       effect on copies of files is implementation-defined.

OPTIONS

       The cp utility shall conform to the Base Definitions volume of POSIX.1‐2017, 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

       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

       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

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

ENVIRONMENT VARIABLES

       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‐2017,  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

       Default.

STDOUT

       Not used.

STDERR

       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

       The output files may be of any type.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0    All files were copied successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS

       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

       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

       None.

RATIONALE

       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‐2017 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‐2017 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‐2017 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‐2017. 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‐2017. The other method
       is described as part of the pax utility (see pax).  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‐2017  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‐2017  file
       types may need to use this loophole as well.

FUTURE DIRECTIONS

       None.

SEE ALSO

       mv, find, ln, pax

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

       The System Interfaces volume of POSIX.1‐2017, open(), unlink()

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1-2017,  Standard  for  Information Technology -- Portable Operating System Interface
       (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C)  2018  by
       the  Institute  of  Electrical  and Electronics Engineers, Inc and The Open Group.  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.opengroup.org/unix/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 .