cp - Copy a file

Description

cp copies files to a target named by the last argument on its command line. If the target is an existing file, cp overwrites it; if it does not exist, cp creates it. If the target file exists and does not have write permission, cp denies access and continues with the next copy.

If you specify more than two path names, the last path name (that is, the target) must be a directory. If the target is a directory, cp copies the sources into that directory with names that are given by the final component of the source path name.

You can also use cp to copy files to and from MVS™ data sets. If you specify more than one file to be copied, the target (last path name on command line) must be either a directory or a partitioned data set. If the target is an MVS partitioned data set, the source cannot be a UNIX directory.

cp does not support the copying to or from generation data groups (GDGs). To use those MVS data sets, the user must specify the real data set name. cp also does not support copying to a temporary PDSE.

When copying records, the string " \n" is copied the same way as the string "\n": both are read back as "\n", where "\n" indicates that z/OS XL C++ will write a record containing a single blank to the file (the default behavior of z/OS XL C/C++). All other blanks in your output are read back as blanks, and any empty (zero-length) records are ignored on input. However, if the environment variable _EDC_ZERO_RECLEN is set to Y before cp is called, an empty record is treated as a single newline character and is not ignored. Also, if _EDC_ZERO_RECLEN is set to Y, a single newline character is written to the file as an empty record, and a single blank will be represented by " \n".

Options

-A

Specifies that all suffixes (from the first period to the end of the target) be truncated. -A has precedence over -M and -C options. -s will be turned off if -A is the last option specified.

-B

Specifies that the data to be copied contains binary data. When you specify -B, cp operates without any consideration for <newline> characters or special characteristics of DBCS data. (This type of behavior is typical when data is copied across a UNIX system.) Because -B is mutually exclusive with -F, -x, and -T, you will get an error if you specify more than one of these options.

-C

Specifies truncating the file name to 8 characters to meet the restriction in the MVS data set member.

-c (UNIX to UNIX only)

Prompts you to change the disk if there is not enough room to complete a copy operation. This option has no effect on systems without disk drives. The parent directories must exist on the new target diskette.

-F format

Specifies whether the file is to be treated as binary, text, or record file format when copied; for text files, specifies the end-of-line delimiter. Also sets the file format to format if the target is a UNIX file. For text files, when copying from UNIX to MVS, the end-of-line delimiter is stripped. When copying from MVS to UNIX, the end-of-line delimiter is added. (Code page IBM-1047 is used to check for end-of-line delimiters.) Record file format files are treated as if they were binary files.

If -F is used when copying from UNIX to UNIX, cp sets only the target file format and does not replace the end-of-line delimiters.

If setting format fails, a warning is displayed but cp will continue to copy any remaining files that were specified to be copied.

-F is mutually exclusive with -B, -x, -p, and -T. If you specify one of these options with -F, you will get an error. If -F is specified more than once, the last -F specified is used.

For format, you can specify:

not

Not specified.

bin

Binary data.

rec

Record. (File data consists of records with prefixes. The record prefix contains the length of the record that follows. From the shell command perspective, files with this format will be treated as if they were binary files.)

Or, you can specify the following text data delimiters:

nl

Newline character.

cr

Carriage return.

lf

Line feed.

crlf

Carriage return followed by line feed.

lfcr

Line feed followed by carriage return.

crnl

Carriage return followed by new line.

-F

Attempts to remove and replace a UNIX destination file that cannot be opened.

-H

Follows symbolic links that are specified as source operand on the command line. Symbolic links that are encountered in the tree traversal are not followed. This is the default behavior when the -R or -r option is specified but none of the -H, -L or -P options are specified.

Restriction: This option can only be used with the -R or the -r option.

-i

When copying to a UNIX target, -i asks you if you want to overwrite an existing file, whether the file is read-only.

-L

Follows symbolic links that are specified as source operand on the command line and those encountered in the tree traverse.

Restriction: This option can only be used with the -R or the -r option.

-M

Specifies that some characters of the file name are converted during the copy process between a UNIX file and an MVS data set member. Characters are converted as follows:

• _ (underscore) in UNIX is converted to @ in MVS data set members and vice versa.
• . (period) in UNIX is converted to # in MVS data set members and vice versa.
• - (dash) in UNIX is converted to $ in MVS data set members and vice versa.

-F (UNIX to UNIX only)

Sets the modification and access time of each destination file to that of the corresponding source file. Typically, cp sets the modification time of the destination file to the present.

-I (UNIX to MVS only)

When the specified file has an alias and the file is copied from UNIX to MVS, the alias information is also copied. If the -I option is specified when the data set that is copied from MVS to z/OS UNIX does not have an alias, that option is ignored.

Restriction: The -I option can only be used with the -X option.

-O u | c=codeset

Allow automatic conversion on source and target files.

-O u

If the target exists and is not empty or tagged, cp will not change the target's tag in order for the target to be a candidate for automatic conversion.

For new targets and existing, untagged, empty files, this option has no effect and cp behaves the same as the default. For a description of the default behavior, see Automatic conversion and file tagging behavior for cp.

If you are using cp to copy from a UNIXan MVS file to a data set, if the source is a tagged text file, then it might be a candidate for automatic conversion.

If you are copying executables from or to MVS, the automatic conversion is disabled for both source and target.

-O c=codeset

For a detailed description of the behavior of this option on cp, see Automatic conversion and file tagging behavior for cp.

codeset can be a code set name known to the system or the numeric coded character set identifier (CCSID). If a code set name exists, the numeric CCSID associated with that name is used. Note that the command iconv -l lists existing CCSIDs along with their corresponding code set names.

To prevent the corruption of text files, cp will fail if it cannot set the tag to text or code set.

If automatic conversion is not set properly or if the source is not tagged properly, the target might end up with a tag code set that does not match the file content.

-P

If _UNIX03 is YES, does not follow any symbolic links, neither those specified as source operand on the command line not those encountered in the tree traverse.

Restriction: This option can only be used with the -R or the -r option.

-P params

If _UNIX03 is unset or not YES, then the -P option will be treated as specifying parameters needed to create a new sequential data set if one does not exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format the CRTL fopen() function uses.

SPACE=(units,(primary,secondary) where the following values are supported for units:

• Any positive integer indicating BLKSIZE.
• CYL (mixed case).
• TRK (mixed case).

For example:

SPACE=(500,(100,500)) units, primary, secondary
SPACE=(500,100) units and primary only

For information about how to specify these parameters, see z/OS XL C/C++ Programming Guide.

CRTL fopen() arguments: LRECL specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. BLKSIZE specifies the maximum length, in bytes, of a physical block of records. RECFM refers to the record format of a data set and SPACE indicates the space attributes for MVS data sets.

-p (UNIX to UNIX only)

Preserves the modification and access times (as the -m option does). In addition, it preserves the file mode, file format, owner, and group owner, if authorized. It also preserves extended attributes. It preserves the ACLs of files and directories, if possible. The ACLs are not preserved if a file system does not support ACLs.

-p is mutually exclusive with -F. If you specify both, you will get an error message.

-R (UNIX to UNIX only)

Clones the source trees. cp copies all the files and subdirectories that are specified by source... into directory, making careful arrangements to duplicate special files (FIFO, character special). cp only follows symbolic link specified as source operand on the command line.

-r (UNIX to UNIX only)

Clones the source trees, but makes no allowances for special files (FIFO, character special). Consequently, cp attempts to read from a device rather than duplicate the special file. This is similar to, but less useful than, the preferred -R.

-s d=suffix|a=suffix

• d=suffix removes the specified suffix from a file.
• a=suffix appends the specified suffix to a file.

-S has precedence over -M and -C. It also turns off the -A option (if -S is the last specified option).

-T

Specifies that the data to be copied contains text data. See Usage notes for details on how to treat text data. This option looks for IBM-1047 end-of-line delimiters, and is mutually exclusive with -F, -X, and -B. That is, you will get an error if you specify more than one of these options.

-T is ignored when if you are copying data across UNIX file systems.

-U

Keeps file names in uppercase when copying from MVS data set members to UNIX files. The default is to make file names lowercase.

-v

Verbose

-W seqparms=params

Specifies the parameters that are needed to create a sequential data set if one does not exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format the CRTL fopen() function uses.

SPACE=(units,(primary,secondary) where the following values are supported for units:

• Any positive integer indicating BLKSIZE.
• CYL (mixed case).
• TRK (mixed case).
  For example:

  SPACE=(500,(100,500)) units, primary, secondary
  SPACE=(500,100) units and primary only

For information about how to specify these parameters, see z/OS XL C/C++ Programming Guide.

CRTL fopen() arguments: LRECL specifies the length, in bytes, for fixed-length records and the maximum length for variable-length records. BLKSIZE specifies the maximum length, in bytes, of a physical block of records. RECFM refers to the record format of a data set and SPACE indicates the space attributes for MVS data sets.

This option is the same as -P params with _UNIX03 unset or not YES. If multiple -P params and -W are specified, the value of the last one specified on the command will be used.

-X

Specifies that the data to be copied is an executable. Cannot be used with -F, -T, or -B.

-Z

Specifies that error messages are not to be displayed when setting ACLs on the target. The return code will be zero. If default behavior is used to set the file tag, failure is suppressed. For a description of the default behavior, see Automatic conversion and file tagging behavior for cp.

If you do not specify either -F|B|T or X, cp will first check the format of the MVS data set indicated and then try to determine the type of file.

The -P option on cp does not affect file tagging.

Automatic conversion and file tagging behavior for cp

Limits and requirements

In general:

1. To specify an MVS data set name, precede the name with double slashes (//). For example, to specify the fully qualified data set names 'turbo.gammalib' and 'turbo.gammalib(pgm1)', write:

   "//'turbo.gammalib'"
   "//'turbo.gammalib(pgm1)'"

   The same goes for data set names that are not fully qualified:

   //turbo

2. For PDS (partitioned data set) or PDSE (partitioned data set extended), to avoid parsing by the shell, the name should be quoted or minimally, the parenthesis should be escaped. For example, to specify 'turbo(pgm1)', use quotes:

   "//turbo(pgm1)"  

   or escape the parenthesis:

   //turbo\(pgm1\)

   As indicated, a fully qualified name must be surrounded with single quotation marks (as is done within TSO). To prevent the single quotation marks from being interpreted by the shell, they must be escaped or the name must be placed within regular quotation marks. See the 'turbo.gammalib' examples.

3. If you specify a UNIX file as source and the MVS data set (target) does not exist, a sequential data set will be created. If the partitioned data set exists, the UNIX file will be copied to the partitioned data set member.
4. If source is an MVS data set and target is a UNIX directory, the UNIX directory must exist.
5. You cannot have a UNIX directory, partitioned data set, or sequential data set as source if the target is a partitioned data set.
6. To copy all members from a partitioned data set, you can specify the partitioned data set as source and a UNIX directory as target.

Table 5 is a quick reference for determining the correct use of options with cp.

The tables that follow indicate the kind of copies that are allowed by using cp.

Usage notes

cp test_file "//'posix.test.pdse(member)'" 

Localization

Format of the TZ environment variable explains how to set the local time zone with the TZ environment variable.

Environment variables

Exit values

0

Successful completion

1

Failure due to any of the following:

• An argument had a trailing slash (/) but was not a directory.
• Inability to find a file.
• Inability to open an input file for reading.
• Inability to create or open an output file.
• A read error occurred on an input file.
• A write error occurred on an output file.
• The input and output files were the same file.
• An unrecoverable error when using -r or -r. Possible unrecoverable -r or -r errors include:
  • Inability to access a file.
  • Inability to change permissions on a target file.
  • Inability to read a directory.
  • Inability to create a directory.
  • A target that is not a directory.
  • Source and destination directories are the same.

2

Failure due to any of the following:

• An incorrect command-line option.
• Too few arguments on the command line.
• A target that should be a directory but isn't.
• No space left on target device.
• Insufficient memory to hold the data to be copied.
• Inability to create a directory to hold a target file.

Messages

Portability

POSIX.2, X/Open Portability Guide, UNIX systems.

The -F and -m options are extensions of the POSIX standard.

Related information

cat, cpio, ln, mv, rm