man-pages/man1p/mv.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "MV" 1P 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 .