X-Git-Url: http://git.osdn.net/view?p=linuxjm%2FLDP_man-pages.git;a=blobdiff_plain;f=original%2Fman2%2Frename.2;fp=original%2Fman2%2Frename.2;h=0000000000000000000000000000000000000000;hp=610bbfd9ac36c395df0fedf1edbced6563367c41;hb=2460a0b8024ceb8570acdbc9208713d79458efcb;hpb=83f9e5d087c3464d5131604d3c9893479e6228eb diff --git a/original/man2/rename.2 b/original/man2/rename.2 deleted file mode 100644 index 610bbfd9..00000000 --- a/original/man2/rename.2 +++ /dev/null @@ -1,459 +0,0 @@ -.\" 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 -.\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer -.\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt -.\" 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 -.sp -.BI "int rename(const char *" oldpath ", const char *" newpath ); -.sp -.BR "#include " "/* Definition of AT_* constants */" -.B #include -.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/.