R Parent topic: R

renameat()

Updated: October 28, 2024

Rename a file at a given location

Synopsis:

#include <stdio.h>

int renameat( int olddirfd, 
              const char* old,
              int newdirfd,
              const char* new );

Arguments:

olddirfd
A file descriptor that indicates the base directory for relative file paths. The pathname given in old is resolved by appending it to the directory associated with olddirfd. You can set this argument to AT_FDCWD to use the current working directory as the base directory.
Note: You must use a file descriptor obtained from an open() call with the O_DIRECTORY flag set. Otherwise, the function fails and sets errno to EBADF.

If old specifies an absolute path, olddirfd has no effect.

old
The path to the file that you want to rename. This path can be absolute or relative; for details of how relative path resolution is done, see above.
newdirfd
A file descriptor that indicates the base directory for relative file paths. The pathname given in new is resolved by appending it to the directory associated with newdirfd. You can set this argument to AT_FDCWD to use the current working directory as the base directory.
Note: You must use a file descriptor obtained from an open() call with the O_DIRECTORY flag set. Otherwise, the function fails and sets errno to EBADF.

If new specifies an absolute path, newdirfd has no effect.

new
The new pathname for the file. This path can be absolute or relative; for details of how relative path resolution is done, see above.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The renameat() function changes the name of the file indicated by old to the name given in new. Each of the old and new arguments can contain an absolute or a relative path. In the latter case, the corresponding file descriptor argument (olddirfd for old and newdirfd for new) is used to resolve the pathname, as explained in the descriptions of these arguments (above).

If new identifies an existing file or empty directory, renameat() overwrites it.

Returns:

0
Success.
Nonzero
An error occurred (errno is set).

Errors:

EACCES
One of the following is true:
  • A component of the path prefix in old or new denies search permission.
  • You don't have permission to search the directory underlying olddirfd or newdirfd.
  • One of the directories containing old or new denies write permission.
EBADF
One of the paths (old or new) does not specify an absolute path and the corresponding file descriptor (olddirfd or newdirfd) is neither AT_FDCWD nor a valid file descriptor open for reading or searching. Or, one of the file descriptors (olddirfd or newdirfd) was created without O_DIRECTORY set.
EBUSY
The directory named by old or new can't be renamed because another process is using it.
EEXIST
The file specified by new is a directory that contains files.
EINVAL
The new directory pathname contains the old directory.
EISDIR
The file specified by new is a directory and old is a file.
ELOOP
Too many levels of symbolic links.
EMLINK
The file named by old is a directory, and the link count of the parent directory of new would exceed LINK_MAX.
ENAMETOOLONG
The length of old or new exceeds PATH_MAX.
ENOENT
The old file doesn't exist, or old or new is an empty string.
ENOSPC
The directory that would contain new can't be extended.
ENOSYS
The renameat() function isn't implemented for the filesystem underlying the path specified in old or new.
ENOTDIR
One of the following is true:
  • A component of the path prefix in old or new names an existing file that is neither a directory nor a symbolic link to one.
  • The path in old is an existing directory but the one in new isn't.
  • The path in old or new contains at least one non-slash character, ends with at least one slash character (/), and the last component names an existing file that is neither a directory nor a symbolic link to one.
  • The old or new argument isn't an absolute path and the associated olddirfd or newdirfd file descriptor is associated with a non-directory file.
ENOTEMPTY
The file specified by new is a directory that contains files.
EROFS
The renameat() would affect files on a read-only filesystem.
EXDEV
The files or directories named by old and new are on different filesystems.

Classification:

ANSI, POSIX 1003.1

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes
Parent topic: R