mv - Rename or move a file or directory

Format

mv [-fiMUv] [-F format|B|T|X] [-P params] [-W seqparms=params] [-Z] [[-O u | c=codeset] file1 file2

mv [-ACfiMUv] [-F format|B|T|X] [-S suffix] [-Z] [-O u | c=codeset] filefile ... directory

mv -Rr [-fi] [-Z] [-O u | c=codeset] directory1 directory2

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

You can move:
  • One file to another file in the working directory.
  • One file to a new file on another directory.
  • A set of directories and files to another place in your file system.
  • A UNIX file to an MVS data set.
  • An MVS data set to a file system.
  • An MVS data set to an MVS data set.

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 will be 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 - 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 dataset 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

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

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.

-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

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

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 will try 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.

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

When 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

The following tables describe the behavior of file tagging and automatic conversion for various source and target scenarios depending on whether the -O option is specified on the mv command.
Table 1. Automatic conversion and file tagging behavior for mv: Moving files to files
  Default (without -O option) With -O u option With -O c=codeset option
If the target file system supports setting file tags… If the target file system does not support setting file tags (such as NFS)…
File tagging Target file is tagged the same as the source file.
  • An existing target's tag is unchanged.
  • A new target is created with a tag according to the file system's attributes (The MOUNT parameter can specify TAG).
The target's tag is not changed.

The source or target file is a candidate for automatic conversion when its txtflag is tagged TEXT.

The target's txtflag is set to TEXT and its code set is set to codeset.
Automatic conversion Disabled for source and target files Allowed for source and target files
Table 2. Automatic conversion and file tagging behavior for mv: Moving files to MVS data sets
  Default (without -O option) With -O u option With -O c=codeset option
If the SOURCE is text or binary:
File tagging Not applicable for target data set
Automatic conversion Disabled for source file Allowed for source file

The source file is a candidate for automatic conversion when its txtflag is tagged TEXT.

Disabled for source file
If the SOURCE is executable:
File tagging Not applicable for target data set
Automatic conversion Disabled for source file

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.
MVS data set naming limitations:
  • Data set names can only contain uppercase alphabetic characters (A-Z). Lowercase characters will be converted to uppercase during any moves to MVS data sets.
  • Data set names can contain numeric characters 0-9 and special characters @, #, and $.
  • Data set names cannot begin with a numeric character.
  • A data set member name cannot be more than 8 characters. If a file name is longer than 8 characters or uses characters that are not allowed in an MVS data set name, the file is not moved. You can use the -C option to truncate names to 8 characters.
Limitations: UNIX to MVS data set:
  1. If you specify a sequential MVS data set that is in undefined record format, the file is moved as binary.
  2. If you specify a PDSE that is in undefined record format, the first file successfully moved determines in what format files will be moved. Note that PDSE does not allow mixture. So if the first successfully moved file is an executable, the PDSE will have program objects only and all other files will fail. However, if the first file is data, then all files are moved as binary.
  3. If you specify a PDS that is in undefined record format, UNIX executables are saved as PDS load modules. All other files are moved as binary.
  4. If you specify an MVS data set that is either in variable length or fixed record length and you have not set the file format, text files are moved as text, binaries as binary, and executables as binary. (IBM-1047 end-of-line delimiters are detected in the data)
  5. If you set the file format, the set value is used to determine if data is binary, text, or record file format.
Limitations: MVS data set to UNIX:
  1. If an UNIX file does not exist, one is created using 666 mode value, whether the data to be copied is binary or text:
    666 mode value:  owner(rw-)  group(rw-)  other(rw-)
    If the data to be copied is a shell script or executable residing in a PDS or PDSE with undefined record format, the UNIX file is created using 777 mode value:
    777 mode value:  owner(rwx)  group(rwx)  other(rwx)
  2. If a UNIX file exists and the file format is set, mv moves the file as that format. Otherwise,
    • Load modules (PDS) are stored as UNIX executables and program objects (PDSE) are moved since they are the same as executables;
    • Data within data sets of undefined record format are moved as binary if the data is not a program object or load module;
    • Data found within data sets of fixed length or variable record length are moved as text. (IBM-1047 end-of-line delimiters are detected in the data
Limitations: MVS to MVS:
  1. Options -A, -C, -f, and -S are ignored.
  2. If target and source are in undefined record format (and neither is a sequential data set), mv will attempt to move the data as a load module. If that fails, then mv will move the data as binary.
  3. If target and source are in undefined record format and either is a sequential data set, mv moves the data as binary.
  4. If the source has a fixed or variable record length and the target is in undefined record format, mv moves the data as binary.
  5. If the source is in undefined record format and the target has a fixed or variable record length, mv moves the data as binary.
  6. If both source and target are in fixed or variable record length, mv moves the data as text.
Limitations: Moving executables into a PDS:
  1. A PDS cannot store load modules that incorporate program management features.
  2. c89, by default, produces objects using the highest level of program management.
  3. If you plan on moving a load module to a PDS, you can use a prelinker, which produces output compatible with linkage editor. Linkage editor generated output can always be stored in a PDS.
Table 3 is a quick reference for determining the correct use of options with mv.
Table 3. Options allowed for mv: File to File and File ... (multiple files) to directory
Source/target Options allowed Options ignored Options failed
UNIX file/UNIX file Ffi ABCMPSTUX  
UNIX file/Sequential data set BFiPT ACfMSU X
UNIX file/PDS or PDSE member BFiTX ACfMPSU  
Sequential data set/UNIX file BFfiTU ACMPS X
Sequential data set/sequential data set BFiPT ACfMSU X
Sequential data set/PDS or PDSE member BFiT ACfMPSU X
PDS or PDSE member/UNIX file BFfiTUX ACMPS  
PDS or PDSE member/sequential data set BFiPT ACfMSU X
PDS or PDSE member/PDS or PDSE member BFiTX ACfMPSU  
UNIX file/UNIX directory Fi ABCFMPSTUX  
PDSE or PDSE member/UNIX directory BFfiMSTUX ACP  
UNIX file/partitioned data set ABCFiMSTX fPU  
PDS or PDSE member/partitioned data set BFiTX ACfMPSU  
UNIX directory/UNIX directory fi ABCFMPSTUX  
Partitioned data set/UNIX directory ABCFfiMSTUX P  

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

Table 4. Moves allowed for mv: File to File
Source Target Allowed
UNIX file, sequential data set, or partitioned data set member UNIX file, sequential data set, or partitioned data set member Yes
UNIX directory (dir) UNIX directory (dir2 exists) Yes (Results will be found in dir2/dir1/ ..).
UNIX directory (dir) UNIX directory (dir2 does not exist) Yes (Results will be found in dir2/...).
Partitioned data set UNIX directory (dir). Results in each member of data set are moved to dir. Yes
UNIX directory Partitioned data set No
Partitioned data set Partitioned data set No
UNIX file, UNIX directory, or partitioned data set member UNIX directory Yes
Partitioned data set member Partitioned data set (must exist) Yes
Table 5. Moves allowed for mv: File... (multiple files) to directory
Source Target Allowed
Any combination of UNIX file or partitioned data set member UNIX directory or partitioned data set Yes
Any combination of UNIX directory, partitioned data set, sequential data set Partitioned data set No
Sequential data set UNIX directory No
Any combination of UNIX directory, UNIX file, partitioned data set, partitioned data set member UNIX directory Yes

Examples

  1. To specify -P params for a non-existing sequential target:
    mv -P "RECFM=U,space=(500,100)" file "//'turbo.gammalib'"
    This mv command is equivalent to:
     mv -W "seqparms='RECFM=U,space=(500,100)'" file "//'turbo.gammalib'"
  2. To move file f1 to a fully qualified sequential data set 'turbo.gammalib' and treat it as a binary:
    mv -F bin f1 "//'turbo.gammalib'"
  3. To move all members from a fully qualified PDS 'turbo.gammalib' to an existing UNIX directory dir:
    mv "//turbo.gammalib'" dir
  4. To drop .c suffixes before moving all files in UNIX directory dir to an existing PDS 'turbo.gammalib':
    mv -S d=.c dir/* "//'turbo.gammalib'"

Usage notes

You cannot move a PDS or PDS/E data set member to a UNIX file with the mv command if the PDS or PDS/E data set has already been opened by another user or job. For example, if the data set posix.dest.pdse is being viewed by ISPF browse, the following mv command will fail:
mv "//'posix.test.pdse(member)'" test_file
UNIX to MVS:
  1. To move from UNIX to a partitioned data set, you must allocate the data set before doing the mv.
  2. If an MVS data set does not exist, mv will allocate a new sequential data set of variable record format.
  3. For text files, all <newline> characters are stripped during the move. Each line in the file ending with a <newline> character is moved into a record of the MVS data set. If text file format is specified or exists for the source file, that file format will be used for end-of-line delimiter instead of <newline>. Note that mv looks for IBM-1047 end-of-line delimiters in data.

    You cannot move a text file to an MVS data set that has an undefined record format:

    • For an MVS data set in fixed record format, any line moved longer than the record size will cause mv to fail with a displayed error message and error code. If the line is shorter than the record size, the record is padded with blanks.
    • For an MVS data set in variable record format: Any line moved longer than the largest record size will cause mv to fail with a displayed error message and error code. The record length is set to the length of the line.
  4. For binary files, all moved data is preserved:
    • For an MVS data set in fixed record format, data is cut into chunks of size equal to the record length. Each chunk is put into one record. The last record is padded with blanks.
    • For an MVS data set in variable record format, data is cut into chunks of size equal to the largest record length. Each chunk is put into one record. The length of the last record is equal to length of the data left.
    • For an MVS data set in undefined record format, data is cut into chunks of size equal to the block size. Each chunk is put into one record. The length of the last record is equal to the length of the data left.
  5. For load modules, the partitioned data set specified must be in undefined record format otherwise the executable will not be moved.
  6. If more than one file name is the same, the file is overwritten on each subsequent move.
  7. If a UNIX file name contains characters that are not allowed in an MVS data set, it will not be moved. If the UNIX file name has more than 8 characters, it cannot be moved to an MVS data set member. (See the -ACMS options for converting file names.)
  8. You are not allowed to move files into data sets with spanned records.
  9. PDSE cannot have a mixture of program objects and data members. PDS allows mixing, but it is not recommended.
  10. Special files such as external links and FIFO will not be moved to MVS data sets. However, you can move character special files to MVS data sets.
  11. If a file is a symbolic link, /mv will move the resolved file, not the link itself.
  12. UNIX file attributes are lost when moving to MVS. If you want to preserve file attributes, you should use the pax utility.
MVS to UNIX:
  1. If the target UNIX file exists, the new data overwrites the existing data. The mode of the file is unchanged (except the S_ISUID and S_ISGID bits are turned off).
  2. If the specified UNIX file does not exist, it will be created using a 666 mode value whether the data is binary or text (this is subject to umask). If the data to be moved is a shell script or executable, the UNIX file will be created with a 777 mode value (also subject to umask).
  3. For an MVS data set in variable record format RECFM(VB) or undefined record format RECFM(U), trailing blanks are preserved when moving from MVS to UNIX. For an MVS data set in fixed record format, trailing blanks are not preserved when moving from MVS to UNIX.
  4. When you move MVS data sets to text files in the z/OS® UNIX file system, a <newline> character is appended to the end of each record. If trailing blanks exist in the record, the <newline> character is appended after the trailing blanks. If the file format option is specified or the target file has the file format set, that file format is used as the end-of-line delimiter instead of a <newline> character.
  5. When you move MVS data sets to UNIX binary files, the <newline> character is not appended to the record.
  6. You cannot use /mv to move data sets with spanned record lengths.
  7. Due to an z/OS XL C/C++ run-time restriction, when moving a file from a file system to an MVS sequential data set with the same name and case, you need to prefix the file in the file system with "./". For example:
    mv ./SMPL.DATA  "//''SMPL.DATA''"

Localization

/mv uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_COLLATE
  • LC_CTYPE
  • LC_MESSAGES
  • LC_SYNTAX
  • NLSPATH

See Localization for more information.

Environment variables

/mv uses the following environment variable when moving records to or from MVS data sets:
_EDC_ZERO_RECLEN
If set to Y before calling /mv, an empty record is treated as a single newline character and is not ignored. Also, a single newline is written to the file as an empty record, and a single blank will be represented by "\n". If you do not set this environment variable when moving records, then the string "\n" is moved the same way as the string "\n": both are read and written as "\n", where "\n" indicates that z/OS XL C/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 the output are read back as blanks, and any empty (zero-length) records are ignored on input.

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

Possible error messages include:
cannot allocate target string
/mv has no space to hold the name of the target file. Try to free some memory to give /mv more space.
filename?
You are attempting to move a file, but there is already a file with the target name and the file is read-only. To write over the existing file, type y and press <Enter>. If you do not want to write over the existing file, type n and press <Enter>.
source name and target name are identical
The source and the target are actually the same file (for example, because of links). In this case, /mv does nothing.
unreadable directory name
/mv cannot read the specified directory; for example, because you do not have appropriate permissions.

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