mv(P)                                                     mv(P)





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  desti-
       nation 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  path-
       name  component of the source_file.  This second form is
       assumed when the final operand names an existing  direc-
       tory.

       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:

       If  the  destination  path  exists, the -f option is not
       specified, and either of  the  following  conditions  is
       true: <ol type="a">

       The  permissions  of  the destination path do not permit
       writing and the standard input is a terminal.

       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  cur-
       rent   source_file   and   go   on   to   any  remaining
       source_files.

       The mv utility shall perform actions equivalent  to  the
       rename()  function defined in the System Interfaces vol-
       ume of IEEE Std 1003.1-2001, called with  the  following
       arguments: <ol type="a">

       The source_file operand is used as the old argument.

       The destination path is used as the new argument.

       If this succeeds, mv shall do nothing more with the cur-
       rent  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.

       If the destination path exists, and it is a file of type
       directory  and  source_file is not a file of type direc-
       tory, 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,  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.

       The file hierarchy rooted in source_file shall be dupli-
       cated  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 characteris-
       tics of each file in the file hierarchy shall be  dupli-
       cated:

              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 stan-
       dard  error, but this failure shall not cause mv to mod-
       ify its exit status.

       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 sec-
       tion. 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 internationaliza-
              tion  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 cate-
              gories.)

       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 collat-
              ing elements used in the extended regular expres-
              sion  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  cate-
              gory.

       LC_MESSAGES
              Determine the locale for the processing of affir-
              mative 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 mes-
       sages.

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 desti-
       nation 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  histori-
       cal  practice in that they required that when the desti-
       nation 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  his-
       torical  practice.  It should be noted that this is con-
       sistent 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 destina-
       tion 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 differ-
       ent 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 direc-
       tories 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 sys-
       tems,  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 unspeci-
       fied. Only the general nature of the contents of prompts
       are  specified  because  implementations may desire more
       descriptive prompts than those used on historical imple-
       mentations.  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() func-
       tionality,  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 Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute 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.open-
       group.org/unix/online.html .



POSIX                         2003                        mv(P)
