'\" et

.TH RENAME "3P" 2013 "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 relative to directory file descriptor

.SH SYNOPSIS

.LP

.nf

#include <stdio.h>

.P

int rename(const char *\fIold\fP, const char *\fInew\fP);

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\(hy2008 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 processes 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 file descriptor was opened without O_SEARCH, the function

shall check whether directory searches are permitted using the current

permissions of the directory underlying the file descriptor. If the

file descriptor was opened with 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 \(mi1,

.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 \(mi1 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\(hy2008,

.IR "Section 4.2" ", " "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\(hy2008,

.IR "Section 4.2" ", " "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

.IR oldfd

or

.IR newfd

was not opened with 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

\fB

#include <stdio.h>

.P

int status;

\&...

status = rename("/home/cnd/mod1", "/home/cnd/mod2");

.fi \fR

.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

\fB

rename("x", "x");

.fi \fR

.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\(hy2008,

.IR "Section 4.2" ", " "Directory Protection",

.IR "\fB<stdio.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

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 .