MV(1P) POSIX Programmer's Manual MV(1P)PROLOG
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.
NAMEmv - move files
SYNOPSISmv [-fi] source_file target_file
mv [-fi] source_file... target_file
DESCRIPTION
In the first synopsis form, the mv utility shall move the file named by
the source_file operand to the destination specified by the tar‐
get_file. This first synopsis form is assumed when the final operand
does not name an existing directory and is not a symbolic link refer‐
ring to an existing directory.
In the second synopsis form, mv shall move each file named by a
source_file operand to a destination file in the existing directory
named by the target_dir operand, or referenced if target_dir is a sym‐
bolic link referring to an existing directory. The destination path for
each source_file shall be the concatenation of the target directory, a
single slash character, and the last pathname component of the
source_file. This second form is assumed when the final operand names
an existing directory.
If any operand specifies an existing file of a type not specified by
the System Interfaces volume of IEEE Std 1003.1-2001, the behavior is
implementation-defined.
For each source_file the following steps shall be taken:
1. If the destination path exists, the -f option is not specified, and
either of the following conditions is true:
a. The permissions of the destination path do not permit writing
and the standard input is a terminal.
b. The -i option is specified.
the mv utility shall write a prompt to standard error and read a line
from standard input. If the response is not affirmative, mv shall do
nothing more with the current source_file and go on to any remaining
source_files.
2. The mv utility shall perform actions equivalent to the rename()
function defined in the System Interfaces volume of
IEEE Std 1003.1-2001, called with the following arguments:
a. The source_file operand is used as the old argument.
b. The destination path is used as the new argument.
If this succeeds, mv shall do nothing more with the current source_file
and go on to any remaining source_files. If this fails for any reasons
other than those described for the errno [EXDEV] in the System Inter‐
faces volume of IEEE Std 1003.1-2001, mv shall write a diagnostic mes‐
sage to standard error, do nothing more with the current source_file,
and go on to any remaining source_files.
3. If the destination path exists, and it is a file of type directory
and source_file is not a file of type directory, or it is a file
not of type directory and source_file is a file of type directory,
mv shall write a diagnostic message to standard error, do nothing
more with the current source_file, and go on to any remaining
source_files.
4. If the destination path exists, mv shall attempt to remove it. If
this fails for any reason, mv shall write a diagnostic message to
standard error, do nothing more with the current source_file, and
go on to any remaining source_files.
5. The file hierarchy rooted in source_file shall be duplicated as a
file hierarchy rooted in the destination path. If source_file or
any of the files below it in the hierarchy are symbolic links, the
links themselves shall be duplicated, including their contents,
rather than any files to which they refer. The following charac‐
teristics of each file in the file hierarchy shall be duplicated:
* The time of last data modification and time of last access
* The user ID and group ID
* The file mode
If the user ID, group ID, or file mode of a regular file cannot be
duplicated, the file mode bits S_ISUID and S_ISGID shall not be dupli‐
cated.
When files are duplicated to another file system, the implementation
may require that the process invoking mv has read access to each file
being duplicated.
If the duplication of the file hierarchy fails for any reason, mv shall
write a diagnostic message to standard error, do nothing more with the
current source_file, and go on to any remaining source_files.
If the duplication of the file characteristics fails for any reason, mv
shall write a diagnostic message to standard error, but this failure
shall not cause mv to modify its exit status.
6. The file hierarchy rooted in source_file shall be removed. If this
fails for any reason, mv shall write a diagnostic message to the
standard error, do nothing more with the current source_file, and
go on to any remaining source_files.
OPTIONS
The mv utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
-f Do not prompt for confirmation if the destination path exists.
Any previous occurrence of the -i option is ignored.
-i Prompt for confirmation if the destination path exists. Any pre‐
vious occurrence of the -f option is ignored.
Specifying more than one of the -f or -i options shall not be consid‐
ered an error. The last option specified shall determine the behavior
of mv.
OPERANDS
The following operands shall be supported:
source_file
A pathname of a file or directory to be moved.
target_file
A new pathname for the file or directory being moved.
target_dir
A pathname of an existing directory into which to move the input
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.
INPUT FILES
The input files specified by each source_file operand can be of any
file type.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of mv:
LANG Provide a default value for the internationalization variables
that are unset or null. (See the Base Definitions volume of
IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
ables 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.
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 key‐
word 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),
the behavior of character classes used in the extended regular
expression defined for the yesexpr locale keyword in the LC_MES‐
SAGES category.
LC_MESSAGES
Determine the locale for the processing of affirmative responses
that should be used to affect the format and contents of diag‐
nostic messages written to standard error.
NLSPATH
Determine the location of message catalogs for the processing of
LC_MESSAGES .
ASYNCHRONOUS EVENTS
Default.
STDOUT
Not used.
STDERR
Prompts shall be written to the standard error under the conditions
specified in the DESCRIPTION section. The prompts shall contain the
destination pathname, but their format is otherwise unspecified. Oth‐
erwise, the standard error shall be used only for diagnostic messages.
OUTPUT FILES
The output files may be of any file type.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 All input files were moved successfully.
>0 An error occurred.
CONSEQUENCES OF ERRORS
If the copying or removal of source_file is prematurely terminated by a
signal or error, mv may leave a partial copy of source_file at the
source or destination. The mv utility shall not modify both source_file
and the destination path simultaneously; termination at any point shall
leave either source_file or the destination path complete.
The following sections are informative.
APPLICATION USAGE
Some implementations mark for update the st_ctime field of renamed
files and some do not. Applications which make use of the st_ctime
field may behave differently with respect to renamed files unless they
are designed to allow for either behavior.
EXAMPLES
If the current directory contains only files a (of any type defined by
the System Interfaces volume of IEEE Std 1003.1-2001), b (also of any
type), and a directory c:
mv a b c
mv c d
results with the original files a and b residing in the directory d in
the current directory.
RATIONALE
Early proposals diverged from the SVID and BSD historical practice in
that they required that when the destination path exists, the -f option
is not specified, and input is not a terminal, mv fails. This was done
for compatibility with cp. The current text returns to historical prac‐
tice. It should be noted that this is consistent with the rename()
function defined in the System Interfaces volume of
IEEE Std 1003.1-2001, which does not require write permission on the
target.
For absolute clarity, paragraph (1), describing the behavior of mv when
prompting for confirmation, should be interpreted in the following man‐
ner:
if (exists AND (NOT f_option) AND
((not_writable AND input_is_terminal) OR i_option))
The -i option exists on BSD systems, giving applications and users a
way to avoid accidentally unlinking files when moving others. When the
standard input is not a terminal, the 4.3 BSD mv deletes all existing
destination paths without prompting, even when -i is specified; this is
inconsistent with the behavior of the 4.3 BSD cp utility, which always
generates an error when the file is unwritable and the standard input
is not a terminal. The standard developers decided that use of -i is a
request for interaction, so when the destination path exists, the util‐
ity takes instructions from whatever responds to standard input.
The rename() function is able to move directories within the same file
system. Some historical versions of mv have been able to move directo‐
ries, but not to a different file system. The standard developers con‐
sidered that this was an annoying inconsistency, so this volume of
IEEE Std 1003.1-2001 requires directories to be able to be moved even
across file systems. There is no -R option to confirm that moving a
directory is actually intended, since such an option was not required
for moving directories in historical practice. Requiring the applica‐
tion to specify it sometimes, depending on the destination, seemed just
as inconsistent. The semantics of the rename() function were preserved
as much as possible. For example, mv is not permitted to "rename" files
to or from directories, even though they might be empty and removable.
Historic implementations of mv did not exit with a non-zero exit status
if they were unable to duplicate any file characteristics when moving a
file across file systems, nor did they write a diagnostic message for
the user. The former behavior has been preserved to prevent scripts
from breaking; a diagnostic message is now required, however, so that
users are alerted that the file characteristics have changed.
The exact format of the interactive prompts is unspecified. Only the
general nature of the contents of prompts are specified because imple‐
mentations may desire more descriptive prompts than those used on his‐
torical implementations. Therefore, an application not using the -f
option or using the -i option relies on the system to provide the most
suitable dialog directly with the user, based on the behavior speci‐
fied.
When mv is dealing with a single file system and source_file is a sym‐
bolic link, the link itself is moved as a consequence of the dependence
on the rename() functionality, per the DESCRIPTION. Across file sys‐
tems, this has to be made explicit.
FUTURE DIRECTIONS
None.
SEE ALSO
cp, ln, the System Interfaces volume of IEEE Std 1003.1-2001, rename()COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .
IEEE/The Open Group 2003 MV(1P)
