mv(1p) — Linux manual page

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

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

PROLOG         top

       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         top

       mv — move files

SYNOPSIS         top

       mv [-if] source_file target_file

       mv [-if] source_file... target_dir

DESCRIPTION         top

       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‐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         top

       The mv utility shall conform to the Base Definitions volume of
       POSIX.1‐2017, 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         top

       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         top

       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         top

       The input files specified by each source_file operand can be of
       any file type.

ENVIRONMENT VARIABLES         top

       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‐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         top

       Default.

STDOUT         top

       Not used.

STDERR         top

       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         top

       The output files may be of any file type.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       The following exit values shall be returned:

        0    All input files were moved successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       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         top

       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         top

       If the current directory contains only files a (of any type
       defined by the System Interfaces volume of POSIX.1‐2017), 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         top

       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‐2017, 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‐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         top

       None.

SEE ALSO         top

       cp(1p), ln(1p)

       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(3p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic
       form from IEEE Std 1003.1-2017, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The
       Open Group Base Specifications Issue 7, 2018 Edition, Copyright
       (C) 2018 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 .

       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               2017                            MV(1P)

Pages that refer to this page: cp(1p)find(1p)