freebsd-dev/bin/mv/mv.1

.\" Copyright (c) 1989, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mv.1	8.1 (Berkeley) 5/31/93
.\" $FreeBSD$
.\"
.Dd May 31, 1993
.Dt MV 1
.Os
.Sh NAME
.Nm mv
.Nd move files
.Sh SYNOPSIS
.Nm
.Op Fl f | Fl i
.Op Fl v
.Ar source target
.Nm
.Op  Fl f | Fl i
.Op Fl v
.Ar source ... directory
.Sh DESCRIPTION
In its first form, the
.Nm
utility renames the file named by the
.Ar source
operand to the destination path named by the
.Ar target
operand.
This form is assumed when the last operand does not name an already
existing directory.
.Pp
In its second form,
.Nm
moves each file named by a
.Ar source
operand to a destination file in the existing directory named by the
.Ar directory
operand.
The destination path for each operand is the pathname produced by the
concatenation of the last operand, a slash, and the final pathname
component of the named file.
.Pp
The following options are available:
.Bl -tag -width flag
.It Fl f
Do not prompt for confirmation before overwriting the destination
path.
(The
.Fl f
option overrides any previous
.Fl i
options.)
.It Fl i
Cause
.Nm
to write a prompt to standard error before moving a file that would
overwrite an existing file.
If the response from the standard input begins with the character
.Sq Li y 
or
.Sq Li Y ,
the move is attempted.
(The
.Fl i
option overrides any previous
.Fl f
options.)
.It Fl v
Cause
.Nm
to be verbose, showing files after they are moved.
.El
.Pp
It is an error for either the
.Ar source
operand or the destination path to specify a directory unless both do.
.Pp
If the destination path does not have a mode which permits writing,
.Nm
prompts the user for confirmation as specified for the
.Fl i
option.
.Pp
As the
.Xr rename  2
call does not work across file systems,
.Nm
uses
.Xr cp 1
and
.Xr rm 1
to accomplish the move.
The effect is equivalent to:
.Bd -literal -offset indent
rm -f destination_path && \e
\tcp -pRP source_file destination && \e
\trm -rf source_file
.Ed
.Sh DIAGNOSTICS
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Sh SEE ALSO
.Xr cp 1 ,
.Xr rm 1 ,
.Xr symlink 7
.Sh COMPATIBILITY
The
.Fl v
option is non-standard and its use in scripts is not recommended.
.Sh STANDARDS
The
.Nm
utility is expected to be
.St -p1003.2
compatible.
.Sh HISTORY
A
.Nm
command appeared in
.At v1 .
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.\" Copyright (c) 1989, 1990, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" This code is derived from software contributed to Berkeley by`
			`.\" the Institute of Electrical and Electronics Engineers, Inc.`
			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
			`.\" 3. All advertising materials mentioning features or use of this software`
			`.\" must display the following acknowledgement:`
			`.\" This product includes software developed by the University of`
			`.\" California, Berkeley and its contributors.`
			`.\" 4. Neither the name of the University nor the names of its contributors`
			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
			`.\"`
			`.\" @(#)mv.1 8.1 (Berkeley) 5/31/93`
$Id$ -> $FreeBSD$ 1999-08-27 23:15:48 +00:00			`.\" $FreeBSD$`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.\"`
			`.Dd May 31, 1993`
			`.Dt MV 1`
			`.Os`
			`.Sh NAME`
			`.Nm mv`
			`.Nd move files`
			`.Sh SYNOPSIS`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 11:39:41 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.Op Fl f \| Fl i`
add verbose flag 1999-08-29 08:21:16 +00:00			`.Op Fl v`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.Ar source target`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 11:39:41 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.Op Fl f \| Fl i`
add verbose flag 1999-08-29 08:21:16 +00:00			`.Op Fl v`
Synchronize usage() and man page. Pointed out by bde. 1997-10-26 10:33:02 +00:00			`.Ar source ... directory`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.Sh DESCRIPTION`
			`In its first form, the`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`utility renames the file named by the`
			`.Ar source`
			`operand to the destination path named by the`
			`.Ar target`
			`operand.`
			`This form is assumed when the last operand does not name an already`
			`existing directory.`
			`.Pp`
			`In its second form,`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`moves each file named by a`
			`.Ar source`
			`operand to a destination file in the existing directory named by the`
			`.Ar directory`
			`operand.`
			`The destination path for each operand is the pathname produced by the`
			`concatenation of the last operand, a slash, and the final pathname`
			`component of the named file.`
			`.Pp`
			`The following options are available:`
			`.Bl -tag -width flag`
			`.It Fl f`
			`Do not prompt for confirmation before overwriting the destination`
			`path.`
			`(The`
delete my last commit Submitted by: pst, ache 1996-02-19 00:44:19 +00:00			`.Fl f`
option -f and -i are exclusive (Posix) respond `Y' is equal to `y' update usage string prompt only if source exist 1996-02-20 23:27:57 +00:00			`option overrides any previous`
			`.Fl i`
			`options.)`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.It Fl i`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`Cause`
			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`to write a prompt to standard error before moving a file that would`
			`overwrite an existing file.`
option -f and -i are exclusive (Posix) respond `Y' is equal to `y' update usage string prompt only if source exist 1996-02-20 23:27:57 +00:00			`If the response from the standard input begins with the character`
			`.Sq Li y`
			`or`
			`.Sq Li Y ,`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`the move is attempted.`
option -f and -i are exclusive (Posix) respond `Y' is equal to `y' update usage string prompt only if source exist 1996-02-20 23:27:57 +00:00			`(The`
			`.Fl i`
			`option overrides any previous`
			`.Fl f`
			`options.)`
add verbose flag 1999-08-29 08:21:16 +00:00			`.It Fl v`
			`Cause`
			`.Nm`
			`to be verbose, showing files after they are moved.`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.El`
			`.Pp`
			`It is an error for either the`
			`.Ar source`
			`operand or the destination path to specify a directory unless both do.`
			`.Pp`
			`If the destination path does not have a mode which permits writing,`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`prompts the user for confirmation as specified for the`
			`.Fl i`
			`option.`
			`.Pp`
			`As the`
			`.Xr rename 2`
			`call does not work across file systems,`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`uses`
			`.Xr cp 1`
			`and`
			`.Xr rm 1`
			`to accomplish the move.`
			`The effect is equivalent to:`
			`.Bd -literal -offset indent`
			`rm -f destination_path && \e`
The command to `move' across file system boundaries is actually cp -PRp source_file destination Closes PR # bin/689: mv(1) manpage Submitted by: wosch@cs.tu-berlin.de (Wolfram Schneider) 1995-08-15 19:44:39 +00:00			`\tcp -pRP source_file destination && \e`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`\trm -rf source_file`
			`.Ed`
Various spelling/formatting changes. Submitted by: Philippe Charnier <charnier@xp11.frmug.org> 1999-05-08 10:22:15 +00:00			`.Sh DIAGNOSTICS`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`The`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`utility exits 0 on success, and >0 if an error occurs.`
			`.Sh SEE ALSO`
			`.Xr cp 1 ,`
option -f and -i are exclusive (Posix) respond `Y' is equal to `y' update usage string prompt only if source exist 1996-02-20 23:27:57 +00:00			`.Xr rm 1 ,`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.Xr symlink 7`
mention that -v is non-standard Reviewed-by: obrien 1999-09-04 03:33:18 +00:00			`.Sh COMPATIBILITY`
			`The`
			`.Fl v`
			`option is non-standard and its use in scripts is not recommended.`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`.Sh STANDARDS`
			`The`
Correct use of .Nm. Add rcsid. 1998-05-15 06:30:58 +00:00			`.Nm`
BSD 4.4 Lite bin Sources 1994-05-26 06:18:55 +00:00			`utility is expected to be`
			`.St -p1003.2`
			`compatible.`
[HISTORY] command appeared in Version 1 AT&T UNIX Obtained from: A Quarter Century of UNIX, Peter H. Salus, page 41 1996-08-29 18:06:19 +00:00			`.Sh HISTORY`
			`A`
			`.Nm`
			`command appeared in`
			`.At v1 .`