CP(1P)

✨ PROLOG ✨

okay bestie, housekeeping first, don't skip it. 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. so like, go read your local page too, no cap 🫶

---

🎀 NAME 🎀

cp — copy files 💖

like. that's the whole thing. it copies files. iconic behavior honestly ✨

---

💫 SYNOPSIS 💫

cp [-Pfip] source_file target_file

cp [-Pfip] source_file... target

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

---

🦋 DESCRIPTION 🦋

okay so cp has three whole moods and which one you get depends on your operands. buckle up bestie, we're going through all of them. 🌸

Form one — the classic two-operand moment. The first synopsis form is denoted by two operands, neither of which are existing files of type directory. cp 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. it's giving "just put the thing where I said" 💅

Form two — the group chat. 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. cp 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. so yes, the slash situation is load-bearing, we love a detail ✨

Form three — the -R era, main character energy. The third synopsis form is denoted by two or more operands where the -R option is specified. cp 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. it's giving "everyone gets a spot under target" 🎀
• 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. that's a hard no bestie, not a vibe 💀

---

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. yeah, nobody told you, it's a mystery, we don't make the rules 😭
  • 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. links stay links, periodt 🔗

---

🌈 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. copying a file onto itself? girl, no. moving on 🫶
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. so maybe it does, maybe it doesn't, we simply do not know 🙈
   • 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_file*s. recursion, but make it cute 🧚
   • 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. it's literally asking for your permission, answer nicely 💖
     • 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. close the door behind you bestie 🚪✨
   • 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.

---

one last heads-up before we move on: 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. so like, your ACL situation is between you and your system, bestie 💅

and we are not done yet — hold that thought, there's more coming 👑

✨ OPTIONS ✨

okay so before we even get into the flags, know this: cp is a well-behaved queen 👑 and she conforms to the Base Definitions volume of POSIX.1-2017, Section 12.2, Utility Syntax Guidelines. she follows the rules, she's not out here doing her own thing 💅

The following options shall be supported:

• -f — if a file descriptor for a destination file cannot be obtained, like, the way step 3.a.ii. describes it, then she attempts to unlink the destination file and proceeds. no hesitation, no drama, just yeet and go 🔥
• -H — take actions based on the type and contents of the file referenced by any symbolic link specified as a source_file operand. so if you hand her a symlink, she looks at what it points to, not the link itself.
• -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. basically she's asking "bestie are you SURE" before she overwrites 🙈
• -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. so links get followed everywhere, both the ones you named and the ones she bumps into along the way.
• -P — take actions on any symbolic link specified as a source_file operand, or any symbolic link encountered during traversal of a file hierarchy. she treats the links as links, no following, no chasing, we stay on the link itself 💜
• -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. whole trees, recursively, that's the vibe 🌸

Now a lil plot twist: 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. so whichever one you said last wins, no hard feelings, no yelling 🎀

---

🫶 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. yes really, it's literally a file whose name is just a dash, don't come for her.
• 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. same energy, same dash, no stdin/stdout shenanigans 💀
• 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. so she only touches stdin when she's asking you a question, otherwise she's minding her own business.

📂 INPUT FILES 📂

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

🌈 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. she said all of them. every single one. periodt.
• 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. yeah. default. that's the whole thing, she's not doing anything special here 💅

🖨️ STDOUT 🖨️

Not used. she simply does not speak there.

😭 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. so if you see something on stderr that isn't a prompt, bestie, that's a diagnostic and something went sideways.

📦 OUTPUT FILES 📦

The output files may be of any type. again, any type. she does not discriminate 🦋

🧚 EXTENDED DESCRIPTION 🧚

None.

🔥 EXIT STATUS 🔥

The following exit values shall be returned:

• 0 — all files were copied successfully. slay.
• >0 — an error occurred. not slay. 😭

💀 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. so like, if she gets yanked mid-copy, you might be left with half a tree and some wonky metadata. be aware, bestie, this is a real one.

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. so yeah, she strips those bits on purpose, it's a safety thing, not a bug, don't @ her 🎀

🍓 EXAMPLES 🍓

None.

💭 RATIONALE (aka the ~lore~ behind all of this) 💭

Okay so first up: the -i option. It exists on BSD systems, and its whole thing is giving applications and users a way to not accidentally delete files while copying. Slay. But here's the tea: even though the 4.3 BSD version doesn't prompt if standard input isn't a terminal, the standard developers were like "no, using -i is a request for interaction," so when the destination path already exists, the utility takes instructions from whatever responds on standard input. Periodt.

The exact format of the interactive prompts is unspecified. Only the general nature of what's in the prompts is specified, because implementations might want more descriptive prompts than the historical ones. So an application using -i just relies on the system to give the most suitable dialog directly to the user, based on the behavior specified. iykyk.

---

Then there's -p. It's historical practice on BSD systems, duplicating the time of last data modification and the time of last access. This volume of POSIX.1‐2017 extends it to also preserve the user and group IDs, plus the file permissions. And yeah, that requirement has obvious problems — 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 there to let implementations 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's unspecified whether cp writes diagnostic messages when the user and group IDs can't be set — because users so commonly use -p to duplicate some portion of the file characteristics while being totally indifferent to duplicating the others. Historic implementations only write diagnostic messages on errors other than [EPERM].

---

Now, 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. It's no longer specified by POSIX.1‐2008 but may still be present in some implementations. The -R option got added as a close synonym to -r, picked for consistency with all the other options in this volume of POSIX.1‐2017 that do recursive directory descent.

The difference between -R and the removed -r? It's all about how cp treats file types other than regular and directory. It was implementation-defined how the -r option treated special files — that was 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, didn't handle special files any differently from regular files, but always read the file and copied its contents. And that had obvious problems in the presence of special file types — for example, character devices, FIFOs, and sockets. 😭

When a failure happens 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's unspecified whether cp shall attempt to copy files below the file where the failure occurred (which cannot succeed in any case anyway, so 💀).

---

Permissions, owners, and groups of created special file types have been deliberately left as implementation-defined. Why? To let systems 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's 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's also probable that additional privileges are required to create block, character, or other implementation-defined special file types.

Plus, 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 can't be set. This is so users don't unintentionally give 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've been: use the mode of the source file unmodified by the creation mask, or 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. But with no 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. Why? So cp can copy trees where the user has read permission but the owner doesn't. The side-effect though 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 mode 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 mode creation mask. This latter change from historical behavior is to prevent users from accidentally creating directories with permissions beyond those they'd 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's 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 to be 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. That's it. Nothing. Empty. The void. 🫥

---

👀 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 .

---

And that's a wrap bestie!! 🎀 This page was brought to you by IEEE/The Open Group, dated 2017, and it's the manual for CP(1P) — yes the whole thing, start to finish, and you read it all. I'm so proud of you fr fr. Go copy some files. Responsibly. 💅✨