rename(2) SDK R4.11 rename(2)
NAME
rename - change the name of a file
SYNOPSIS
int rename (oldpath, newpath)
const char * oldpath;
const char * newpath;
where:
oldpath Address of the pathname of the file being renamed
newpath Address of file's new pathname
DESCRIPTION
Oldpath points to a pathname naming an existing file that will be
called the source file. Newpath points to a pathname naming a
target file that may or may not exist. If the target exists, it must
be the same type as the source file. In either case, the source and
target must reside on the same file system device. '.' and '..'
cannot be renamed. Terminal symbolic links for either pathname are
not followed.
If both files are directories, oldpath must not be an ancestor of
newpath. This prevents the rename operation from orphaning
everything in the file hierarchy below oldpath. If newpath is an
existing directory, it must contain no entries but '.' and '..', and
the only links to it should be its '.' entry and its entry in its
parent.
The link between the pathname oldpath and the source file is
deleted, though there may be other links to the source file. If the
target file exists, the link between newpath and the target is also
deleted. Lastly, a link between the pathname newpath and the source
file is created. This sequence of events is described in more detail
below:
If newpath does not exist in the filename store, a link for it is
created in the directory indicated by the path prefix of newpath.
The link is made to refer to the same entity in the filesystem that
oldpath refers to.
If newpath already exists in the filename store, the link in its
containing directory is changed to refer to the same entity in the
filesystem that oldpath refers to. If this change deletes the last
link to the file formerly referred to by newpath, that file is
deleted.
Oldpath is removed from the filename store.
The attributes of the files involved change as follows:
· Source File - The time of last attribute change (st_ctime) is
set to the current time.
· Target File (if it existed and was not deleted) - The number
of links (st_nlink) is decremented. The time of last
attribute change (st_ctime) is set to the current time.
· Containing Directory of Source File - The time last modified
(st_mtime) and time of last attribute change (st_ctime) are
set to the current time. If rename is operating on
directories and either the target file existed or the parent
of the target file differs from the parent of the source file,
the number of links (st_nlink) is decremented. The file size
(st_size) is updated to reflect the deletion of the entry for
oldpath and possibly, the addition of an entry for newpath.
· Containing Directory of Target File (assuming it differs from
the containing directory of the source file) - If rename is
operating on directories and the target file didn't exist, the
number of links (st_nlink) is incremented and the time of last
attribute change (st_ctime) is set to the current time. (This
reflects that the '..' of the source is set to a new
directory, namely, what was the parent of the target file.)
The file size (st_size) is updated if the target file didn't
exist, reflecting the addition of an entry for newpath.
If the call fails, the attributes of all files and directories are
unchanged.
ACCESS CONTROL
If the source file is a directory and its parent will change, the
calling process must have write access to the source in order to
change its '..' entry.
The process must have write permission to the containing directories.
The process must have permission to resolve oldpath and newpath.
RETURN VALUE
0 The file was successfully renamed.
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EPERM The file named by oldpath is a directory and the
calling process does not have appropriate privilege.
For traditional DG/UX systems, this means the
effective user id of the caller is not 0. (See the
appropriateprivilege(5) man page for more
information.)
For systems supporting the DG/UX Capability Option, this means the
caller did not have one or more specific capabilities enabled in its
effective capability set. See capdefaults(5) for the default
capability for this system call.
EXDEV The link named by newpath and the file named by oldpath are
on different logical devices (file systems). Note that this
error code will not be returned if the implementation permits
cross-device links.
EACCES The requested link requires writing in a directory with a mode
that denies write permission.
EROFS The requested link requires writing in a directory on a read-
only file system device.
EINVAL The file named by oldpath is an ancestor directory of the
file named by newpath.
EINVAL The file named by oldpath is '.' or '..'.
EISDIR Oldpath is a directory and newpath is not.
ENOSPC No more contiguous space for a new directory entry.
EEXIST Newpath points to a non-empty directory.
ENOENT Oldpath does not exist.
ENOENT A non-terminal component of oldpath or newpath does not
exist.
ENOTDIR
A non-terminal component of oldpath or newpath was not a
directory or symbolic link.
ENAMETOOLONG
Oldpath or newpath exceeds the length limit for pathnames.
ENAMETOOLONG
A component of oldpath or newpath exceeds the length limit
for filenames.
ENOMEM There are not enough system resources to resolve oldpath or
newpath or to expand a symbolic link.
ELOOP The number of symbolic links encountered during pathname
resolution exceeded MAXSYMLINKS. A symbolic link cycle is
suspected.
EPERM Oldpath or newpath contains a character not in the allowed
character set.
EFAULT Oldpath or newpath does not completely reside in the
process's address space or the pathname does not terminate in
the process's address space.
SEE ALSO
mv(1), mvdir(1M), open(2), appropriateprivilege(5), stat(5).
capdefaults(5).
Licensed material--property of copyright holder(s)