MV

PROLOG

NAME

SYNOPSIS

mv [-if] source_file target_file

mv [-if] source_file... target_dir

DESCRIPTION

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 symbolic 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 if the target did not end in a <slash>, 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 POSIX.1-2017, 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.

If the source_file operand and destination path resolve to either the same existing directory entry or different directory entries for the same existing file, then the destination path shall not be removed, and one of the following shall occur:

a.

No change is made to source_file, no error occurs, and no diagnostic is issued.

b.

No change is made to source_file, a diagnostic is issued to standard error identifying the two names, and the exit status is affected.

c.

If the source_file operand and destination path name distinct directory entries, then the source_file operand is removed, no error occurs, and no diagnostic is issued.

The mv utility shall do nothing more with the current source_file, and go on to any remaining source_files.

3.

The mv utility shall perform actions equivalent to the rename() function defined in the System Interfaces volume of POSIX.1-2017, 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 Interfaces volume of POSIX.1-2017, 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, 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. If the destination path exists and was created by a previous step, it is unspecified whether this will treated as an error or the destination path will be overwritten.

5.

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.

6.

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 characteristics 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 duplicated.

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 files being duplicated to another file system have hard links to other files, it is unspecified whether the files copied to the new file system have the hard links preserved or separate copies are created for the linked files.

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.

7.

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 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 previous occurrence of the -f option is ignored.

Specifying more than one of the -f or -i options shall not be considered an error. The last option specified shall determine the behavior of mv.  

OPERANDS

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

INPUT FILES

ENVIRONMENT VARIABLES

LANG

Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1-2017, Section 8.2, Internationalization Variables 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 keyword 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_MESSAGES category.

LC_MESSAGES

Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic messages and prompts written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS

STDOUT

STDERR

OUTPUT FILES

EXTENDED DESCRIPTION

EXIT STATUS

 0

All input files were moved successfully.

>0

An error occurred.

CONSEQUENCES OF ERRORS

The following sections are informative.  

APPLICATION USAGE

The specification ensures that mv a a will not alter the contents of file a, and allows the implementation to issue an error that a file cannot be moved onto itself. Likewise, when a and b are hard links to the same file, mv a b will not alter b, but if a diagnostic is not issued, then it is unspecified whether a is left untouched (as it would be by the rename() function) or unlinked (reducing the link count of b).  

EXAMPLES

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

For absolute clarity, paragraph (1), describing the behavior of mv when prompting for confirmation, should be interpreted in the following manner:

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 utility 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 directories, but not to a different file system. The standard developers considered that this was an annoying inconsistency, so this volume of POSIX.1-2017 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 application 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 implementations may desire more descriptive prompts than those used on historical 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 specified.

When mv is dealing with a single file system and source_file is a symbolic link, the link itself is moved as a consequence of the dependence on the rename() functionality, per the DESCRIPTION. Across file systems, this has to be made explicit.  

FUTURE DIRECTIONS

SEE ALSO

The Base Definitions volume of POSIX.1-2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines

The System Interfaces volume of POSIX.1-2017, rename()  

COPYRIGHT

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

Index

PROLOG

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

OPERANDS

STDIN

INPUT FILES

ENVIRONMENT VARIABLES

ASYNCHRONOUS EVENTS

STDOUT

STDERR

OUTPUT FILES

EXTENDED DESCRIPTION

EXIT STATUS

CONSEQUENCES OF ERRORS

APPLICATION USAGE

EXAMPLES

RATIONALE

FUTURE DIRECTIONS

SEE ALSO

COPYRIGHT