1MV(1P)                     POSIX Programmer's Manual                    MV(1P)
2
3
4

PROLOG

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

NAME

12       mv — move files
13

SYNOPSIS

15       mv [-if] source_file target_file
16
17       mv [-if] source_file... target_dir
18

DESCRIPTION

20       In the first synopsis form, the mv utility shall move the file named by
21       the  source_file  operand  to  the  destination  specified  by the tar‐
22       get_file.  This first synopsis form is assumed when the  final  operand
23       does  not  name an existing directory and is not a symbolic link refer‐
24       ring to an existing directory. In this case,  if  source_file  names  a
25       non-directory file and target_file ends with a trailing <slash> charac‐
26       ter, mv shall treat this as an error and no source_file  operands  will
27       be processed.
28
29       In  the  second  synopsis  form,  mv  shall  move  each file named by a
30       source_file operand to a destination file  in  the  existing  directory
31       named  by the target_dir operand, or referenced if target_dir is a sym‐
32       bolic link referring to an existing directory. The destination path for
33       each  source_file shall be the concatenation of the target directory, a
34       single <slash> character if the target did not end in  a  <slash>,  and
35       the  last  pathname  component of the source_file.  This second form is
36       assumed when the final operand names an existing directory.
37
38       If any operand specifies an existing file of a type  not  specified  by
39       the System Interfaces volume of POSIX.1‐2017, the behavior is implemen‐
40       tation-defined.
41
42       For each source_file the following steps shall be taken:
43
44        1. If the destination path exists, the -f option is not specified, and
45           either of the following conditions is true:
46
47            a. The  permissions  of the destination path do not permit writing
48               and the standard input is a terminal.
49
50            b. The -i option is specified.
51
52           the mv utility shall write a prompt to standard error  and  read  a
53           line  from  standard  input. If the response is not affirmative, mv
54           shall do nothing more with the current source_file and go on to any
55           remaining source_files.
56
57        2. If  the  source_file operand and destination path resolve to either
58           the same existing directory entry or  different  directory  entries
59           for  the same existing file, then the destination path shall not be
60           removed, and one of the following shall occur:
61
62            a. No change is made to source_file, no error occurs, and no diag‐
63               nostic is issued.
64
65            b. No  change  is  made  to source_file, a diagnostic is issued to
66               standard error identifying the two names, and the  exit  status
67               is affected.
68
69            c. If  the  source_file operand and destination path name distinct
70               directory entries, then the source_file operand is removed,  no
71               error occurs, and no diagnostic is issued.
72
73           The  mv utility shall do nothing more with the current source_file,
74           and go on to any remaining source_files.
75
76        3. The mv utility shall perform actions  equivalent  to  the  rename()
77           function  defined  in the System Interfaces volume of POSIX.1‐2017,
78           called with the following arguments:
79
80            a. The source_file operand is used as the old argument.
81
82            b. The destination path is used as the new argument.
83
84           If this succeeds,  mv  shall  do  nothing  more  with  the  current
85           source_file and go on to any remaining source_files.  If this fails
86           for any reasons other than those described for the errno [EXDEV] in
87           the  System  Interfaces  volume  of  POSIX.1‐2017, mv shall write a
88           diagnostic message to standard error, do nothing more with the cur‐
89           rent source_file, and go on to any remaining source_files.
90
91        4. If  the destination path exists, and it is a file of type directory
92           and source_file is not a file of type directory, or it  is  a  file
93           not  of type directory and source_file is a file of type directory,
94           mv shall write a diagnostic message to standard error,  do  nothing
95           more  with  the  current  source_file,  and  go on to any remaining
96           source_files.  If the destination path exists and was created by  a
97           previous  step,  it  is unspecified whether this will treated as an
98           error or the destination path will be overwritten.
99
100        5. If the destination path exists, mv shall attempt to remove  it.  If
101           this  fails  for any reason, mv shall write a diagnostic message to
102           standard error, do nothing more with the current  source_file,  and
103           go on to any remaining source_files.
104
105        6. The  file  hierarchy rooted in source_file shall be duplicated as a
106           file hierarchy rooted in the destination path.  If  source_file  or
107           any  of the files below it in the hierarchy are symbolic links, the
108           links themselves shall be  duplicated,  including  their  contents,
109           rather than any files to which they refer. The following character‐
110           istics of each file in the file hierarchy shall be duplicated:
111
112            *  The time of last data modification and time of last access
113
114            *  The user ID and group ID
115
116            *  The file mode
117
118           If the user ID, group ID, or file mode of a regular file cannot  be
119           duplicated,  the  file  mode  bits S_ISUID and S_ISGID shall not be
120           duplicated.
121
122           When files are duplicated to another file system,  the  implementa‐
123           tion  may  require  that the process invoking mv has read access to
124           each file being duplicated.
125
126           If files being duplicated to another file system have hard links to
127           other  files, it is unspecified whether the files copied to the new
128           file system have the hard links preserved or  separate  copies  are
129           created for the linked files.
130
131           If  the  duplication of the file hierarchy fails for any reason, mv
132           shall write a diagnostic message to standard error, do nothing more
133           with   the   current  source_file,  and  go  on  to  any  remaining
134           source_files.
135
136           If the duplication of the file characteristics fails for  any  rea‐
137           son,  mv  shall  write  a diagnostic message to standard error, but
138           this failure shall not cause mv to modify its exit status.
139
140        7. The file hierarchy rooted in source_file shall be removed. If  this
141           fails  for  any  reason, mv shall write a diagnostic message to the
142           standard error, do nothing more with the current  source_file,  and
143           go on to any remaining source_files.
144

OPTIONS

146       The  mv  utility  shall  conform  to  the  Base  Definitions  volume of
147       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
148
149       The following options shall be supported:
150
151       -f        Do not  prompt  for  confirmation  if  the  destination  path
152                 exists. Any previous occurrence of the -i option is ignored.
153
154       -i        Prompt  for  confirmation if the destination path exists. Any
155                 previous occurrence of the -f option is ignored.
156
157       Specifying more than one of the -f or -i options shall not  be  consid‐
158       ered  an  error. The last option specified shall determine the behavior
159       of mv.
160

OPERANDS

162       The following operands shall be supported:
163
164       source_file
165                 A pathname of a file or directory to be moved.
166
167       target_file
168                 A new pathname for the file or directory being moved.
169
170       target_dir
171                 A pathname of an existing directory into which  to  move  the
172                 input files.
173

STDIN

175       The  standard  input shall be used to read an input line in response to
176       each prompt specified in the STDERR section.  Otherwise,  the  standard
177       input shall not be used.
178

INPUT FILES

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

ENVIRONMENT VARIABLES

184       The following environment variables shall affect the execution of mv:
185
186       LANG      Provide a default value for  the  internationalization  vari‐
187                 ables  that are unset or null. (See the Base Definitions vol‐
188                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
189                 ables  for  the  precedence of internationalization variables
190                 used to determine the values of locale categories.)
191
192       LC_ALL    If set to a non-empty string value, override  the  values  of
193                 all the other internationalization variables.
194
195       LC_COLLATE
196                 Determine  the locale for the behavior of ranges, equivalence
197                 classes, and multi-character collating elements used  in  the
198                 extended  regular  expression  defined for the yesexpr locale
199                 keyword in the LC_MESSAGES category.
200
201       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
202                 bytes of text data as characters (for example, single-byte as
203                 opposed to  multi-byte  characters  in  arguments  and  input
204                 files),  the  behavior  of  character  classes  used  in  the
205                 extended regular expression defined for  the  yesexpr  locale
206                 keyword in the LC_MESSAGES category.
207
208       LC_MESSAGES
209                 Determine  the  locale used to process affirmative responses,
210                 and the locale used to affect  the  format  and  contents  of
211                 diagnostic messages and prompts written to standard error.
212
213       NLSPATH   Determine the location of message catalogs for the processing
214                 of LC_MESSAGES.
215

ASYNCHRONOUS EVENTS

217       Default.
218

STDOUT

220       Not used.
221

STDERR

223       Prompts shall be written to the standard  error  under  the  conditions
224       specified  in  the  DESCRIPTION  section. The prompts shall contain the
225       destination pathname, but their format is otherwise unspecified.   Oth‐
226       erwise, the standard error shall be used only for diagnostic messages.
227

OUTPUT FILES

229       The output files may be of any file type.
230

EXTENDED DESCRIPTION

232       None.
233

EXIT STATUS

235       The following exit values shall be returned:
236
237        0    All input files were moved successfully.
238
239       >0    An error occurred.
240

CONSEQUENCES OF ERRORS

242       If the copying or removal of source_file is prematurely terminated by a
243       signal or error, mv may leave a partial  copy  of  source_file  at  the
244       source or destination. The mv utility shall not modify both source_file
245       and the destination path simultaneously; termination at any point shall
246       leave either source_file or the destination path complete.
247
248       The following sections are informative.
249

APPLICATION USAGE

251       Some  implementations mark for update the last file status change time‐
252       stamp of renamed files and some do not. Applications which make use  of
253       the  last  file  status  change  timestamp  may behave differently with
254       respect to renamed files unless they are designed to allow  for  either
255       behavior.
256
257       The  specification  ensures  that mv a a will not alter the contents of
258       file a, and allows the implementation to issue an  error  that  a  file
259       cannot  be  moved onto itself. Likewise, when a and b are hard links to
260       the same file, mv a b will not alter b, but  if  a  diagnostic  is  not
261       issued, then it is unspecified whether a is left untouched (as it would
262       be by the rename() function) or unlinked (reducing the  link  count  of
263       b).
264

EXAMPLES

266       If  the current directory contains only files a (of any type defined by
267       the System Interfaces volume of POSIX.1‐2017), b (also  of  any  type),
268       and a directory c:
269
270
271           mv a b c
272           mv c d
273
274       results  with the original files a and b residing in the directory d in
275       the current directory.
276

RATIONALE

278       Early proposals diverged from the SVID and BSD historical  practice  in
279       that they required that when the destination path exists, the -f option
280       is not specified, and input is not a terminal, mv fails. This was  done
281       for  compatibility  with  cp.   The  current text returns to historical
282       practice. It should be noted that this is consistent with the  rename()
283       function defined in the System Interfaces volume of POSIX.1‐2017, which
284       does not require write permission on the target.
285
286       For absolute clarity, paragraph (1), describing the behavior of mv when
287       prompting for confirmation, should be interpreted in the following man‐
288       ner:
289
290
291           if (exists AND (NOT f_option) AND
292               ((not_writable AND input_is_terminal) OR i_option))
293
294       The -i option exists on BSD systems, giving applications  and  users  a
295       way  to avoid accidentally unlinking files when moving others. When the
296       standard input is not a terminal, the 4.3 BSD mv deletes  all  existing
297       destination paths without prompting, even when -i is specified; this is
298       inconsistent with the behavior of the 4.3 BSD cp utility, which  always
299       generates  an  error when the file is unwritable and the standard input
300       is not a terminal. The standard developers decided that use of -i is  a
301       request for interaction, so when the destination path exists, the util‐
302       ity takes instructions from whatever responds to standard input.
303
304       The rename() function is able to move directories within the same  file
305       system.  Some historical versions of mv have been able to move directo‐
306       ries, but not to a different file system.  The standard developers con‐
307       sidered  that  this  was  an  annoying inconsistency, so this volume of
308       POSIX.1‐2017 requires directories to be able to be  moved  even  across
309       file  systems. There is no -R option to confirm that moving a directory
310       is actually intended, since such an option was not required for  moving
311       directories  in historical practice. Requiring the application to spec‐
312       ify it sometimes, depending on the destination, seemed just  as  incon‐
313       sistent.  The semantics of the rename() function were preserved as much
314       as possible. For example, mv is not permitted to ``rename'' files to or
315       from directories, even though they might be empty and removable.
316
317       Historic implementations of mv did not exit with a non-zero exit status
318       if they were unable to duplicate any file characteristics when moving a
319       file  across  file systems, nor did they write a diagnostic message for
320       the user. The former behavior has been  preserved  to  prevent  scripts
321       from  breaking;  a diagnostic message is now required, however, so that
322       users are alerted that the file characteristics have changed.
323
324       The exact format of the interactive prompts is  unspecified.  Only  the
325       general  nature of the contents of prompts are specified because imple‐
326       mentations may desire more descriptive prompts than those used on  his‐
327       torical  implementations.  Therefore,  an  application not using the -f
328       option or using the -i option relies on the system to provide the  most
329       suitable  dialog  directly  with the user, based on the behavior speci‐
330       fied.
331
332       When mv is dealing with a single file system and source_file is a  sym‐
333       bolic link, the link itself is moved as a consequence of the dependence
334       on the rename() functionality, per the DESCRIPTION.  Across  file  sys‐
335       tems, this has to be made explicit.
336

FUTURE DIRECTIONS

338       None.
339

SEE ALSO

341       cp, ln
342
343       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
344       Variables, Section 12.2, Utility Syntax Guidelines
345
346       The System Interfaces volume of POSIX.1‐2017, rename()
347
349       Portions of this text are reprinted and reproduced in  electronic  form
350       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
351       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
352       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
353       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
354       event of any discrepancy between this version and the original IEEE and
355       The Open Group Standard, the original IEEE and The Open Group  Standard
356       is  the  referee document. The original Standard can be obtained online
357       at http://www.opengroup.org/unix/online.html .
358
359       Any typographical or formatting errors that appear  in  this  page  are
360       most likely to have been introduced during the conversion of the source
361       files to man page format. To report such errors,  see  https://www.ker
362       nel.org/doc/man-pages/reporting_bugs.html .
363
364
365
366IEEE/The Open Group                  2017                               MV(1P)
Impressum