rename.3p (13771B)
- '\" 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 .