| 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.4 |