int
rename(
const char *from
, const char *to
)
)
causes the link named
from
to be renamed as
to
.
If
to
exists, it is first removed.
Both
from
and
to
must be of the same type (that is, both directories or both
non-directories), and must reside on the same file system.
rename()
guarantees that an instance of
to
will always exist, even if the system should crash in
the middle of the operation.
If the final component of
from
is a symbolic link,
the symbolic link is renamed,
not the file or directory to which it points.
If both
from
and
to
are pathnames of the same existing file in the file system's name space,
rename()
returns successfully and performs no other action.
)
returns -1 and the global variable
errno
indicates the reason for the failure.
)
will fail and neither of the argument files will be
affected if:
ENAMETOOLONG
]
{NAME_MAX}
characters, or an entire path name exceeded
{PATH_MAX}
characters.
ENOENT
]
from
path does not exist,
or a path prefix of
to
does not exist.
EACCES
]
EPERM
]
from
is marked sticky,
and neither the containing directory nor
from
are owned by the effective user ID.
Or the
to
file exists,
the directory containing
to
is marked sticky,
and neither the containing directory nor
to
are owned by the effective user ID.
ELOOP
]
ENOTDIR
]
from
is a directory, but
to
is not a directory.
EISDIR
]
to
is a directory, but
from
is not a directory.
EXDEV
]
to
and the file named by
from
are on different logical devices (file systems).
Note that this error code will not be returned if the implementation
permits cross-device links.
ENOSPC
]
EDQUOT
]
EIO
]
EROFS
]
EFAULT
]
EINVAL
]
from
is a parent directory of
to
,
or an attempt is made to rename
`.'
or
`..'.
ENOTEMPTY
]
to
is a directory and is not empty.
EBUSY
]
from
or
to
is the mount point for a mounted file system.
)
function deviates from the semantics defined in
ISO/IEC 9945-1:1990 (``POSIX.1'') ,
which specifies that if both
from
and
to
link
to the same existing file,
rename(
)
shall return successfully and performs no further action, whereas this
implementation will remove the file specified by
from
unless both
from
and
to
are pathnames of the same file in the file system's name space.
To retain conformance, a compatibility interface is provided by the
POSIX Compatibility Library (libposix, -lposix)
which is also be brought into scope if any of the
_POSIX_SOURCE
,
_POSIX_C_SOURCE
or
_XOPEN_SOURCE
preprocessor symbols are defined at compile-time:
the
rename()
function conforms to
ISO/IEC 9945-1:1990 (``POSIX.1'')
and
X/Open Portability Guide Issue 4, Version 2 (``XPG4.2'') .
a
',
say
`
a/foo
',
being a hard link to directory
`
b
',
and an entry in
directory
`
b
',
say
`
b/bar
',
being a hard link
to directory
`
a
'.
When such a loop exists and two separate processes attempt to
perform
`rename a/foo b/bar'
and
`rename b/bar a/foo',
respectively,
the system may deadlock attempting to lock
both directories for modification.
Hard links to directories should be
replaced by symbolic links by the system administrator.