.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright 2024 Oxide Computer Company
.\"
.TH MV 1 "September 14, 2024"
.SH NAME
mv \- move files
.SH SYNOPSIS
.nf
\fB/usr/bin/mv\fR [\fB-fin\fR] \fIsource\fR \fItarget_file\fR
.fi

.LP
.nf
\fB/usr/bin/mv\fR [\fB-fin\fR] \fIsource\fR... \fItarget_dir\fR
.fi

.LP
.nf
\fB/usr/xpg4/bin/mv\fR [\fB-fin\fR] \fIsource\fR \fItarget_file\fR
.fi

.LP
.nf
\fB/usr/xpg4/bin/mv\fR [\fB-fin\fR] \fIsource\fR... \fItarget_dir\fR
.fi

.SH DESCRIPTION
In the first synopsis form, the \fBmv\fR utility moves the file named by the
\fIsource\fR operand to the destination specified by the \fItarget_file\fR.
\fIsource\fR and \fItarget_file\fR can not have the same name. If
\fItarget_file\fR does not exist, \fBmv\fR creates a file named
\fItarget_file\fR. If \fItarget_file\fR exists, its contents are overwritten.
This first synopsis form is assumed when the final operand does not name an
existing directory.
.sp
.LP
In the second synopsis form, \fBmv\fR moves each file named by a \fIsource\fR
operand to a destination file in the existing directory named by the
\fItarget_dir\fR operand. The destination path for each \fIsource\fR is the
concatenation of the target directory, a single slash character (\fB/\fR), and
the last path name component of the \fIsource\fR. This second form is assumed
when the final operand names an existing directory.
.sp
.LP
If \fBmv\fR determines that the mode of \fItarget_file\fR forbids writing, it
prints the mode (see \fBchmod\fR(2)), ask for a response, and read the standard
input for one line. If the response is affirmative, the \fBmv\fR occurs, if
permissible; otherwise, the command exits. Notice that the mode displayed can
not fully represent the access permission if \fItarget\fR is associated with an
\fBACL\fR. When the parent directory of \fIsource\fR is writable and has the
sticky bit set, one or more of the following conditions must be true:
.RS +4
.TP
.ie t \(bu
.el o
the user must own the file
.RE
.RS +4
.TP
.ie t \(bu
.el o
the user must own the directory
.RE
.RS +4
.TP
.ie t \(bu
.el o
the file must be writable by the user
.RE
.RS +4
.TP
.ie t \(bu
.el o
the user must be a privileged user
.RE
.sp
.LP
If \fIsource\fR is a file and \fItarget_file\fR is a link to another file with
links, the other links remain and \fItarget_file\fR becomes a new file.
.sp
.LP
If \fIsource\fR and \fItarget_file\fR/\fItarget_dir\fR are on different file
systems, \fBmv\fR copies the source and deletes the original. Any hard links to
other files are lost. \fBmv\fR attempts to duplicate the source file
characteristics to the target, that is, the owner and group id, permission
modes, modification and access times, \fBACL\fRs, and extended attributes, if
applicable. For symbolic links, \fBmv\fR preserves only the owner and group of
the link itself.
.sp
.LP
If unable to preserve owner and group id, \fBmv\fR clears \fBS_ISUID\fR and
\fBS_ISGID\fR bits in the target. \fBmv\fR prints a diagnostic message to
stderr if unable to clear these bits, though the exit code is not affected.
\fBmv\fR might be unable to preserve extended attributes if the target file
system does not have extended attribute support. \fB/usr/xpg4/bin/mv\fR prints
a diagnostic message to stderr for all other failed attempts to duplicate file
characteristics. The exit code is not affected.
.sp
.LP
In order to preserve the source file characteristics, users must have the
appropriate file access permissions. This includes being super-user or having
the same owner id as the destination file.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
\fBmv\fR moves the file(s) without prompting even if it is writing over an
existing \fItarget\fR. Note that this is the default if the standard input is
not a terminal. This overrides any \fB-i\fR and \fB-n\fR options already
specified on the command line.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 6n
\fBmv\fR prompts for confirmation whenever the move would overwrite an existing
\fItarget\fR. An affirmative answer means that the move should proceed. Any
other answer prevents \fBmv\fR from overwriting the \fItarget\fR. This overrides
any \fB-n\fI options already specified on the command line. See the discussion
of binary-specific behavior below for how \fB-i\fR and \fB-f\fR interact.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 6n
\fBmv\fR will not overwrite \fItarget\fR if it already exists, proceeding on to
other sources. This does not generate an error. This overrides any \fB-i\fR or
\fB-f\fR options already specified on the command line.
.RE


.SS "/usr/bin/mv"
Specifying the \fB-f\fR the \fB-i\fR, and the \fB-n\fR options is not considered
an error. The last option specified determines the behavior of \fBmv\fR with one
exception: the \fB-f\fR option overrides all \fB-i\fR options, regardless of where
they appear in the command line.
.SS "/usr/xpg4/bin/mv"
Specifying the \fB-f\fR the \fB-i\fR, and the \fB-n\fR options is not considered
an error.  The last option specified determines the behavior of \fBmv\fR.
.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fB\fIsource\fR\fR
.ad
.RS 15n
A path name of a file or directory to be moved.
.RE

.sp
.ne 2
.na
\fB\fItarget_file\fR\fR
.ad
.RS 15n
A new path name for the file or directory being moved.
.RE

.sp
.ne 2
.na
\fB\fItarget_dir\fR\fR
.ad
.RS 15n
A path name of an existing directory into which to move the input files.
.RE

.SH USAGE
See \fBlargefile\fR(7) for the description of the behavior of \fBmv\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH ENVIRONMENT VARIABLES
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of \fBmv\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.sp
.LP
Affirmative responses are processed using the extended regular expression
defined for the \fByesexpr\fR keyword in the \fBLC_MESSAGES\fR category of the
user's locale. The locale specified in the \fBLC_COLLATE\fR category defines
the behavior of ranges, equivalence classes, and multi-character collating
elements used in the expression defined for \fByesexpr\fR. The locale specified
in \fBLC_CTYPE\fR determines the locale for interpretation of sequences of
bytes of text data a characters, the behavior of character classes used in the
expression defined for the \fByesexpr\fR. See \fBlocale\fR(7).
.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
All input files were moved successfully.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.SS "/usr/bin/mv"
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Stable
.TE

.SS "/usr/xpg4/bin/mv"
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.BR cp (1),
.BR cpio (1),
.BR ln (1),
.BR rm (1),
.BR setfacl (1),
.BR chmod (2),
.BR attributes (7),
.BR environ (7),
.BR fsattr (7),
.BR largefile (7),
.BR standards (7)
.SH NOTES
A \fB--\fR permits the user to mark explicitly the end of any command line
options, allowing \fBmv\fR to recognize filename arguments that begin with a
\fB-\fR. As an aid to BSD migration, \fBmv\fR accepts \fB-\fR as a synonym for
\fB--\fR. This migration aid might disappear in a future release.