1MV(1P) POSIX Programmer's Manual MV(1P)
2
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
12 mv — move files
13
15 mv [-if] source_file target_file
16 mv [-if] source_file... target_dir
18
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 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 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 For each source_file the following steps shall be taken:
43 1. If the destination path exists, the -f option is not specified, and
45 either of the following conditions is true:
46 a. The permissions of the destination path do not permit writing
48 and the standard input is a terminal.
49 b. The -i option is specified.
51 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 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 a. No change is made to source_file, no error occurs, and no diag‐
63 nostic is issued.
64 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 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 The mv utility shall do nothing more with the current source_file,
74 and go on to any remaining source_files.
75 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 a. The source_file operand is used as the old argument.
81 b. The destination path is used as the new argument.
83 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 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 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 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 * The time of last data modification and time of last access
113 * The user ID and group ID
115 * The file mode
117 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 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 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 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 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 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
146 The mv utility shall conform to the Base Definitions volume of
147 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
148 The following options shall be supported:
150 -f Do not prompt for confirmation if the destination path
152 exists. Any previous occurrence of the -i option is ignored.
153 -i Prompt for confirmation if the destination path exists. Any
155 previous occurrence of the -f option is ignored.
156 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
162 The following operands shall be supported:
163 source_file
165 A pathname of a file or directory to be moved.
166 target_file
168 A new pathname for the file or directory being moved.
169 target_dir
171 A pathname of an existing directory into which to move the
172 input files.
173
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
180 The input files specified by each source_file operand can be of any
181 file type.
182
184 The following environment variables shall affect the execution of mv:
185 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 LC_ALL If set to a non-empty string value, override the values of
193 all the other internationalization variables.
194 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 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 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 NLSPATH Determine the location of message catalogs for the processing
214 of LC_MESSAGES.
215
217 Default.
218
220 Not used.
221
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
229 The output files may be of any file type.
230
232 None.
233
235 The following exit values shall be returned:
236 0 All input files were moved successfully.
238 >0 An error occurred.
240
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 The following sections are informative.
249
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 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
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 mv a b c
272 mv c d
273 results with the original files a and b residing in the directory d in
275 the current directory.
276
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 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 if (exists AND (NOT f_option) AND
292 ((not_writable AND input_is_terminal) OR i_option))
293 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 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 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 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 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
338 None.
339
341 cp, ln
342 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
344 Variables, Section 12.2, Utility Syntax Guidelines
345 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 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 .
363IEEE/The Open Group 2017 MV(1P)