mv

MV(1POSIX)                  POSIX Programmer's Manual                 MV(1POSIX)



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.


NAME
       mv — move files

SYNOPSIS
       mv [−if] source_file target_file

       mv [−if] source_file... target_dir

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 target_file.
       This first synopsis form is assumed when the final operand does not name
       an existing directory and is not a symbolic link referring to an existing
       directory. In this case, if source_file names a non-directory file and
       target_file ends with a trailing <slash> character, mv shall treat this
       as an error and no source_file operands will be processed.

       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‐2008, 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 name 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‐2008,
           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‐2008, 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 mv utility shall conform to the Base Definitions volume of
       POSIX.1‐2008, 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
                 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
       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
                 POSIX.1‐2008, 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
       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.
       Otherwise, 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 last file status change
       timestamp of renamed files and some do not. Applications which make use
       of the last file status change timestamp may behave differently with
       respect to renamed files unless they are designed to allow for either
       behavior.

       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
       If the current directory contains only files a (of any type defined by
       the System Interfaces volume of POSIX.1‐2008), 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
       practice. It should be noted that this is consistent with the rename()
       function defined in the System Interfaces volume of POSIX.1‐2008, 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
       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‐2008 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
       None.

SEE ALSO
       cp, ln

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

       The System Interfaces volume of POSIX.1‐2008, rename()

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical
       and Electronics Engineers, Inc and The Open Group.  (This is POSIX.1-2008
       with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .



IEEE/The Open Group                   2013                            MV(1POSIX)