diff options
Diffstat (limited to 'upstream/archlinux/man1p/mv.1p')
| -rw-r--r-- | upstream/archlinux/man1p/mv.1p | 532 |
1 files changed, 532 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/mv.1p b/upstream/archlinux/man1p/mv.1p new file mode 100644 index 00000000..1ad0b263 --- /dev/null +++ b/upstream/archlinux/man1p/mv.1p @@ -0,0 +1,532 @@ +'\" et +.TH MV "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mv +\(em move files +.SH SYNOPSIS +.LP +.nf +mv \fB[\fR-if\fB] \fIsource_file target_file\fR +.P +mv \fB[\fR-if\fB] \fIsource_file\fR... \fItarget_dir\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR mv +utility shall move the file named by the +.IR source_file +operand to the destination specified by the +.IR target_file . +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. In this case, if +.IR source_file +names a non-directory file and +.IR target_file +ends with a trailing +<slash> +character, +.IR mv +shall treat this as an error and no +.IR source_file +operands will be processed. +.P +In the second synopsis form, +.IR mv +shall move each file named by a +.IR source_file +operand to a destination file in the existing directory named by the +.IR target_dir +operand, or referenced if +.IR target_dir +is a symbolic link referring to an existing directory. The +destination path for each +.IR source_file +shall be the concatenation of the target directory, a single +<slash> +character if the target did not end in a +<slash>, +and the last pathname component of the +.IR source_file . +This second form is assumed when the final operand names an existing +directory. +.P +If any operand specifies an existing file of a type not +specified by the System Interfaces volume of POSIX.1\(hy2017, the behavior is implementation-defined. +.P +For each +.IR source_file +the following steps shall be taken: +.IP " 1." 4 +If the destination path exists, the +.BR \-f +option is not specified, and either of the following conditions is +true: +.RS 4 +.IP " a." 4 +The permissions of the destination path do not permit writing and the +standard input is a terminal. +.IP " b." 4 +The +.BR \-i +option is specified. +.P +the +.IR mv +utility shall write a prompt to standard error and read a line from +standard input. If the response is not affirmative, +.IR mv +shall do nothing more with the current +.IR source_file +and go on to any remaining +.IR source_file s. +.RE +.IP " 2." 4 +If the +.IR source_file +operand and destination path resolve to either the same existing directory +entry or different directory entries for the same existing file, then the +destination path shall not be removed, and one of the following shall +occur: +.RS 4 +.IP " a." 4 +No change is made to +.IR source_file , +no error occurs, and no diagnostic is issued. +.IP " b." 4 +No change is made to +.IR source_file , +a diagnostic is issued to standard error identifying the two names, +and the exit status is affected. +.IP " c." 4 +If the +.IR source_file +operand and destination path name distinct directory entries, then the +.IR source_file +operand is removed, no error occurs, and no diagnostic is issued. +.P +The +.IR mv +utility shall do nothing more with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 3." 4 +The +.IR mv +utility shall perform actions equivalent to the +\fIrename\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017, called with the following arguments: +.RS 4 +.IP " a." 4 +The +.IR source_file +operand is used as the +.IR old +argument. +.IP " b." 4 +The destination path is used as the +.IR new +argument. +.P +If this succeeds, +.IR mv +shall do nothing more with the current +.IR source_file +and go on to any remaining +.IR source_file s. +If this fails for any reasons other than those described for the +.IR errno +.BR [EXDEV] +in the System Interfaces volume of POSIX.1\(hy2017, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 4." 4 +If the destination path exists, and it is a file of type directory and +.IR source_file +is not a file of type directory, or it is a file not of type directory +and +.IR source_file +is a file of type directory, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +If the destination path exists and was created by a previous step, it +is unspecified whether this will treated as an error or the destination +path will be overwritten. +.IP " 5." 4 +If the destination path exists, +.IR mv +shall attempt to remove it. If this fails for any reason, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.IP " 6." 4 +The file hierarchy rooted in +.IR source_file +shall be duplicated as a file hierarchy rooted in the destination path. If +.IR source_file +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 4 +.IP " *" 4 +The time of last data modification and time of last access +.IP " *" 4 +The user ID and group ID +.IP " *" 4 +The file mode +.P +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. +.P +When files are duplicated to another file system, the implementation +may require that the process invoking +.IR mv +has read access to each file being duplicated. +.P +If files being duplicated to another file system have hard links to +other files, it is unspecified whether the files copied to the new +file system have the hard links preserved or separate copies are created +for the linked files. +.P +If the duplication of the file hierarchy fails for any reason, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.P +If the duplication of the file characteristics fails for any reason, +.IR mv +shall write a diagnostic message to standard error, but this failure +shall not cause +.IR mv +to modify its exit status. +.RE +.IP " 7." 4 +The file hierarchy rooted in +.IR source_file +shall be removed. If this fails for any reason, +.IR mv +shall write a diagnostic message to the standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.SH OPTIONS +The +.IR mv +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-f\fP" 10 +Do not prompt for confirmation if the destination path exists. Any +previous occurrence of the +.BR \-i +option is ignored. +.IP "\fB\-i\fP" 10 +Prompt for confirmation if the destination path exists. Any previous +occurrence of the +.BR \-f +option is ignored. +.P +Specifying more than one of the +.BR \-f +or +.BR \-i +options shall not be considered an error. The last option specified +shall determine the behavior of +.IR mv . +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file or directory to be moved. +.IP "\fItarget_file\fR" 10 +A new pathname for the file or directory being moved. +.IP "\fItarget_dir\fR" 10 +A pathname of an existing directory into which to move the input +files. +.SH STDIN +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" +The input files specified by each +.IR source_file +operand can be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mv : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +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 +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +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" +The output files may be of any file type. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were moved successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If the copying or removal of +.IR source_file +is prematurely terminated by a signal or error, +.IR mv +may leave a partial copy of +.IR source_file +at the source or destination. The +.IR mv +utility shall not modify both +.IR source_file +and the destination path simultaneously; termination at any point shall +leave either +.IR source_file +or the destination path complete. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Some implementations mark for update the last file status change timestamp +of renamed files and some do not. Applications which make use of the +last file status change timestamp may behave differently with respect +to renamed files unless they are designed to allow for either behavior. +.P +The specification ensures that +.IR mv +.BR a +.BR a +will not alter the contents of file +.BR a , +and allows the implementation to issue an error that a file cannot be +moved onto itself. Likewise, when +.BR a +and +.BR b +are hard links to the same file, +.IR mv +.BR a +.BR b +will not alter +.BR b , +but if a diagnostic is not issued, then it is unspecified whether +.BR a +is left untouched (as it would be by the +\fIrename\fR() +function) or unlinked (reducing the link count of +.BR b ). +.SH EXAMPLES +If the current directory contains only files +.BR a +(of any type defined by the System Interfaces volume of POSIX.1\(hy2017), +.BR b +(also of any type), and a directory +.BR c : +.sp +.RS 4 +.nf + +mv a b c +mv c d +.fi +.P +.RE +.P +results with the original files +.BR a +and +.BR b +residing in the directory +.BR d +in the current directory. +.SH RATIONALE +Early proposals diverged from the SVID and BSD historical practice in +that they required that when the destination path exists, the +.BR \-f +option is not specified, and input is not a terminal, +.IR mv +fails. This was done for compatibility with +.IR cp . +The current text returns to historical practice. It should be noted +that this is consistent with the +\fIrename\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2017, which does not require write permission +on the target. +.P +For absolute clarity, paragraph (1), describing the behavior of +.IR mv +when prompting for confirmation, should be interpreted in the following +manner: +.sp +.RS 4 +.nf + +if (exists AND (NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +.fi +.P +.RE +.P +The +.BR \-i +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 +.IR mv +deletes all existing destination paths without prompting, even when +.BR \-i +is specified; this is inconsistent with the behavior of the 4.3 BSD +.IR cp +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 +.BR \-i +is a request for interaction, so when the destination +path exists, the utility takes instructions from whatever responds to +standard input. +.P +The +\fIrename\fR() +function is able to move directories within the same file system. Some +historical versions of +.IR mv +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 POSIX.1\(hy2017 requires directories to be able to be moved +even across file systems. There is no +.BR \-R +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\fR() +function were preserved as much as possible. For example, +.IR mv +is not permitted to ``rename'' files to or from directories, even +though they might be empty and removable. +.P +Historic implementations of +.IR mv +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. +.P +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 +.BR \-f +option or using the +.BR \-i +option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +When +.IR mv +is dealing with a single file system and +.IR source_file +is a symbolic link, the link itself is moved as a consequence of the +dependence on the +\fIrename\fR() +functionality, per the DESCRIPTION. Across file systems, this has to be +made explicit. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcp\fR\^", +.IR "\fIln\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIrename\fR\^(\|)" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |