diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/rename.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/rename.3p | 555 |
1 files changed, 555 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/rename.3p b/man-pages-posix-2017/man3p/rename.3p new file mode 100644 index 0000000..383d7ed --- /dev/null +++ b/man-pages-posix-2017/man3p/rename.3p @@ -0,0 +1,555 @@ +'\" et +.TH RENAME "3P" 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 +rename, renameat +\(em rename file +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.P +int rename(const char *\fIold\fP, const char *\fInew\fP); +.P +#include <fcntl.h> +.P +int renameat(int \fIoldfd\fP, const char *\fIold\fP, int \fInewfd\fP, + const char *\fInew\fP); +.fi +.SH DESCRIPTION +For +\fIrename\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIrename\fR() +function shall change the name of a file. The +.IR old +argument points to the pathname of the file to be renamed. The +.IR new +argument points to the new pathname of the file. +If the +.IR new +argument does not resolve to an existing directory entry for a file of +type directory and the +.IR new +argument contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters after all symbolic links have been processed, +\fIrename\fR() +shall fail. +.P +If either the +.IR old +or +.IR new +argument names a symbolic link, +\fIrename\fR() +shall operate on the symbolic link itself, and shall not resolve the +last component of the argument. If the +.IR old +argument and the +.IR new +argument resolve to either the same existing directory entry or different +directory entries for the same existing file, +\fIrename\fR() +shall return successfully and perform no other action. +.P +If the +.IR old +argument points to the pathname of a file that is not a directory, the +.IR new +argument shall not point to the pathname of a directory. If the link +named by the +.IR new +argument exists, it shall be removed and +.IR old +renamed to +.IR new . +In this case, a link named +.IR new +shall remain visible to other threads throughout the renaming operation +and refer either to the file referred to by +.IR new +or +.IR old +before the operation began. Write access permission is required for +both the directory containing +.IR old +and the directory containing +.IR new . +.P +If the +.IR old +argument points to the pathname of a directory, the +.IR new +argument shall not point to the pathname of a file that is not a +directory. If the directory named by the +.IR new +argument exists, it shall be removed and +.IR old +renamed to +.IR new . +In this case, a link named +.IR new +shall exist throughout the renaming operation and shall refer either to +the directory referred to by +.IR new +or +.IR old +before the operation began. If +.IR new +names an existing directory, it shall be required to be an empty +directory. +.P +If either +.IR pathname +argument refers to a path whose final component is either dot or +dot-dot, +\fIrename\fR() +shall fail. +.P +If the +.IR old +argument points to a pathname of a symbolic link, the symbolic link +shall be renamed. If the +.IR new +argument points to a pathname of a symbolic link, the symbolic link +shall be removed. +.P +The +.IR old +pathname shall not name an ancestor directory of the +.IR new +pathname. Write access permission is required for the directory containing +.IR old +and the directory containing +.IR new . +If the +.IR old +argument points to the pathname of a directory, write access permission +may be required for the directory named by +.IR old , +and, if it exists, the directory named by +.IR new . +.P +If the link named by the +.IR new +argument exists and the file's link count becomes 0 when it is removed +and no process has the file open, the space occupied by the file shall +be freed and the file shall no longer be accessible. If one or more +processes have the file open when the last link is removed, the link +shall be removed before +\fIrename\fR() +returns, but the removal of the file contents shall be postponed until +all references to the file are closed. +.P +Upon successful completion, +\fIrename\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory of each file. +.P +If the +\fIrename\fR() +function fails for any reason other than +.BR [EIO] , +any file named by +.IR new +shall be unaffected. +.P +The +\fIrenameat\fR() +function shall be equivalent to the +\fIrename\fR() +function except in the case where either +.IR old +or +.IR new +specifies a relative path. If +.IR old +is a relative path, the file to be renamed is located relative to the +directory associated with the file descriptor +.IR oldfd +instead of the current working directory. If +.IR new +is a relative path, the same happens only relative to the directory +associated with +.IR newfd . +If the access mode of the open file description associated with the +file descriptor is not O_SEARCH, the function shall check whether +directory searches are permitted using the current permissions of +the directory underlying the file descriptor. If the access mode is +O_SEARCH, the function shall not perform the check. +.P +If +\fIrenameat\fR() +is passed the special value AT_FDCWD in the +.IR oldfd +or +.IR newfd +parameter, the current working directory shall be used in the +determination of the file for the respective +.IR path +parameter. +.SH "RETURN VALUE" +Upon successful completion, the +\fIrename\fR() +function shall return 0. Otherwise, it shall return \-1, +.IR errno +shall be set to indicate the error, +and neither the file named by +.IR old +nor the file named by +.IR new +shall be changed or created. +.P +Upon successful completion, the +\fIrenameat\fR() +function shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIrename\fR() +and +\fIrenameat\fR() +functions shall fail if: +.TP +.BR EACCES +A component of either path prefix denies search permission; or one of +the directories containing +.IR old +or +.IR new +denies write permissions; or, write permission is required and is +denied for a directory pointed to by the +.IR old +or +.IR new +arguments. +.TP +.BR EBUSY +The directory named by +.IR old +or +.IR new +is currently in use by the system or another process, and the +implementation considers this an error. +.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12 +.br +The link named by +.IR new +is a directory that is not an empty directory. +.TP +.BR EINVAL +The +.IR old +pathname names an ancestor directory of the +.IR new +pathname, or either pathname argument contains a final component that +is dot or dot-dot. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR EISDIR +The +.IR new +argument points to a directory and the +.IR old +argument points to a file that is not a directory. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMLINK +The file named by +.IR old +is a directory, and the link count of the parent directory of +.IR new +would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +The link named by +.IR old +does not name an existing file, a component of the path prefix of +.IR new +does not exist, or either +.IR old +or +.IR new +points to an empty string. +.TP +.BR ENOSPC +The directory that would contain +.IR new +cannot be extended. +.TP +.BR ENOTDIR +A component of either path prefix names an existing file that is +neither a directory nor a symbolic link to a directory; or the +.IR old +argument names a directory and the +.IR new +argument names a non-directory file; or the +.IR old +argument contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory; or the +.IR old +argument names an existing non-directory file and the +.IR new +argument names a nonexistent file, contains at least one non-\c +<slash> +character, and ends with one or more trailing +<slash> +characters; or the +.IR new +argument names an existing non-directory file, contains at least one non-\c +<slash> +character, and ends with one or more trailing +<slash> +characters. +.TP +.BR EPERM " or " EACCES +.br +The S_ISVTX flag is set on the directory containing the file referred +to by +.IR old +and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection" +with respect to +.IR old ; +or +.IR new +refers to an existing file, the S_ISVTX flag is set on the directory +containing this file, and the process does not satisfy the criteria +specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection" +with respect to this file. +.TP +.BR EROFS +The requested operation requires writing in a directory on a read-only +file system. +.TP +.BR EXDEV +The links named by +.IR new +and +.IR old +are on different file systems and the implementation does not support +links between file systems. +.P +In addition, the +\fIrenameat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR oldfd +or +.IR newfd +is not O_SEARCH and the permissions of the directory underlying +.IR oldfd +or +.IR newfd , +respectively, do not permit directory searches. +.TP +.BR EBADF +The +.IR old +argument does not specify an absolute path and the +.IR oldfd +argument is neither AT_FDCWD nor a valid file descriptor open for +reading or searching, or the +.IR new +argument does not specify an absolute path and the +.IR newfd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR old +or +.IR new +argument is not an absolute path and +.IR oldfd +or +.IR newfd , +respectively, is a file descriptor associated with a non-directory file. +.P +The +\fIrename\fR() +and +\fIrenameat\fR() +functions may fail if: +.TP +.BR EBUSY +The file named by the +.IR old +or +.IR new +arguments is a named STREAM. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The file named by +.IR new +exists and is the last directory entry to a pure procedure (shared text) +file that is being executed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Renaming a File" +.P +The following example shows how to rename a file named +.BR /home/cnd/mod1 +to +.BR /home/cnd/mod2 . +.sp +.RS 4 +.nf + +#include <stdio.h> +.P +int status; +\&... +status = rename("/home/cnd/mod1", "/home/cnd/mod2"); +.fi +.P +.RE +.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. +.SH RATIONALE +This +\fIrename\fR() +function is equivalent for regular files to that defined by the ISO\ C standard. +Its inclusion here expands that definition to include actions on +directories and specifies behavior when the +.IR new +parameter names a file that already exists. That specification +requires that the action of the function be atomic. +.P +One of the reasons for introducing this function was to have a means of +renaming directories while permitting implementations to prohibit the +use of +\fIlink\fR() +and +\fIunlink\fR() +with directories, thus constraining links to directories to those made by +\fImkdir\fR(). +.P +The specification that if +.IR old +and +.IR new +refer to the same file is intended to guarantee that: +.sp +.RS 4 +.nf + +rename("x", "x"); +.fi +.P +.RE +.P +does not remove the file. +.P +Renaming dot or dot-dot is prohibited in order to prevent cyclical file +system paths. +.P +See also the descriptions of +.BR [ENOTEMPTY] +and +.BR [ENAMETOOLONG] +in +\fIrmdir\fR() +and +.BR [EBUSY] +in +\fIunlink\fR(). +For a discussion of +.BR [EXDEV] , +see +\fIlink\fR(). +.P +The purpose of the +\fIrenameat\fR() +function is to rename files in directories other than the current +working directory without exposure to race conditions. Any part of the +path of a file could be changed in parallel to a call to +\fIrename\fR(), +resulting in unspecified behavior. By opening file descriptors for the +source and target directories and using the +\fIrenameat\fR() +function it can be guaranteed that that renamed file is located correctly +and the resulting file is in the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlink\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection", +.IR "\fB<fcntl.h>\fP", +.IR "\fB<stdio.h>\fP" +.\" +.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 . |