From 9cab982f34e59d932773a3c5fae8dab6a6d7da7f Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 21 Feb 2014 10:57:30 +0100 Subject: [PATCH] rename.2: Merge text of renameat(2) Signed-off-by: Michael Kerrisk --- man2/rename.2 | 109 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 105 insertions(+), 4 deletions(-) diff --git a/man2/rename.2 b/man2/rename.2 index 43310f0f6..bafa89c48 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -1,6 +1,7 @@ .\" This manpage is Copyright (C) 1992 Drew Eckhardt; .\" and Copyright (C) 1993 Michael Haardt; -.\" and Copyright (C) 1993,1995 Ian Jackson. +.\" 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 @@ -29,13 +30,40 @@ .\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt .\" 2007-03-25, mtk, added various text to DESCRIPTION. .\" -.TH RENAME 2 2013-01-27 "Linux" "Linux Programmer's Manual" +.TH RENAME 2 2014-02-21 "Linux" "Linux Programmer's Manual" .SH NAME -rename \- change the name or location of a file +rename, renameat \- 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 ); +.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 +.RE +.ad +.PD .SH DESCRIPTION .BR rename () renames a file, moving it between directories if required. @@ -88,6 +116,53 @@ If 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 (2), +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 (2) +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 (2)). + +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 (). .SH RETURN VALUE On success, zero is returned. On error, \-1 is returned, and @@ -229,8 +304,35 @@ are not on the same mounted filesystem. .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 (): +.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 +.SH VERSIONS +.BR renameat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. .SH CONFORMING TO +.BR rename (): 4.3BSD, C89, C99, POSIX.1-2001. + +.BR renameat (): +POSIX.1-2008. .SH BUGS On NFS filesystems, you can not assume that if the operation failed, the file was not renamed. @@ -246,7 +348,6 @@ for a similar problem. .BR mv (1), .BR chmod (2), .BR link (2), -.BR renameat (2), .BR symlink (2), .BR unlink (2), .BR path_resolution (7),