mirror of https://github.com/mkerrisk/man-pages
377 lines
13 KiB
Groff
377 lines
13 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "MV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" mv
|
|
.SH NAME
|
|
mv \- move files
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBmv\fP \fB[\fP\fB-fi\fP\fB]\fP \fIsource_file target_file\fP\fB
|
|
.br
|
|
.sp
|
|
mv\fP \fB[\fP\fB-fi\fP\fB]\fP \fIsource_file\fP\fB...\fP \fItarget_file\fP\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
In the first synopsis form, the \fImv\fP utility shall move the file
|
|
named by the \fIsource_file\fP operand to the destination
|
|
specified by the \fItarget_file\fP. 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.
|
|
.LP
|
|
In the second synopsis form, \fImv\fP shall move each file named by
|
|
a \fIsource_file\fP operand to a destination file in the
|
|
existing directory named by the \fItarget_dir\fP operand, or referenced
|
|
if \fItarget_dir\fP is a symbolic link referring to an
|
|
existing directory. The destination path for each \fIsource_file\fP
|
|
shall be the concatenation of the target directory, a single
|
|
slash character, and the last pathname component of the \fIsource_file\fP.
|
|
This second form is assumed when the final operand
|
|
names an existing directory.
|
|
.LP
|
|
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.
|
|
.LP
|
|
For each \fIsource_file\fP the following steps shall be taken:
|
|
.IP " 1." 4
|
|
If the destination path exists, the \fB-f\fP option is not specified,
|
|
and either of the following conditions is true:
|
|
.RS
|
|
.IP " a." 4
|
|
The permissions of the destination path do not permit writing and
|
|
the standard input is a terminal.
|
|
.LP
|
|
.IP " b." 4
|
|
The \fB-i\fP option is specified.
|
|
.LP
|
|
.RE
|
|
.LP
|
|
the \fImv\fP utility shall write a prompt to standard error and read
|
|
a line from standard input. If the response is not
|
|
affirmative, \fImv\fP shall do nothing more with the current \fIsource_file\fP
|
|
and go on to any remaining
|
|
\fIsource_file\fPs.
|
|
.LP
|
|
.IP " 2." 4
|
|
The \fImv\fP utility shall perform actions equivalent to the \fIrename\fP()
|
|
function
|
|
defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
|
called with the following arguments:
|
|
.RS
|
|
.IP " a." 4
|
|
The \fIsource_file\fP operand is used as the \fIold\fP argument.
|
|
.LP
|
|
.IP " b." 4
|
|
The destination path is used as the \fInew\fP argument.
|
|
.LP
|
|
.RE
|
|
.LP
|
|
If this succeeds, \fImv\fP shall do nothing more with the current
|
|
\fIsource_file\fP and go on to any remaining
|
|
\fIsource_file\fPs. If this fails for any reasons other than those
|
|
described for the \fIerrno\fP [EXDEV] in the System Interfaces
|
|
volume of IEEE\ Std\ 1003.1-2001, \fImv\fP shall write a diagnostic
|
|
message to standard error, do nothing more with the
|
|
current \fIsource_file\fP, and go on to any remaining \fIsource_file\fPs.
|
|
.LP
|
|
.IP " 3." 4
|
|
If the destination path exists, and it is a file of type directory
|
|
and \fIsource_file\fP is not a file of type directory, or it
|
|
is a file not of type directory and \fIsource_file\fP is a file of
|
|
type directory, \fImv\fP shall write a diagnostic message to
|
|
standard error, do nothing more with the current \fIsource_file\fP,
|
|
and go on to any remaining \fIsource_file\fPs.
|
|
.LP
|
|
.IP " 4." 4
|
|
If the destination path exists, \fImv\fP shall attempt to remove it.
|
|
If this fails for any reason, \fImv\fP shall write a
|
|
diagnostic message to standard error, do nothing more with the current
|
|
\fIsource_file\fP, and go on to any remaining
|
|
\fIsource_file\fPs.
|
|
.LP
|
|
.IP " 5." 4
|
|
The file hierarchy rooted in \fIsource_file\fP shall be duplicated
|
|
as a file hierarchy rooted in the destination path. If
|
|
\fIsource_file\fP 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:
|
|
.RS
|
|
.IP " *" 3
|
|
The time of last data modification and time of last access
|
|
.LP
|
|
.IP " *" 3
|
|
The user ID and group ID
|
|
.LP
|
|
.IP " *" 3
|
|
The file mode
|
|
.LP
|
|
.RE
|
|
.LP
|
|
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.
|
|
.LP
|
|
When files are duplicated to another file system, the implementation
|
|
may require that the process invoking \fImv\fP has read
|
|
access to each file being duplicated.
|
|
.LP
|
|
If the duplication of the file hierarchy fails for any reason, \fImv\fP
|
|
shall write a diagnostic message to standard error, do
|
|
nothing more with the current \fIsource_file\fP, and go on to any
|
|
remaining \fIsource_file\fPs.
|
|
.LP
|
|
If the duplication of the file characteristics fails for any reason,
|
|
\fImv\fP shall write a diagnostic message to standard
|
|
error, but this failure shall not cause \fImv\fP to modify its exit
|
|
status.
|
|
.LP
|
|
.IP " 6." 4
|
|
The file hierarchy rooted in \fIsource_file\fP shall be removed. If
|
|
this fails for any reason, \fImv\fP shall write a
|
|
diagnostic message to the standard error, do nothing more with the
|
|
current \fIsource_file\fP, and go on to any remaining
|
|
\fIsource_file\fPs.
|
|
.LP
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fImv\fP utility shall conform to the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
.LP
|
|
The following options shall be supported:
|
|
.TP 7
|
|
\fB-f\fP
|
|
Do not prompt for confirmation if the destination path exists. Any
|
|
previous occurrence of the \fB-i\fP option is ignored.
|
|
.TP 7
|
|
\fB-i\fP
|
|
Prompt for confirmation if the destination path exists. Any previous
|
|
occurrence of the \fB-f\fP option is ignored.
|
|
.sp
|
|
.LP
|
|
Specifying more than one of the \fB-f\fP or \fB-i\fP options shall
|
|
not be considered an error. The last option specified shall
|
|
determine the behavior of \fImv\fP.
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operands shall be supported:
|
|
.TP 7
|
|
\fIsource_file\fP
|
|
A pathname of a file or directory to be moved.
|
|
.TP 7
|
|
\fItarget_file\fP
|
|
A new pathname for the file or directory being moved.
|
|
.TP 7
|
|
\fItarget_dir\fP
|
|
A pathname of an existing directory into which to move the input files.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
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.
|
|
.SH INPUT FILES
|
|
.LP
|
|
The input files specified by each \fIsource_file\fP operand can be
|
|
of any file type.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fImv\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
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.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_COLLATE\fP
|
|
.sp
|
|
Determine the locale for the behavior of ranges, equivalence classes,
|
|
and multi-character collating elements used in the extended
|
|
regular expression defined for the \fByesexpr\fP locale keyword in
|
|
the \fILC_MESSAGES\fP category.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
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 \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP
|
|
category.
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
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.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
Not used.
|
|
.SH STDERR
|
|
.LP
|
|
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.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
The output files may be of any file type.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
All input files were moved successfully.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
If the copying or removal of \fIsource_file\fP is prematurely terminated
|
|
by a signal or error, \fImv\fP may leave a partial
|
|
copy of \fIsource_file\fP at the source or destination. The \fImv\fP
|
|
utility shall not modify both \fIsource_file\fP and the
|
|
destination path simultaneously; termination at any point shall leave
|
|
either \fIsource_file\fP or the destination path
|
|
complete.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Some implementations mark for update the \fIst_ctime\fP field of renamed
|
|
files and some do not. Applications which make use of
|
|
the \fIst_ctime\fP field may behave differently with respect to renamed
|
|
files unless they are designed to allow for either
|
|
behavior.
|
|
.SH EXAMPLES
|
|
.LP
|
|
If the current directory contains only files \fBa\fP (of any type
|
|
defined by the System Interfaces volume of
|
|
IEEE\ Std\ 1003.1-2001), \fBb\fP (also of any type), and a directory
|
|
\fBc\fP:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBmv a b c
|
|
mv c d
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
results with the original files \fBa\fP and \fBb\fP residing in the
|
|
directory \fBd\fP in the current directory.
|
|
.SH RATIONALE
|
|
.LP
|
|
Early proposals diverged from the SVID and BSD historical practice
|
|
in that they required that when the destination path exists,
|
|
the \fB-f\fP option is not specified, and input is not a terminal,
|
|
\fImv\fP fails. This was done for compatibility with \fIcp\fP. The
|
|
current text returns to historical practice. It should be noted that
|
|
this is consistent
|
|
with the \fIrename\fP() function defined in the System Interfaces
|
|
volume of
|
|
IEEE\ Std\ 1003.1-2001, which does not require write permission on
|
|
the target.
|
|
.LP
|
|
For absolute clarity, paragraph (1), describing the behavior of \fImv\fP
|
|
when prompting for confirmation, should be interpreted
|
|
in the following manner:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBif (exists AND (NOT f_option) AND
|
|
((not_writable AND input_is_terminal) OR i_option))
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fB-i\fP 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 \fImv\fP deletes all existing destination paths without
|
|
prompting, even when \fB-i\fP is specified; this is inconsistent with
|
|
the behavior of the 4.3 BSD \fIcp\fP 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 \fB-i\fP
|
|
is a request for interaction, so when the destination path
|
|
exists, the utility takes instructions from whatever responds to standard
|
|
input.
|
|
.LP
|
|
The \fIrename\fP() function is able to move directories within the
|
|
same file system.
|
|
Some historical versions of \fImv\fP 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 \fB-R\fP 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 \fIrename\fP() function were
|
|
preserved as much as possible. For example, \fImv\fP is not permitted
|
|
to "rename" files to or from directories, even though they might be
|
|
empty and removable.
|
|
.LP
|
|
Historic implementations of \fImv\fP 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.
|
|
.LP
|
|
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 \fB-f\fP option or using the \fB-i\fP option
|
|
relies on the system to provide the most suitable dialog
|
|
directly with the user, based on the behavior specified.
|
|
.LP
|
|
When \fImv\fP is dealing with a single file system and \fIsource_file\fP
|
|
is a symbolic link, the link itself is moved as a
|
|
consequence of the dependence on the \fIrename\fP() functionality,
|
|
per the DESCRIPTION.
|
|
Across file systems, this has to be made explicit.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIcp\fP , \fIln\fP , the System Interfaces volume of
|
|
IEEE\ Std\ 1003.1-2001, \fIrename\fP()
|
|
.SH 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 .
|