diff options
Diffstat (limited to 'man1p/mv.1p')
| -rw-r--r-- | man1p/mv.1p | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/man1p/mv.1p b/man1p/mv.1p new file mode 100644 index 000000000..e01faddf6 --- /dev/null +++ b/man1p/mv.1p @@ -0,0 +1,376 @@ +.\" 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 . |