CP(1P) - phpMan

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

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 [-fip] source_file target_file
       cp [-fip] source_file ... target
       cp -R [-H | -L | -P][-fip] 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 desti-
       nation path named by target_file.
       The second synopsis form is denoted by two or more operands  where  the
       -R  or  -r options are 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 is a file of a type
       defined by the System Interfaces volume of IEEE Std 1003.1-2001, but is
       not a file of type 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 slash character,  and  the
       last component of source_file.
       The third and fourth synopsis forms are denoted by two or more operands
       where the -R or -r options are specified.  The cp  utility  shall  copy
       each  file in the file hierarchy rooted in each source_file to a desti-
       nation path named as follows:
        * If target exists and is a file of type directory, the  name  of  the
          corresponding  destination  path for each file in the file hierarchy
          shall be the concatenation of target, a  slash  character,  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  oper-
       ands are specified, or if target exists and is a file of a type defined
       by the System Interfaces volume of IEEE Std 1003.1-2001, but is  not  a
       file of type 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  neither  the  -R  nor  -r  options were 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.
        * 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  encoun-
             tered 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 encoun-
             tered  during traversal of a file hierarchy, and shall not follow
             any symbolic links.
        * If the -r option was  specified,  the  behavior  is  implementation-
          defined.
       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 neither the -R or -r options were 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 IEEE Std 1003.1-2001, 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. 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  per-
                    forming  actions equivalent to the open() function defined
                    in the System Interfaces  volume  of  IEEE Std 1003.1-2001
                    called  using dest_file as the path argument, and the bit-
                    wise-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
                    IEEE Std 1003.1-2001  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()  func-
               tion    defined    in   the   System   Interfaces   volume   of
               IEEE Std 1003.1-2001 called using dest_file as the  path  argu-
               ment,  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  diag-
               nostic 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  con-
               tinues  with any remaining files. If no write error occurred in
               step 3d, cp shall go on to any remaining files.
        4. Otherwise, the following steps shall be taken:
            a. If the -r option was specified, the behavior is implementation-
               defined.
            b. If  the  -R  option was specified, the following steps shall be
               taken:
               i.   The dest_file shall be created with the same file type  as
                    source_file.
               ii.  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 diag-
               nostic  message  to  standard  error,  do  nothing  more   with
               source_file, and go on to any remaining files.
               iii. If  source_file is a file of type symbolic link, the path-
                    name contained in dest_file shall be the same as the path-
                    name contained in source_file.
               If  this fails for any reason, cp shall write a diagnostic mes-
               sage 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  IEEE Std 1003.1-2001,
       Section  4.4, File Access Permissions), their effect on copies of files
       is implementation-defined.
OPTIONS
       The cp  utility  shall  conform  to  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, 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 refer-
              enced by any symbolic link specified as a source_file operand.
       -i     Write a prompt to standard error before copying to any  existing
              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 refer-
              enced by any symbolic link specified as a source_file operand or
              any  symbolic links encountered during traversal of a file hier-
              archy.
       -P     Take actions on any symbolic link specified as a source_file op-
              erand  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  permis-
       sion  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 stan-
       dard error.
       The order in which the  preceding  characteristics  are  duplicated  is
       unspecified.  The  dest_file shall not be deleted if these characteris-
       tics cannot be preserved.
       -R     Copy file hierarchies.
       -r     Copy file hierarchies. The treatment of special files is  imple-
              mentation-defined.

       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.
       target_file
              A pathname of an existing or nonexistent file, used for the out-
              put when a single file is copied.
       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
              IEEE Std 1003.1-2001, Section  8.2,  Internationalization  Vari-
              ables  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 key-
              word 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 regu-
              lar expression defined for the yesexpr  locale  keyword  in  the
              LC_MESSAGES category.
       LC_MESSAGES
              Determine the locale for the processing of affirmative responses
              that should be used to affect the format and contents  of  diag-
              nostic messages 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 speci-
       fied  in the DESCRIPTION section. The prompt shall contain the destina-
       tion 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  difference  between  -R  and  -r is in the treatment by cp of file
       types other than regular and directory.  The original -r flag, for his-
       toric reasons, does not handle special files any differently from regu-
       lar files, but always reads the file and copies its contents. This  has
       obvious  problems  in  the presence of special file types; for example,
       character devices, FIFOs, and sockets. The -R  option  is  intended  to
       recreate the file hierarchy and the -r option supports historical prac-
       tice. It was anticipated that  a  future  version  of  this  volume  of
       IEEE Std 1003.1-2001  would  deprecate the -r option, and for that rea-
       son, there has been no attempt to fix  its  behavior  with  respect  to
       FIFOs or other file types where copying the file is clearly wrong. How-
       ever, some implementations support -r with the same abilities as the -R
       defined  in this volume of IEEE Std 1003.1-2001. To accommodate them as
       well as systems that do not, the differences  between  -r  and  -R  are
       implementation-defined. Implementations may make them identical. The -r
       option is marked obsolescent.
       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  inter-
       action, so when the destination path exists, the utility takes instruc-
       tions 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 imple-
       mentations may desire more descriptive prompts than those used on  his-
       torical  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
       IEEE Std 1003.1-2001  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  IEEE Std 1003.1-2001  requires  that  the  modification
       times  be  preserved. The statement that the order in which the charac-
       teristics 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  set-
       ting  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,  indif-
       ferent  to  the  duplication  of others.  Historic implementations only
       write diagnostic messages on errors other than [EPERM].
       The -r option is historical practice on BSD  and  BSD-derived  systems,
       copying  file hierarchies as opposed to single files.  This functional-
       ity is used heavily in historical applications, and its loss would sig-
       nificantly  decrease consensus. The -R option was added as a close syn-
       onym to the -r option, selected for consistency with all other  options
       in  this  volume  of  IEEE Std 1003.1-2001  that do recursive directory
       descent.
       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 unspeci-
       fied 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  per-
       missions, 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. His-
       torical implementations have detected the attempt in most cases.
       There   are   two  methods  of  copying  subtrees  in  this  volume  of
       IEEE Std 1003.1-2001.  The other method is described as part of the pax
       utility  (see pax ). Both methods are historical practice. The cp util-
       ity 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 combi-
       nations  in both utilities). The results are not required to be identi-
       cal; there seemed insufficient gain to applications to balance the dif-
       ficulty  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
       IEEE Std 1003.1-2001 is provided  so  that  implementations  supporting
       symbolic links are not required to prohibit copying directories to sym-
       bolic links. Other  extensions  to  the  System  Interfaces  volume  of
       IEEE Std 1003.1-2001 file types may need to use this loophole as well.
FUTURE DIRECTIONS
       The -r option may be removed; use -R instead.
SEE ALSO
       mv,    find,    ln,    pax,    the    System   Interfaces   volume   of
       IEEE Std 1003.1-2001, open(), unlink()
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 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 .

IEEE/The Open Group                  2003                               CP(1P)