RENAME(2) | System Calls Manual | RENAME(2) |
rename
, renameat
—
#include <stdio.h>
int
rename
(const
char *from, const char
*to);
#include
<unistd.h>
int
renameat
(int
fromfd, const char
*from, int tofd,
const char *to);
rename
() causes the link named
from to be renamed as to. If
to exists, it is first removed. Both
from and to must be of the same
type (that is, both directories or both non-directories), and must reside on
the same file system.
rename
() guarantees that an instance of
to will always exist, even if the system should crash
in the middle of the operation.
If the final component of from is a symbolic link, the symbolic link is renamed, not the file or directory to which it points.
If both from and to
are pathnames of the same existing file in the file system's name space,
rename
() returns successfully and performs no other
action.
renameat
() works the same way as
rename
() except if from (resp.
to) is relative. In that case, it is looked up from a
directory whose file descriptor was passed as fromfd
(resp. tofd). Search permission is required on the
directories named by fromfd and
tofd. fromfd or
tofd can be set to AT_FDCWD
in
order to specify the current directory.
rename
() and renameat
()
functions return the value 0 if successful; otherwise the
value -1 is returned and the global variable
errno is set to indicate the error.
rename
() and renameat
() will
fail and neither of the argument files will be affected if:
EACCES
]EBUSY
]EDQUOT
]EFAULT
]EINVAL
].
’ or
‘..
’.EIO
]EISDIR
]ELOOP
]ENAMETOOLONG
]NAME_MAX
}
characters, or an entire path name exceeded
{PATH_MAX
} characters.ENOENT
]ENOSPC
]ENOTDIR
]ENOTEMPTY
]EPERM
]EROFS
]EXDEV
]In addition, renameat
() will fail if:
EBADF
]AT_FDCWD
nor a valid file descriptor open for
reading or searching.ENOTDIR
]rename
() function deviates from the semantics
defined in IEEE Std 1003.1-1990
(“POSIX.1”), which specifies that if both
from and to link
to the same existing file, rename
() shall return
successfully and performs no further action, whereas this implementation will
remove the file specified by from unless both
from and to are pathnames of the
same file in the file system's name space.
To retain conformance, a compatibility interface is provided by
the POSIX Compatibility Library (libposix, -lposix)
which is also be brought into scope if any of the
_POSIX_SOURCE
,
_POSIX_C_SOURCE
or
_XOPEN_SOURCE
preprocessor symbols are defined at
compile-time: the rename
() function conforms to
IEEE Std 1003.1-1990 (“POSIX.1”) and
X/Open Portability Guide Issue 4, Version 2
(“XPG4.2”). renameat
() conforms
to IEEE Std 1003.1-2008
(“POSIX.1”).
a
’, say
‘a/foo
’, being a
hard link to directory
‘b
’, and an
entry in directory
‘b
’, say
‘b/bar
’, being a
hard link to directory
‘a
’. When such a
loop exists and two separate processes attempt to perform
‘rename a/foo b/bar
’ and
‘rename b/bar a/foo
’, respectively, the
system may deadlock attempting to lock both directories for modification. Hard
links to directories should be replaced by symbolic links by the system
administrator.
July 28, 2013 | NetBSD 9.0 |