Provided by: manpages-posix_2.16-1_all bug

NAME

       mv - move files

SYNOPSIS

       mv [-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  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 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, 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 Interfaces volume of IEEE Std 1003.1-2001, 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.

        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
           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 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 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  IEEE Std 1003.1-2001, 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 for the processing of affirmative  responses  that  should  be
              used  to  affect the format and contents of diagnostic 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.  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 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 practice. 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 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 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 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 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 .