renameat()

Arguments:

olddirfd

A file descriptor that indicates the base directory for relative filepaths. 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 filepaths. 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