1MV(P) POSIX Programmer's Manual MV(P)
2
6 mv - move files
7
9 mv [-fi] source_file target_file
10 mv [-fi] source_file... target_file
12
15 In the first synopsis form, the mv utility shall move the file named by
16 the source_file operand to the destination specified by the tar‐
17 get_file. This first synopsis form is assumed when the final operand
18 does not name an existing directory and is not a symbolic link refer‐
19 ring to an existing directory.
20 In the second synopsis form, mv shall move each file named by a
22 source_file operand to a destination file in the existing directory
23 named by the target_dir operand, or referenced if target_dir is a sym‐
24 bolic link referring to an existing directory. The destination path for
25 each source_file shall be the concatenation of the target directory, a
26 single slash character, and the last pathname component of the
27 source_file. This second form is assumed when the final operand names
28 an existing directory.
29 If any operand specifies an existing file of a type not specified by
31 the System Interfaces volume of IEEE Std 1003.1-2001, the behavior is
32 implementation-defined.
33 For each source_file the following steps shall be taken:
35 1. If the destination path exists, the -f option is not specified, and
37 either of the following conditions is true:
38 a. The permissions of the destination path do not permit writing
40 and the standard input is a terminal.
41 b. The -i option is specified.
43 the mv utility shall write a prompt to standard error and read a line
45 from standard input. If the response is not affirmative, mv shall do
46 nothing more with the current source_file and go on to any remaining
47 source_files.
48 2. The mv utility shall perform actions equivalent to the rename()
50 function defined in the System Interfaces volume of
51 IEEE Std 1003.1-2001, called with the following arguments:
52 a. The source_file operand is used as the old argument.
54 b. The destination path is used as the new argument.
56 If this succeeds, mv shall do nothing more with the current source_file
58 and go on to any remaining source_files. If this fails for any reasons
59 other than those described for the errno [EXDEV] in the System Inter‐
60 faces volume of IEEE Std 1003.1-2001, mv shall write a diagnostic mes‐
61 sage to standard error, do nothing more with the current source_file,
62 and go on to any remaining source_files.
63 3. If the destination path exists, and it is a file of type directory
65 and source_file is not a file of type directory, or it is a file
66 not of type directory and source_file is a file of type directory,
67 mv shall write a diagnostic message to standard error, do nothing
68 more with the current source_file, and go on to any remaining
69 source_files.
70 4. If the destination path exists, mv shall attempt to remove it. If
72 this fails for any reason, mv shall write a diagnostic message to
73 standard error, do nothing more with the current source_file, and
74 go on to any remaining source_files.
75 5. The file hierarchy rooted in source_file shall be duplicated as a
77 file hierarchy rooted in the destination path. If source_file or
78 any of the files below it in the hierarchy are symbolic links, the
79 links themselves shall be duplicated, including their contents,
80 rather than any files to which they refer. The following charac‐
81 teristics of each file in the file hierarchy shall be duplicated:
82 * The time of last data modification and time of last access
84 * The user ID and group ID
86 * The file mode
88 If the user ID, group ID, or file mode of a regular file cannot be
90 duplicated, the file mode bits S_ISUID and S_ISGID shall not be dupli‐
91 cated.
92 When files are duplicated to another file system, the implementation
94 may require that the process invoking mv has read access to each file
95 being duplicated.
96 If the duplication of the file hierarchy fails for any reason, mv shall
98 write a diagnostic message to standard error, do nothing more with the
99 current source_file, and go on to any remaining source_files.
100 If the duplication of the file characteristics fails for any reason, mv
102 shall write a diagnostic message to standard error, but this failure
103 shall not cause mv to modify its exit status.
104 6. The file hierarchy rooted in source_file shall be removed. If this
106 fails for any reason, mv shall write a diagnostic message to the
107 standard error, do nothing more with the current source_file, and
108 go on to any remaining source_files.
109
111 The mv utility shall conform to the Base Definitions volume of
112 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
113 The following options shall be supported:
115 -f Do not prompt for confirmation if the destination path exists.
117 Any previous occurrence of the -i option is ignored.
118 -i Prompt for confirmation if the destination path exists. Any pre‐
120 vious occurrence of the -f option is ignored.
121 Specifying more than one of the -f or -i options shall not be consid‐
124 ered an error. The last option specified shall determine the behavior
125 of mv.
126
128 The following operands shall be supported:
129 source_file
131 A pathname of a file or directory to be moved.
132 target_file
134 A new pathname for the file or directory being moved.
135 target_dir
137 A pathname of an existing directory into which to move the input
138 files.
139
142 The standard input shall be used to read an input line in response to
143 each prompt specified in the STDERR section. Otherwise, the standard
144 input shall not be used.
145
147 The input files specified by each source_file operand can be of any
148 file type.
149
151 The following environment variables shall affect the execution of mv:
152 LANG Provide a default value for the internationalization variables
154 that are unset or null. (See the Base Definitions volume of
155 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
156 ables for the precedence of internationalization variables used
157 to determine the values of locale categories.)
158 LC_ALL If set to a non-empty string value, override the values of all
160 the other internationalization variables.
161 LC_COLLATE
163 Determine the locale for the behavior of ranges, equivalence
165 classes, and multi-character collating elements used in the
166 extended regular expression defined for the yesexpr locale key‐
167 word in the LC_MESSAGES category.
168 LC_CTYPE
170 Determine the locale for the interpretation of sequences of
171 bytes of text data as characters (for example, single-byte as
172 opposed to multi-byte characters in arguments and input files),
173 the behavior of character classes used in the extended regular
174 expression defined for the yesexpr locale keyword in the LC_MES‐
175 SAGES category.
176 LC_MESSAGES
178 Determine the locale for the processing of affirmative responses
179 that should be used to affect the format and contents of diag‐
180 nostic messages written to standard error.
181 NLSPATH
183 Determine the location of message catalogs for the processing of
184 LC_MESSAGES .
185
188 Default.
189
191 Not used.
192
194 Prompts shall be written to the standard error under the conditions
195 specified in the DESCRIPTION section. The prompts shall contain the
196 destination pathname, but their format is otherwise unspecified. Oth‐
197 erwise, the standard error shall be used only for diagnostic messages.
198
200 The output files may be of any file type.
201
203 None.
204
206 The following exit values shall be returned:
207 0 All input files were moved successfully.
209 >0 An error occurred.
211
214 If the copying or removal of source_file is prematurely terminated by a
215 signal or error, mv may leave a partial copy of source_file at the
216 source or destination. The mv utility shall not modify both source_file
217 and the destination path simultaneously; termination at any point shall
218 leave either source_file or the destination path complete.
219 The following sections are informative.
221
223 Some implementations mark for update the st_ctime field of renamed
224 files and some do not. Applications which make use of the st_ctime
225 field may behave differently with respect to renamed files unless they
226 are designed to allow for either behavior.
227
229 If the current directory contains only files a (of any type defined by
230 the System Interfaces volume of IEEE Std 1003.1-2001), b (also of any
231 type), and a directory c:
232 mv a b c
235 mv c d
236 results with the original files a and b residing in the directory d in
238 the current directory.
239
241 Early proposals diverged from the SVID and BSD historical practice in
242 that they required that when the destination path exists, the -f option
243 is not specified, and input is not a terminal, mv fails. This was done
244 for compatibility with cp. The current text returns to historical prac‐
245 tice. It should be noted that this is consistent with the rename()
246 function defined in the System Interfaces volume of
247 IEEE Std 1003.1-2001, which does not require write permission on the
248 target.
249 For absolute clarity, paragraph (1), describing the behavior of mv when
251 prompting for confirmation, should be interpreted in the following man‐
252 ner:
253 if (exists AND (NOT f_option) AND
256 ((not_writable AND input_is_terminal) OR i_option))
257 The -i option exists on BSD systems, giving applications and users a
259 way to avoid accidentally unlinking files when moving others. When the
260 standard input is not a terminal, the 4.3 BSD mv deletes all existing
261 destination paths without prompting, even when -i is specified; this is
262 inconsistent with the behavior of the 4.3 BSD cp utility, which always
263 generates an error when the file is unwritable and the standard input
264 is not a terminal. The standard developers decided that use of -i is a
265 request for interaction, so when the destination path exists, the util‐
266 ity takes instructions from whatever responds to standard input.
267 The rename() function is able to move directories within the same file
269 system. Some historical versions of mv have been able to move directo‐
270 ries, but not to a different file system. The standard developers con‐
271 sidered that this was an annoying inconsistency, so this volume of
272 IEEE Std 1003.1-2001 requires directories to be able to be moved even
273 across file systems. There is no -R option to confirm that moving a
274 directory is actually intended, since such an option was not required
275 for moving directories in historical practice. Requiring the applica‐
276 tion to specify it sometimes, depending on the destination, seemed just
277 as inconsistent. The semantics of the rename() function were preserved
278 as much as possible. For example, mv is not permitted to "rename" files
279 to or from directories, even though they might be empty and removable.
280 Historic implementations of mv did not exit with a non-zero exit status
282 if they were unable to duplicate any file characteristics when moving a
283 file across file systems, nor did they write a diagnostic message for
284 the user. The former behavior has been preserved to prevent scripts
285 from breaking; a diagnostic message is now required, however, so that
286 users are alerted that the file characteristics have changed.
287 The exact format of the interactive prompts is unspecified. Only the
289 general nature of the contents of prompts are specified because imple‐
290 mentations may desire more descriptive prompts than those used on his‐
291 torical implementations. Therefore, an application not using the -f
292 option or using the -i option relies on the system to provide the most
293 suitable dialog directly with the user, based on the behavior speci‐
294 fied.
295 When mv is dealing with a single file system and source_file is a sym‐
297 bolic link, the link itself is moved as a consequence of the dependence
298 on the rename() functionality, per the DESCRIPTION. Across file sys‐
299 tems, this has to be made explicit.
300
302 None.
303
305 cp , ln , the System Interfaces volume of IEEE Std 1003.1-2001,
306 rename()
307
309 Portions of this text are reprinted and reproduced in electronic form
310 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
311 -- Portable Operating System Interface (POSIX), The Open Group Base
312 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
313 Electrical and Electronics Engineers, Inc and The Open Group. In the
314 event of any discrepancy between this version and the original IEEE and
315 The Open Group Standard, the original IEEE and The Open Group Standard
316 is the referee document. The original Standard can be obtained online
317 at http://www.opengroup.org/unix/online.html .
318IEEE/The Open Group 2003 MV(P)