rename(2)
_________________________________________________________________
rename System Call
Change the name of a file.
_________________________________________________________________
SYNTAX
int rename (old_path, new_path)
char * old_path;
char * new_path;
PARAMETERS
old_path Address of the pathname of the file being renamed.
new_path Address of file's new pathname.
DESCRIPTION
<Old_path> points to a pathname naming an existing file that will
be called the source file. <New_path> 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, <old_path> must not be an ancestor
of <new_path>. This prevents the rename operation from orphaning
everything in the file hierarchy below <old_path>. If <new_path>
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 <old_path> and the source file is
deleted, though there may be other links to the source file. If
the target file exists, the link between <new_path> and the
target is also deleted. Lastly, a link between the pathname
<new_path> and the source file is created. This sequence of
events is described in more detail below:
If <new_path> does not exist in the filename store, a link for it
is created in the directory indicated by the path prefix of
<new_path>. The link is made to refer to the same entity in the
filesystem that <old_path> refers to.
If <new_path> already exists in the filename store, the link in
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
rename(2)
its containing directory is changed to refer to the same entity
in the filesystem that <old_path> refers to. If this change
deletes the last link to the file formerly referred to by
<new_path>, that file is deleted.
<Old_path> 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 <old_path> and possibly, the addition of an
entry for <new_path>.
* 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 <new_path>.
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 <old_path> and
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
rename(2)
<new_path>.
RETURN VALUE
0 The file was successfully renamed.
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EPERM The file named by <old_path> is a directory and
the effective user id is not superuser.
EXDEV The link named by <new_path> and the file named by
<old_path> 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 <old_path> is an ancestor
directory of the file named by <new_path>.
EINVAL The file named by <old_path> is '.' or '..'.
EISDIR <Old_path> is a directory and <new_path> is not.
ENOSPC No more contiguous space for a new directory
entry.
EEXIST <New_path> points to a non-empty directory.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
rename(2)
ENOENT <Old_path> does not exist.
ENOENT A non-terminal component of <old_path> or
<new_path> does not exist.
ENOTDIR A non-terminal component of <old_path> or
<new_path> was not a directory or symbolic link.
ENAMETOOLONG <Old_path> or <new_path> exceeds the length limit
for pathnames.
ENAMETOOLONG A component of <old_path> or <new_path> exceeds
the length limit for filenames.
ENOMEM There are not enough system resources to resolve
<old_path> or <new_path> 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 <Old_path> or <new_path> contains a character not
in the allowed character set.
EFAULT <Old_path> or <new_path> does not completely
reside in the process's address space or the
pathname does not terminate in the process's
address space.
SEE ALSO
The related manual sections: mv(1), mvdir(1),
open(2),
stat(5).
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)