wcs_rename(2)                                             wcs_rename(2)

  rename()

  NAME

    rename(), wcs_rename - change the name of a file

  SYNOPSIS

    #include 

    int rename (const char *from, const char *to)
    int wcs_rename (const wchar_t *from, const wchar_t *to)

  DESCRIPTION

    The rename(2) and wcs_rename(2) functions are identical, except that
    wcs_rename(2) accepts wide characters in the from and to arguments.

    The rename(2) and wcs_rename(2) functions cause 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.

    The rename(2) or wcs_rename(2) function guarantees that an instance of to
    will always exist, even if the system should crash in the middle of the
    operation.

    The process doesn't require write access for the from or to directories in
    order for the call to succeed.

  RETURN VALUES

    A 0 value is returned if the operation succeeds, otherwise rename(2) or
    wcs_rename(2) returns -1 and the global variable errno indicates the
    reason for the failure.

  ERRORS

    The rename(2) or wcs_rename(2) function will fail and neither of the
    argument files will be affected if:

    [EACCES]
        A component of either path prefix denies search permission.

    [EACCES]
        The requested link requires writing in a directory with a mode that
        denies write permission.

    [EFAULT]
        Path points outside the process's allocated address space.

    [EINVAL]
        Either pathname contains a character with the high-order bit set.

    [EINVAL]
        From is a parent directory of to, or an attempt is made to rename . or
        ...

    [EIO]
        An I/O error occurred while making or updating a directory entry.

    [EISDIR]
        To is a directory, but from is not a directory.

    [ELOOP]
        Too many symbolic links were encountered in translating either
        pathname.

    [ENAMETOOLONG]
        A component of either pathname exceeded {NAME_MAX} characters, or the
        entire length of either pathname exceeded {PATH_MAX} characters.

    [ENOENT]
        A component of the from path does not exist, or a path prefix of to
        does not exist.

    [ENOSPC]
        The directory in which the entry for the new name is being placed
        cannot be extended because there is no space left on the file system
        containing the directory.

    [ENOTDIR]
        A component of either path prefix is not a directory.

    [ENOTDIR]
        from is a directory, but to is not a directory.

    [ENOTEMPTY]
        To is a directory and is not empty.

    [EPERM]
        The directory containing from is marked sticky, and neither the
        containing directory nor from are owned by the effective user ID.

    [EPERM]
        The file cannot be moved or renamed to different file system (for
        example, /dev/fs/C/dog to /dev/fs/D/dog

    [EROFS]
        The requested link requires writing in a directory on a read-only file
        system.

    [EXDEV]
        The link named by 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.

  SEE ALSO

    open(2)

  USAGE NOTES

    All of these functions are thread safe.

    All of these functions are async-signal safe.