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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       mv -- move files

SSYYNNOOPPSSIISS
       mv [[-if]] _s_o_u_r_c_e___f_i_l_e _t_a_r_g_e_t___f_i_l_e

       mv [[-if]] _s_o_u_r_c_e___f_i_l_e... _t_a_r_g_e_t___d_i_r

DDEESSCCRRIIPPTTIIOONN
       In the first synopsis form, the _m_v utility shall move the file named by
       the _s_o_u_r_c_e___f_i_l_e operand to the destination specified by the
       _t_a_r_g_e_t___f_i_l_e.  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 _s_o_u_r_c_e___f_i_l_e names
       a non-directory file and _t_a_r_g_e_t___f_i_l_e ends with a trailing <slash>
       character, _m_v shall treat this as an error and no _s_o_u_r_c_e___f_i_l_e operands
       will be processed.

       In the second synopsis form, _m_v shall move each file named by a
       _s_o_u_r_c_e___f_i_l_e operand to a destination file in the existing directory
       named by the _t_a_r_g_e_t___d_i_r operand, or referenced if _t_a_r_g_e_t___d_i_r is a
       symbolic link referring to an existing directory. The destination path
       for each _s_o_u_r_c_e___f_i_l_e 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 _s_o_u_r_c_e___f_i_l_e.  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 _s_o_u_r_c_e___f_i_l_e the following steps shall be taken:

        1. If the destination path exists, the --ff 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 --ii option is specified.

           the _m_v utility shall write a prompt to standard error and read a
           line from standard input. If the response is not affirmative, _m_v
           shall do nothing more with the current _s_o_u_r_c_e___f_i_l_e and go on to any
           remaining _s_o_u_r_c_e___f_i_l_es.

        2. If the _s_o_u_r_c_e___f_i_l_e 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 _s_o_u_r_c_e___f_i_l_e, no error occurs, and no
               diagnostic is issued.

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

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

           The _m_v utility shall do nothing more with the current _s_o_u_r_c_e___f_i_l_e,
           and go on to any remaining _s_o_u_r_c_e___f_i_l_es.

        3. The _m_v utility shall perform actions equivalent to the _r_e_n_a_m_e()
           function defined in the System Interfaces volume of POSIX.1-2017,
           called with the following arguments:

            a. The _s_o_u_r_c_e___f_i_l_e operand is used as the _o_l_d argument.

            b. The destination path is used as the _n_e_w argument.

           If this succeeds, _m_v shall do nothing more with the current
           _s_o_u_r_c_e___f_i_l_e and go on to any remaining _s_o_u_r_c_e___f_i_l_es.  If this fails
           for any reasons other than those described for the _e_r_r_n_o [[EEXXDDEEVV]] in
           the System Interfaces volume of POSIX.1-2017, _m_v shall write a
           diagnostic message to standard error, do nothing more with the
           current _s_o_u_r_c_e___f_i_l_e, and go on to any remaining _s_o_u_r_c_e___f_i_l_es.

        4. If the destination path exists, and it is a file of type directory
           and _s_o_u_r_c_e___f_i_l_e is not a file of type directory, or it is a file
           not of type directory and _s_o_u_r_c_e___f_i_l_e is a file of type directory,
           _m_v shall write a diagnostic message to standard error, do nothing
           more with the current _s_o_u_r_c_e___f_i_l_e, and go on to any remaining
           _s_o_u_r_c_e___f_i_l_es.  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, _m_v shall attempt to remove it. If
           this fails for any reason, _m_v shall write a diagnostic message to
           standard error, do nothing more with the current _s_o_u_r_c_e___f_i_l_e, and
           go on to any remaining _s_o_u_r_c_e___f_i_l_es.

        6. The file hierarchy rooted in _s_o_u_r_c_e___f_i_l_e shall be duplicated as a
           file hierarchy rooted in the destination path. If _s_o_u_r_c_e___f_i_l_e 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 _m_v 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, _m_v
           shall write a diagnostic message to standard error, do nothing more
           with the current _s_o_u_r_c_e___f_i_l_e, and go on to any remaining
           _s_o_u_r_c_e___f_i_l_es.

           If the duplication of the file characteristics fails for any
           reason, _m_v shall write a diagnostic message to standard error, but
           this failure shall not cause _m_v to modify its exit status.

        7. The file hierarchy rooted in _s_o_u_r_c_e___f_i_l_e shall be removed. If this
           fails for any reason, _m_v shall write a diagnostic message to the
           standard error, do nothing more with the current _s_o_u_r_c_e___f_i_l_e, and
           go on to any remaining _s_o_u_r_c_e___f_i_l_es.

OOPPTTIIOONNSS
       The _m_v utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

       --ff        Do not prompt for confirmation if the destination path
                 exists. Any previous occurrence of the --ii option is ignored.

       --ii        Prompt for confirmation if the destination path exists. Any
                 previous occurrence of the --ff option is ignored.

       Specifying more than one of the --ff or --ii options shall not be
       considered an error. The last option specified shall determine the
       behavior of _m_v.

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _s_o_u_r_c_e___f_i_l_e
                 A pathname of a file or directory to be moved.

       _t_a_r_g_e_t___f_i_l_e
                 A new pathname for the file or directory being moved.

       _t_a_r_g_e_t___d_i_r
                 A pathname of an existing directory into which to move the
                 input files.

SSTTDDIINN
       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.

IINNPPUUTT FFIILLEESS
       The input files specified by each _s_o_u_r_c_e___f_i_l_e operand can be of any
       file type.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _m_v:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_O_L_L_A_T_E
                 Determine the locale for the behavior of ranges, equivalence
                 classes, and multi-character collating elements used in the
                 extended regular expression defined for the yyeesseexxpprr locale
                 keyword in the _L_C___M_E_S_S_A_G_E_S category.

       _L_C___C_T_Y_P_E  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 yyeesseexxpprr locale
                 keyword in the _L_C___M_E_S_S_A_G_E_S category.

       _L_C___M_E_S_S_A_G_E_S
                 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.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       Not used.

SSTTDDEERRRR
       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.

OOUUTTPPUUTT FFIILLEESS
       The output files may be of any file type.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    All input files were moved successfully.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       If the copying or removal of _s_o_u_r_c_e___f_i_l_e is prematurely terminated by a
       signal or error, _m_v may leave a partial copy of _s_o_u_r_c_e___f_i_l_e at the
       source or destination. The _m_v utility shall not modify both _s_o_u_r_c_e___f_i_l_e
       and the destination path simultaneously; termination at any point shall
       leave either _s_o_u_r_c_e___f_i_l_e or the destination path complete.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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 _m_v aa aa will not alter the contents of
       file aa, and allows the implementation to issue an error that a file
       cannot be moved onto itself. Likewise, when aa and bb are hard links to
       the same file, _m_v aa bb will not alter bb, but if a diagnostic is not
       issued, then it is unspecified whether aa is left untouched (as it would
       be by the _r_e_n_a_m_e() function) or unlinked (reducing the link count of
       bb).

EEXXAAMMPPLLEESS
       If the current directory contains only files aa (of any type defined by
       the System Interfaces volume of POSIX.1-2017), bb (also of any type),
       and a directory cc:


           mv a b c
           mv c d

       results with the original files aa and bb residing in the directory dd in
       the current directory.

RRAATTIIOONNAALLEE
       Early proposals diverged from the SVID and BSD historical practice in
       that they required that when the destination path exists, the --ff option
       is not specified, and input is not a terminal, _m_v fails. This was done
       for compatibility with _c_p.  The current text returns to historical
       practice. It should be noted that this is consistent with the _r_e_n_a_m_e()
       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 _m_v 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 --ii 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 _m_v deletes all existing
       destination paths without prompting, even when --ii is specified; this is
       inconsistent with the behavior of the 4.3 BSD _c_p 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 --ii is a
       request for interaction, so when the destination path exists, the
       utility takes instructions from whatever responds to standard input.

       The _r_e_n_a_m_e() function is able to move directories within the same file
       system. Some historical versions of _m_v 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 --RR 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 _r_e_n_a_m_e() function
       were preserved as much as possible. For example, _m_v is not permitted to
       ``rename'' files to or from directories, even though they might be
       empty and removable.

       Historic implementations of _m_v 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 --ff
       option or using the --ii option relies on the system to provide the most
       suitable dialog directly with the user, based on the behavior
       specified.

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

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_p, _l_n

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

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

CCOOPPYYRRIIGGHHTT
       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(1)
