rename(2) DG/UX 4.30 rename(2)
NAME
rename - Change the name of a file.
SYNOPSIS
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 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.
Licensed material--property of copyright holder(s) Page 1
rename(2) DG/UX 4.30 rename(2)
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
<new_path>.
RETURN VALUE
0 The file was successfully renamed.
-1 An error occurred. Errno is set to indicate
Licensed material--property of copyright holder(s) Page 2
rename(2) DG/UX 4.30 rename(2)
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.
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
Licensed material--property of copyright holder(s) Page 3
rename(2) DG/UX 4.30 rename(2)
<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).
Licensed material--property of copyright holder(s) Page 4