rename(2) DG/UX 5.4.2 rename(2)
NAME
rename - change the name of a file
SYNOPSIS
int rename (oldpath, newpath)
char * oldpath;
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.
Licensed material--property of copyright holder(s) 1
rename(2) DG/UX 5.4.2 rename(2)
⊕ 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
effective user id is not superuser.
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.
Licensed material--property of copyright holder(s) 2
rename(2) DG/UX 5.4.2 rename(2)
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), stat(5).
Licensed material--property of copyright holder(s) 3