rename Subroutine

Base Operating System and Extensions Technical Reference, Volume 2

rename Subroutine

Purpose

Renames a directory or a file.

Library

Standard C Library (libc.a)

Syntax

#include <stdio.h>

int rename (FromPath, ToPath)
const char *FromPath, *ToPath;

Description

The rename subroutine renames a directory or a file within a file system.

To use the rename subroutine, the calling process must have write and search permission in the parent directories of both the FromPath and ToPath parameters. If the path defined in the FromPath parameter is a directory, the calling process must have write and search permission to the FromPath directory as well.

If the FromPath and ToPath parameters both refer to the same existing file, the rename subroutine returns successfully and performs no other action.

The components of both the FromPath and ToPath parameters must be of the same type (that is, both directories or both non-directories) and must reside on the same file system. If the ToPath file already exists, it is first removed. Removing it guarantees that a link named ToPath will exist throughout the operation. This link refers to the file named by either the ToPath or FromPath parameter before the operation began.

If the final component of the FromPath parameter is a symbolic link, the symbolic link (not the file or directory to which it points) is renamed. If the ToPath is a symbolic link, the link is destroyed.

If the parent directory of the FromPath parameter has the Sticky bit attribute (described in the sys/mode.h file), the calling process must have an effective user ID equal to the owner ID of the FromPath parameter, or to the owner ID of the parent directory of the FromPath parameter.

A user who is not the owner of the file or directory must have root user authority to use the rename subroutine.

If the FromPath and ToPath parameters name directories, the following must be true:

The directory specified by the FromPath parameter is not an ancestor of ToPath. For example, the FromPath path name must not contain a path prefix that names the directory specified by the ToPath parameter.
The directory specified in the FromPath parameter must be well-formed. A well-formed directory contains both . (dot) and .. (dot dot) entries. That is, the . (dot) entry in the FromPath directory refers to the same directory as that in the FromPath parameter. The .. (dot dot) entry in the FromPath directory refers to the directory that contains an entry for FromPath.
The directory specified by the ToPath parameter, if it exists, must be well-formed (as defined previously).

Parameters

FromPath	Identifies the file or directory to be renamed.
ToPath	Identifies the new path name of the file or directory to be renamed. If ToPath is an existing file or empty directory, it is replaced by FromPath. If ToPath specifies a directory that is not empty, the rename subroutine exits with an error.

Return Values

Upon successful completion, the rename subroutine returns a value of 0. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The rename subroutine is unsuccessful and the file or directory name remains unchanged if one or more of the following are true:

EACCES	Creating the requested link requires writing in a directory mode that denies the process write permission.
EBUSY	The directory named by the FromPath or ToPath parameter is currently in use by the system, or the file named by FromPath or ToPath is a named STREAM.
EDQUOT	The directory that would contain the path specified by the ToPath parameter cannot be extended because the user's or group's quota of disk blocks on the file system containing the directory is exhausted.
EEXIST	The ToPath parameter specifies an existing directory that is not empty.
EINVAL	The path specified in the FromPath or ToPath parameter is not a well-formed directory (FromPath is an ancestor of ToPath), or an attempt has been made to rename . (dot) or .. (dot dot).
EISDIR	The ToPath parameter names a directory and the FromPath parameter names a non-directory.
EMLINK	The FromPath parameter names a directory that is larger than the maximum link count of the parent directory of the ToPath parameter.
ENOENT	A component of either path does not exist, the file named by the FromPath parameter does not exist, or a symbolic link was named, but the file to which it refers does not exist.
ENOSPC	The directory that would contain the path specified in the ToPath parameter cannot be extended because the file system is out of space.
ENOTDIR	The FromPath parameter names a directory and the ToPath parameter names a non-directory.
ENOTEMPTY	The ToPath parameter specifies an existing directory that is not empty.
EROFS	The requested operation requires writing in a directory on a read-only file system.
ETXTBSY	The ToPath parameter names a shared text file that is currently being used.
EXDEV	The link named by the ToPath parameter and the file named by the FromPath parameter are on different file systems.

If Network File System (NFS) is installed on the system, the rename subroutine can be unsuccessful if the following is true:

ETIMEDOUT

The connection timed out.

The rename subroutine can be unsuccessful for other reasons. See "Base Operating System Error Codes For Services That Require Path-Name Resolution" for a list of additional errors.

The rename subroutine can be unsuccessful for other reasons. See Appendix A, "Base Operating System Error Codes For Services That Require Path-Name Resolution" on page A-1 for a list of additional errors.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The chmod subroutine, link subroutine, mkdir subroutine, rmdir subroutine, unlink subroutine.

The chmod command, mkdir command, mv command, mvdir command.

Files, Directories, and File Systems for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.