rename, renameat - rename file

Syntax	#include <stdio.h> int rename(const char *old, const char *new); int renameat(int oldfd, const char *old, int newfd, const char *new);
Description	rename() changes the name of a file. The old argument points to the pathname of the file to be renamed. The new argument points to the new pathname of the file. If old and new both refer to the same existing file, rename() returns successfully and performs no other action. If old points to the pathname of a file that is not a directory, new must not point to the pathname of a directory. If the link named by the new argument exists, it is removed, and old is renamed to new. In this case, a link named new will remain visible to other processes throughout the renaming operation and will refer either to the file referred to by new or old before the operation began. Write access permission is required for both the directory containing old and the directory containing new. If old points to the pathname of a directory, new must not point to the pathname of a file that is not a directory. If the directory named by the new argument exists, it is removed, and old is renamed to new. In this case, a link named new will exist throughout the renaming operation and will refer either to the file referred to by new or old before the operation began. Thus, if new names an existing directory, it must be an empty directory. The pathname prefix of new must not be identical to old. Write access permission is required for the directory containing old and the directory containing new. If old points to the pathname of a directory, write access permission may be required for the directory named by old, and, if it exists, the directory named by new. If the link named by new 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 will be freed, and the file will no longer be accessible. If one or more processes have the file open when the last link is removed, the link will be removed before rename() returns, but the removal of the file contents will be postponed until all references to the file are closed. Upon successful completion, rename() will mark for update the st_ctime and st_mtime fields of the parent directory of each file. BS2000 rename() can also be used without changes for files with record I/O. (End) The renameat() function is equivalent to the rename() function except when the old or new parameter specifies a relative path. If old specifies a relative pathname, the file which is to be renamed is searched for not in the current directory, but in that connected with the file descriptor oldfd. If new specifies a relative pathname, the same happens relative to the directory connected with the file descriptor newfd. If a file descriptor was opened without O_SEARCH, the function checks whether a search is permitted in the connected file descriptor with the authorizations applicable for the directory. If the file descriptor was opened with O_SEARCH, the check is not performed. When the value AT_FDCWD is transferred to the renameat() function for the oldfd or newfd parameter, the current directory for determining the file of the corresponding path is used.
Return val.	0	if successful.
	-1	if an error occurs; errno is set to indicate the error. Neither the file named by old nor the file named by new will be changed or created. BS2000 errno is set to EMACRO. If old and new point to files from different file systems, no changes are made. errno is set to EXDEV. (End)
Errors	rename() and renameat() will fail if:
	EACCES	A component of either path prefix denies search permission; or one of the directories containing old or new denies write permissions; or write permission is required and is denied for a directory pointed to by the old or new arguments.
	EBUSY	One of the directories named by old or new is currently in use by the system or another process, and the implementation considers this an error.
	Extension
	EDQUOT	The directory in which the entry for the new name is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. (End)
	EEXIST or ENOTEMPTY
		The link specified by new is a non-empty directory.
	Extension
	EFAULT	old or new points outside the allocated address space of the process.
	EINTR	A signal was caught during execution of the rename() system call. (End)
	EINVAL	The directory pathname new contains a path prefix that designates the directory old (see also "Notes").
	Extension
	EIO	An I/O error occurred when creating or updating a directory entry. (End)
	EISDIR	The new argument points to a directory and the old argument points to a file that is not a directory.
	Extension
	ELOOP	Too many symbolic links were encountered in resolving old or new. (End)
	BS2000
	EMACRO	There is no existing file with the name old or there is already a file cataloged under the name new or the file to be renamed has been opened by a program. (End)
	EMLINK	old points to a directory, and the link count of the parent directory of new exceeds {LINK_MAX}.
	ENAMETOOLONG
		The length of old or new exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
	ENOENT	The link named by old does not name an existing file, or either old or new points to an empty string.
	ENOSPC	The directory that would contain new cannot be extended.
	ENOTDIR	A component of either path is not a directory, or the old argument names a directory, and the new argument names a non-directory file.
	EROFS	The requested operation requires writing in a directory on a read-only file system.
	EXDEV	The links named by new and old are on different file systems.
	In addition, renameat() fails if the following applies:
	EACCES	The file descriptor oldfd or newfd was not opened with O_SEARCH, and the authorizations applicable for the directory do not permit the directory to be searched.
	EBADF	The old parameter does not specify an absolute pathname, and the oldfd parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor opened for reading or searching, or the new parameter does not specify an absolute pathname, and the newfd parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor for reading or searching.
	ENOTDIR	The old or new parameter does not specify an absolute pathname, and the corresponding file descriptor oldfd / newfd is not connected with a directory.
Notes	rename() cannot be used to relocate a file from the POSIX subsystem to BS2000 or vice-versa. The following statement, for example, will produce the error EINVAL: rename(/BS2/hugo, *POSIX(hugo)) The program environment determines whether rename() is executed for a BS2000 or POSIX file.
See also	link(), rmdir(), unlink(), fcntl.h, stdio.h.