NAME

zkRename - rename a file

SYNOPSIS

#include "zkStdio.h"

int zkRename(const char* old, const char* new);

DESCRIPTION

The zkRename() function changes the name of a file. The old argument points to the pathname of the file to be renamed. The new argument points to the new pathname of the file.

The results when the old argument and the new argument both refer to the same existing file, or when the file named by the new argument exists, are implementation-defined.

RETURN VALUE

Upon successful completion, zkRename() returns 0. Otherwise, -1 is returned, errno is set to indicate the error, and neither the file named by old nor the file named by new will be changed or created.

ERRORS

The zkRename() function will fail if:

[EACCES]
A component of either path prefix denies search permission; or one of the directories containing old or new denies write permissions; or, write permission is required and is denied for a directory pointed to by the old or new arguments.
[EBUSY]
The directory named by old or new is currently in use by the system or another process, and the implementation considers this an error.
[EEXIST] or [ENOTEMPTY]
The link named by new is a directory that is not an empty directory.
[EINVAL]
The new directory pathname contains a path prefix that names the old directory.
[EIO]
A physical I/O error has occurred.
[EISDIR]
The new argument points to a directory and the old argument points to a file that is not a directory.
[ELOOP]
Too many symbolic links were encountered in resolving either pathname.
[EMLINK]
The file named by old is a directory, and the link count of the parent directory of new would exceed {LINK_MAX}.
[ENAMETOOLONG]
The length of the old or new argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
[ENOENT]
The link named by old does not name an existing file, or either old or new points to an empty string.
[ENOSPC]
The directory that would contain new cannot be extended.
[ENOTDIR]
A component of either path prefix is not a directory; or the old argument names a directory and new argument names a non-directory file.
[EPERM] or [EACCES]
The S_ISVTX flag is set on the directory containing the file referred to by old and the caller is not the file owner, nor is the caller the directory owner, nor does the caller have appropriate privileges; or new refers to an existing file, the S_ISVTX flag is set on the directory containing this file and the caller is not the file owner, nor is the caller the directory owner, nor does the caller have appropriate privileges.
[EROFS]
The requested operation requires writing in a directory on a read-only file system.
[EXDEV]
The links named by new and old are on different file systems and the implementation does not support links between file systems.

The zkRename() function may fail if:

[EBUSY]
The file named by the old  or new arguments is a named STREAM.
[ENAMETOOLONG]
Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.
[ETXTBSY]
The file to be renamed is a pure procedure (shared text) file that is being executed.

PORTABILITY

The results of the zkRename() function when the old argument and the new argument both refer to the same existing file, or when the file named by the new argument exists, are implementation-defined.

The zkRename() function may only be used portably on regular files.