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] file …file … 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 till 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 –F specified
will be 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 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 translated
when moving between a UNIX file and a data set member.
Characters are translated as follows:
- _ (underscore) in UNIX is translated to @ in MVS dataset members and vice versa.
- . (period) in UNIX is translated to # in MVS dataset members and vice versa.
- – (dash) in UNIX is translated to $ in MVS dataset members and vice versa.
- –P params
- Specifies the parameters 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() argument 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.
- –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
-
–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.
Note: –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 file names lowercase.
- –v
- Verbose
- -W seqparms=params
- Specifies the parameters 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 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.
Note: 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 Note: 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:
- 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
- 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 quotes:
"//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.
- 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.
- If source is an MVS data
set and target is a UNIX directory, the UNIX directory
must exist.
- You cannot have a UNIX directory, partitioned data
set, or sequential data set as source if the target is a partitioned
data set.
- 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 are as follows:
- 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. The limitations are as follows:
- If you specify a sequential MVS data
set that is in undefined record format, the file is moved as binary.
- 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.
- 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.
- 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)
- 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. The limitations are as follows:
- 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)
- 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. The limitations are as follows:
- Options –A, –C, –f,
and –S are ignored.
- 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.
- If target and source are in undefined record format and either
is a sequential data set, mv moves the data
as binary.
- If the source has a fixed or variable record length and the target
is in undefined record format, mv moves
the data as binary.
- If the source is in undefined record format and the target has
a fixed or variable record length, mv moves
the data as binary.
- If both source and target are in fixed or variable record length, mv moves
the data as text.
Limitations: Moving executables into a PDS. The limitations
are as follows:
- A PDS cannot store load modules that incorporate program management
features.
- c89, by default, produces objects using
the highest level of program management.
- 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.
The following table 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 directorySource/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 kind of moves allowed
using mv.
Table 4. Moves allowed for mv: File to FileSource |
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 directorySource |
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
- To specify –P params for
a nonexisting 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'"
- 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'"
- To move all members from a fully qualified PDS 'turbo.gammalib' to
an existing UNIX directory dir:
mv "//turbo.gammalib'" dir
- 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
For UNIX to MVS:
- To move from UNIX to a partitioned data set,
you must allocate the data set before doing the mv.
- If an MVS data set does not
exist, mv will allocate a new sequential
data set of variable record format.
- 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 already 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. Record length is set to the length of the
line.
- 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.
- For load modules, the partitioned data set specified must be in
undefined record format otherwise the executable will not be moved.
- If more than one file name is the same, the file is overwritten
on each subsequent move.
- 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.)
- You are not allowed to move files into data sets with spanned
records.
- PDSE cannot have a mixture of program objects and data members.
PDS allows mixing, but it is not recommended.
- 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.
- If a file is a symbolic link, mv will
move the resolved file, not the link itself.
- UNIX file attributes are lost when moving to MVS. If you want to preserve file
attributes, you should use the pax utility.
For MVS to UNIX:
- 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).
- 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).
- 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.
- 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.
- When you move MVS data sets
to UNIX binary files, the <newline> character
is not appended to the record.
- You cannot use mv to move data sets
with spanned record lengths.
- 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. If you really want
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