+++ /dev/null
-.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
-.\" and Copyright (C) 1993 Michael Haardt;
-.\" and Copyright (C) 1993,1995 Ian Jackson
-.\" and Copyright (C) 2006, 2014 Michael Kerrisk
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith <faith@cs.unc.edu>
-.\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer <aeb@cwi.nl>
-.\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt <michael@moria.de>
-.\" 2007-03-25, mtk, added various text to DESCRIPTION.
-.\"
-.TH RENAME 2 2014-08-19 "Linux" "Linux Programmer's Manual"
-.SH NAME
-rename, renameat, renameat2 \- change the name or location of a file
-.SH SYNOPSIS
-.nf
-.B #include <stdio.h>
-.sp
-.BI "int rename(const char *" oldpath ", const char *" newpath );
-.sp
-.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
-.B #include <stdio.h>
-.sp
-.BI "int renameat(int " olddirfd ", const char *" oldpath ,
-.BI " int " newdirfd ", const char *" newpath );
-
-.BI "int renameat2(int " olddirfd ", const char *" oldpath ,
-.BI " int " newdirfd ", const char *" newpath \
-", unsigned int " flags );
-.fi
-.sp
-.in -4n
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.BR renameat ():
-.PD 0
-.ad l
-.RS 4
-.TP 4
-Since glibc 2.10:
-_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
-.TP
-Before glibc 2.10:
-_ATFILE_SOURCE
-.\" FIXME . need to define FTMs for renameat2(), once it hits glibc
-.RE
-.ad
-.PD
-.SH DESCRIPTION
-.BR rename ()
-renames a file, moving it between directories if required.
-Any other hard links to the file (as created using
-.BR link (2))
-are unaffected.
-Open file descriptors for
-.I oldpath
-are also unaffected.
-
-If
-.I newpath
-already exists, it will be atomically replaced (subject to
-a few conditions; see ERRORS below), so that there is
-no point at which another process attempting to access
-.I newpath
-will find it missing.
-
-If
-.I oldpath
-and
-.I newpath
-are existing hard links referring to the same file, then
-.BR rename ()
-does nothing, and returns a success status.
-
-If
-.I newpath
-exists but the operation fails for some reason,
-.BR rename ()
-guarantees to leave an instance of
-.I newpath
-in place.
-
-.I oldpath
-can specify a directory.
-In this case,
-.I newpath
-must either not exist, or it must specify an empty directory.
-
-However, when overwriting there will probably be a window in which
-both
-.I oldpath
-and
-.I newpath
-refer to the file being renamed.
-
-If
-.I oldpath
-refers to a symbolic link, the link is renamed; if
-.I newpath
-refers to a symbolic link, the link will be overwritten.
-.SS renameat()
-The
-.BR renameat ()
-system call operates in exactly the same way as
-.BR rename (),
-except for the differences described here.
-
-If the pathname given in
-.I oldpath
-is relative, then it is interpreted relative to the directory
-referred to by the file descriptor
-.I olddirfd
-(rather than relative to the current working directory of
-the calling process, as is done by
-.BR rename ()
-for a relative pathname).
-
-If
-.I oldpath
-is relative and
-.I olddirfd
-is the special value
-.BR AT_FDCWD ,
-then
-.I oldpath
-is interpreted relative to the current working
-directory of the calling process (like
-.BR rename ()).
-
-If
-.I oldpath
-is absolute, then
-.I olddirfd
-is ignored.
-
-The interpretation of
-.I newpath
-is as for
-.IR oldpath ,
-except that a relative pathname is interpreted relative
-to the directory referred to by the file descriptor
-.IR newdirfd .
-
-See
-.BR openat (2)
-for an explanation of the need for
-.BR renameat ().
-.SS renameat2()
-.BR renameat2 ()
-has an additional
-.I flags
-argument.
-A
-.BR renameat2 ()
-call with a zero
-.I flags
-argument is equivalent to
-.BR renameat ().
-
-The
-.I flags
-argument is a bit mask consisting of zero or more of the following flags:
-.TP
-.B RENAME_NOREPLACE
-Don't overwrite
-.IR newpath
-of the rename.
-Return an error if
-.IR newpath
-already exists.
-.TP
-.B RENAME_EXCHANGE
-Atomically exchange
-.IR oldpath
-and
-.IR newpath .
-Both pathnames must exist
-but may be of different types (e.g., one could be a non-empty directory
-and the other a symbolic link).
-.SH RETURN VALUE
-On success, zero is returned.
-On error, \-1 is returned, and
-.I errno
-is set appropriately.
-.SH ERRORS
-.TP
-.B EACCES
-Write permission is denied for the directory containing
-.I oldpath
-or
-.IR newpath ,
-or, search permission is denied for one of the directories
-in the path prefix of
-.I oldpath
-or
-.IR newpath ,
-or
-.I oldpath
-is a directory and does not allow write permission (needed to update
-the
-.I ..
-entry).
-(See also
-.BR path_resolution (7).)
-.TP
-.B EBUSY
-The rename fails because
-.IR oldpath " or " newpath
-is a directory that is in use by some process (perhaps as
-current working directory, or as root directory, or because
-it was open for reading) or is in use by the system
-(for example as mount point), while the system considers
-this an error.
-(Note that there is no requirement to return
-.B EBUSY
-in such
-cases\(emthere is nothing wrong with doing the rename anyway\(embut
-it is allowed to return
-.B EBUSY
-if the system cannot otherwise
-handle such situations.)
-.TP
-.B EDQUOT
-The user's quota of disk blocks on the filesystem has been exhausted.
-.TP
-.B EFAULT
-.IR oldpath " or " newpath " points outside your accessible address space."
-.TP
-.B EINVAL
-The new pathname contained a path prefix of the old, or, more generally,
-an attempt was made to make a directory a subdirectory of itself.
-.TP
-.B EISDIR
-.I newpath
-is an existing directory, but
-.I oldpath
-is not a directory.
-.TP
-.B ELOOP
-Too many symbolic links were encountered in resolving
-.IR oldpath " or " newpath .
-.TP
-.B EMLINK
-.I oldpath
-already has the maximum number of links to it, or
-it was a directory and the directory containing
-.I newpath
-has the maximum number of links.
-.TP
-.B ENAMETOOLONG
-.IR oldpath " or " newpath " was too long."
-.TP
-.B ENOENT
-The link named by
-.I oldpath
-does not exist;
-or, a directory component in
-.I newpath
-does not exist;
-or,
-.I oldpath
-or
-.I newpath
-is an empty string.
-.TP
-.B ENOMEM
-Insufficient kernel memory was available.
-.TP
-.B ENOSPC
-The device containing the file has no room for the new directory
-entry.
-.TP
-.B ENOTDIR
-A component used as a directory in
-.IR oldpath " or " newpath
-is not, in fact, a directory.
-Or,
-.I oldpath
-is a directory, and
-.I newpath
-exists but is not a directory.
-.TP
-.BR ENOTEMPTY " or " EEXIST
-.I newpath
-is a nonempty directory, that is, contains entries other than "." and "..".
-.TP
-.BR EPERM " or " EACCES
-The directory containing
-.I oldpath
-has the sticky bit
-.RB ( S_ISVTX )
-set and the process's effective user ID is neither
-the user ID of the file to be deleted nor that of the directory
-containing it, and the process is not privileged
-(Linux: does not have the
-.B CAP_FOWNER
-capability);
-or
-.I newpath
-is an existing file and the directory containing it has the sticky bit set
-and the process's effective user ID is neither the user ID of the file
-to be replaced nor that of the directory containing it,
-and the process is not privileged
-(Linux: does not have the
-.B CAP_FOWNER
-capability);
-or the filesystem containing
-.I pathname
-does not support renaming of the type requested.
-.TP
-.B EROFS
-The file is on a read-only filesystem.
-.TP
-.B EXDEV
-.IR oldpath " and " newpath
-are not on the same mounted filesystem.
-(Linux permits a filesystem to be mounted at multiple points, but
-.BR rename ()
-does not work across different mount points,
-even if the same filesystem is mounted on both.)
-.PP
-The following additional errors can occur for
-.BR renameat ()
-and
-.BR renameat2 ():
-.TP
-.B EBADF
-.I olddirfd
-or
-.I newdirfd
-is not a valid file descriptor.
-.TP
-.B ENOTDIR
-.I oldpath
-is relative and
-.I olddirfd
-is a file descriptor referring to a file other than a directory;
-or similar for
-.I newpath
-and
-.I newdirfd
-.PP
-The following additional errors can occur for
-.BR renameat2 ():
-.TP
-.B EEXIST
-.I flags
-contains
-.B RENAME_NOREPLACE
-and
-.I newpath
-already exists.
-.TP
-.B EINVAL
-An invalid flag was specified in
-.IR flags ,
-or both
-.B RENAME_NOREPLACE
-and
-.B RENAME_EXCHANGE
-were specified.
-.TP
-.B EINVAL
-The filesystem does not support one of the flags in
-.IR flags .
-.TP
-.B ENOENT
-.I flags
-contains
-.B RENAME_EXCHANGE
-and
-.IR newpath
-does not exist.
-.SH VERSIONS
-.BR renameat ()
-was added to Linux in kernel 2.6.16;
-library support was added to glibc in version 2.4.
-
-.BR renameat2 ()
-was added to Linux in kernel 3.15.
-.\" FIXME . glibc support is pending.
-.SH CONFORMING TO
-.BR rename ():
-4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.
-
-.BR renameat ():
-POSIX.1-2008.
-
-.BR renameat2 ()
-is Linux-specific.
-.SH NOTES
-.SS Glibc notes
-On older kernels where
-.BR renameat ()
-is unavailable, the glibc wrapper function falls back to the use of
-.BR rename ().
-When
-.I oldpath
-and
-.I newpath
-are relative pathnames,
-glibc constructs pathnames based on the symbolic links in
-.IR /proc/self/fd
-that correspond to the
-.I olddirfd
-and
-.IR newdirfd
-arguments.
-.SH BUGS
-On NFS filesystems, you can not assume that if the operation
-failed, the file was not renamed.
-If the server does the rename operation
-and then crashes, the retransmitted RPC which will be processed when the
-server is up again causes a failure.
-The application is expected to
-deal with this.
-See
-.BR link (2)
-for a similar problem.
-.SH SEE ALSO
-.BR mv (1),
-.BR chmod (2),
-.BR link (2),
-.BR symlink (2),
-.BR unlink (2),
-.BR path_resolution (7),
-.BR symlink (7)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
