mv - Rename or move a file or directory

Description

mv renames files or moves them to a different directory. If you specify multiple files, the target (that is, the last path name on the command line) must be a directory. mv moves the files into that directory and gives them names that match the final components of the source path names. When you specify a single source file and the target is not a directory, mv moves the source to the new name, by a simple rename if possible.

You can also use mv to move files to and from MVS™ data sets. If you specify more than one file to be moved, 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.

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

When moving records, the string " \n" is moved 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 calling mv, an empty record is treated as a single newline and is not ignored. Also, if _EDC_ZERO_RECLEN is set to Y, a single newline is written to the file as an empty record, and a single blank will be represented by " \n".

A file can be moved by any user who has write permission to the directory that contains the file, unless that directory has its sticky bit turned on. If the file is in a directory whose sticky bit is turned on, only the file owner or a superuser can move the file.

Options

-A

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

-B

Specifies that the data to be moved contains binary data. When you specify -B, /mv operates without any consideration for <newline> characters or special characteristics of DBCS data (this type of behavior is typical when moving across a UNIX system). -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 names to 8 characters to meet the restriction in the MVS data set member.

-F format

Specifies whether the file is to be treated as binary, text, or record file format when moved; for text files, specifies the end-of-line delimiter. Also sets the file format to format only if the source is an MVS data set and the target is a UNIX file. Only cp sets the file format for UNIX to UNIX operations. For text files, when moving from UNIX to MVS, the end-of-line delimiter will be stripped. When moving from MVS to UNIX, the end-of-line delimiter will be added. (Code page IBM-1047 is used to check for end-of-line delimiters). Record file formats are treated as if they were binary files.

-F is mutually exclusive with -B, -X, 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 are treated as if they were binary files.)

Or 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 a new line character

-f

Does not ask if you want to overwrite an existing UNIX destination file; it automatically behaves as if you answered yes. If you specify both -f and -i, /mv uses the option that appears last on the command line.

-i

When moving to a UNIX target, always prompts before overwriting an existing file, but does not overwrite the file if you do not have permission. If you specify both -f and -i, /mv uses the option that appears last on the command line.

-M

Specifies that some characters of the file name are converted when moving between a UNIX file and a 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.

-P params

Specifies the parameters that are needed to create a sequential data set if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format that the 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

Note:

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

-R (UNIX to UNIX only)

Moves a directory and all its contents (files, subdirectories, files in subdirectories, and so on). For example:

mv -R dir1 dir2

moves the entire contents of dir1 to dir2/dir1. /mv creates any directories that it needs.

See Limits and requirements when a move involves a directory that is also a mount point.

-r (UNIX to UNIX only)

Is identical to -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 moved 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. You will get an error if you specify more than one of these options.

-T is ignored when moving across UNIX file systems.

-U

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

-v

Verbose

-W seqparms=params

Specifies the parameters that are needed to create a sequential data set if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE, and SPACE in the format that the 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

Note: The 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.

-X

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

-Z

Specifies that error messages are not to be displayed when setting ACLs or the file tag on the target. The return code will be zero. mv tries to preserve the ACLs, if possible. The ACLs are not preserved if a file system does not support ACLs, or if you are moving files to MVS. For more information about file tagging, see Automatic conversion and file tagging behavior for mv.

-O u | c=codeset

Allow automatic conversion on source and target files.

-O u

If the target exists and is not empty or already tagged, /mv 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 mv behaves the same as the default. For a description of the default behavior, see Automatic conversion and file tagging behavior for mv.

If you are using /mv to move from a UNIX file to an MVS data set, if the source is a tagged text file, then it might be a candidate for automatic conversion.

If you are using /mv to move executables from or to MVS, automatic conversion is disabled for both source and target.

-O c=codeset

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

codeset can be a code set name that is 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, /mv will fail if it cannot set the tag to text or code set.

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

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

Automatic conversion and file tagging behavior for mv

Limits and requirements

General requirements are as follows:

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)', you can use quotation marks:

   "//turbo(pgm1)"  

   or escape the parenthesis:

   //turbo\(pgm1\)

   As indicated, a fully qualified name must be single-quoted (as is done within TSO). To prevent the single quotes 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 moved 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 move all members from a partitioned data set, you can specify the partitioned data set as source and a UNIX directory as target.
7. If the move involves a directory that is a mount point, you may see messages that include message FSUM6244 and message EDC5114I (Resource busy).
   • If the target directory is a mount point, the movement of a file (or files) is completed.
   • If the source directory is a mount point, the move is not completed because the source directory is considered "Resource busy." To avoid this issue, follow these steps:
     1. Unmount the source directory with /usr/sbin/unmount.
     2. Use the mkdir command to create a new directory.
     3. Mount the new directory with /usr/sbin/mount.
   

The tables that follow indicate the types of moves allowed using /mv.

Usage notes

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

Localization

Environment variables

Exit values

0

Successful completion

1

Failure due to any of the following:

• The argument had a trailing / but was not a directory.
• Inability to find file.
• Inability to open input file for reading.
• Inability to create or open output file for output.
• Read error on an input file.
• Write error on an output file.
• Input and output files identical.
• Inability to unlink input file.
• Inability to rename input file.
• Unrecoverable error when using the -r option, such as:
  • Inability to access a file.
  • Inability to read a directory.
  • Inability to remove a directory.
  • Inability to create a directory.
  • A target that is not a directory.
  • Source and destination directories identical.

2

Failure due to any of the following:

• 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.
• Out of memory to hold the data to be moved.
• Inability to create a directory to hold a target file.

Messages

Portability

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

The -R and -r options are extensions of the POSIX standard.

Related information

cp, cpio, rm