[apple/xnu.git] / bsd / man / man2 / rename.2

.\"	$NetBSD: rename.2,v 1.7 1995/02/27 12:36:15 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)rename.2	8.1 (Berkeley) 6/4/93
.\"
.Dd September 18, 2008
.Dt RENAME 2
.Os BSD 4.2
.Sh NAME
.Nm rename ,
.Nm renameat
.Nd change the name of a file
.Sh SYNOPSIS
.Fd #include <stdio.h>
.Ft int
.Fo rename
.Fa "const char *old"
.Fa "const char *new"
.Fc
.Ft int
.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
.Sh DESCRIPTION
The
.Fn rename
system call causes the link named
.Fa old
to be renamed as
.Fa new .
If 
.Fa new
exists, it is first removed.
Both 
.Fa old
and
.Fa new
must be of the same type
(that is, both must be either directories or non-directories)
and must reside on the same file system.
.Pp
The
.Fn rename
system call guarantees that an instance of
.Fa new
will always exist,
even if the system should crash in the middle of the operation.
.Pp
If the final component of
.Fa old
is a symbolic link,
the symbolic link is renamed,
not the file or directory to which it points.
.Pp
The
.Fn renameat
system call is equivalent to
.Fn rename
except in the case where either
.Fa from
or
.Fa to
specifies a relative path.
If
.Fa from
is a relative path, the file to be renamed is located
relative to the directory associated with the file descriptor
.Fa fromfd
instead of the current working directory.
If the
.Fa to
is a relative path, the same happens only relative to the directory associated
with
.Fa tofd .
If the
.Fn renameat
is passed the special value
.Dv AT_FDCWD
in the
.Fa fromfd
or
.Fa tofd
parameter, the current working directory is used in the determination
of the file for the respective path parameter.
.Sh CAVEATS
The system can deadlock if a loop is present in the file system graph.
This loop takes the form of an entry in directory
.Ql Pa a ,
say
.Ql Pa a/foo ,
being a hard link to directory
.Ql Pa b ,
and an entry in
directory
.Ql Pa b ,
say
.Ql Pa b/bar ,
being a hard link
to directory
.Ql Pa a .
When such a loop exists and two separate processes attempt to
perform
.Ql rename a/foo b/bar
and
.Ql rename b/bar a/foo ,
respectively, 
the system may deadlock attempting to lock
both directories for modification.
.Pp
Whether or not hard links to directories are supported is specific to
the underlying filesystem implementation.
.Pp
It is recommended that any hard links to directories in an underlying
filesystem should be replaced by symbolic links by the system administrator
to avoid the possibility of deadlocks.
.Pp
Moving or renaming a file or directory into a directory with inheritable ACLs does not result in ACLs being set on the file or directory. Use
.Xr acl 3
in conjunction with
.Fn rename
to set ACLs on the file or directory.
.Sh RETURN VALUES
A 0 value is returned if the operation succeeds, otherwise
.Fn rename
returns -1 and the global variable 
.Va errno
indicates the reason for the failure.
.Sh ERRORS
The
.Fn rename
system call will fail and neither of the argument files will be
affected if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EACCES
A component of either path prefix denies search permission.
.\" ===========
.It Bq Er EACCES
The requested operation requires writing in a directory
(e.g.,
.Fa new ,
new/.., or old/..) whose modes disallow this.
.\" ===========
.It Bq Er EDQUOT
The directory in which the entry for the new name
is being placed cannot be extended because the
user's quota of disk blocks on the file system
containing the directory has been exhausted.
.\" ===========
.It Bq Er EFAULT
.Em Path
points outside the process's allocated address space.
.\" ===========
.It Bq Er EINVAL
.Fa Old
is a parent directory of
.Fa new ,
or an attempt is made to rename
.Ql \&.
or
.Ql \&.. .
.\" ===========
.It Bq Er EIO
An I/O error occurs while making or updating a directory entry.
.\" ===========
.It Bq Er EISDIR
.Fa new
is a directory, but
.Fa old
is not a directory.
.\" ===========
.It Bq Er ELOOP
Too many symbolic links are encountered in translating either pathname.
This is taken to be indicative of a looping symbolic link.
.\" ===========
.It Bq Er ENAMETOOLONG
A component of a pathname exceeds 
.Dv {NAME_MAX}
characters, or an entire path name exceeds
.Dv {PATH_MAX}
characters.
.\" ===========
.It Bq Er ENOENT
A component of the
.Fa old
path does not exist,
or a path prefix of
.Fa new
does not exist.
.\" ===========
.It Bq Er 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.
.\" ===========
.It Bq Er ENOTDIR
A component of either path prefix is not a directory.
.\" ===========
.It Bq Er ENOTDIR
.Fa old
is a directory, but
.Fa new
is not a directory.
.\" ===========
.It Bq Er ENOTEMPTY
.Fa New
is a directory and is not empty.
.\" ===========
.It Bq Er EPERM
The directory containing
.Fa old
is marked sticky,
and neither the containing directory nor
.Fa old
are owned by the effective user ID.
.\" ===========
.It Bq Er EPERM
The
.Fa new
file exists,
the directory containing
.Fa new
is marked sticky,
and neither the containing directory nor
.Fa new
are owned by the effective user ID.
.\" ===========
.It Bq Er EROFS
The requested link requires writing in a directory on a read-only file
system.
.\" ===========
.It Bq Er EXDEV
The link named by
.Fa new
and the file named by
.Fa old
are on different logical devices (file systems).
Note that this error code will not be returned
if the implementation permits cross-device links.
.El
.Pp
In addition to the errors returned by the
.Fn rename ,
the
.Fn renameat
may fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa from
argument does not specify an absolute path and the
.Fa fromfd
argument is neither
.Dv AT_FDCWD
nor a valid file descriptor open for searching, or the
.Fa to
argument does not specify an absolute path and the
.Fa tofd
argument is neither
.Dv AT_FDCWD
nor a valid file descriptor open for searching.
.It Bq Er ENOTDIR
The
.Fa from
argument is not an absolute path and
.Fa fromfd
is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory, or the
.Fa to
argument is not an absolute path and
.Fa tofd
is neither
.Dv AT_FDCWD
nor a file descriptor associated with a directory.
.Sh CONFORMANCE
The restriction on renaming a directory whose permissions disallow writing
is based on the fact that UFS directories contain a ".." entry.
If renaming a directory would move it to another parent directory,
this entry needs to be changed.
.Pp
This restriction has been generalized to disallow renaming
of any write-disabled directory,
even when this would not require a change to the ".." entry.
For consistency, HFS+ directories emulate this behavior.
.Sh SEE ALSO
.Xr open 2 ,
.Xr symlink 7
.Sh STANDARDS
The
.Fn rename
function conforms to 
.St -p1003.1-88 .
The
.Fn renameat
system call is expected to conform to POSIX.1-2008 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: rename.2,v 1.7 1995/02/27 12:36:15 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1983, 1991, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)rename.2 8.1 (Berkeley) 6/4/93
	35	.\"
b0d623f7	36	.Dd September 18, 2008
9bccf70c A	37	.Dt RENAME 2
	38	.Os BSD 4.2
	39	.Sh NAME
fe8ab488 A	40	.Nm rename ,
fe8ab488 A	41	.Nm renameat
9bccf70c A	42	.Nd change the name of a file
	43	.Sh SYNOPSIS
	44	.Fd #include <stdio.h>
	45	.Ft int
2d21ac55 A	46	.Fo rename
	47	.Fa "const char *old"
	48	.Fa "const char *new"
	49	.Fc
fe8ab488 A	50	.Ft int
fe8ab488 A	51	.Fn renameat "int fromfd" "const char from" "int tofd" "const char to"
9bccf70c	52	.Sh DESCRIPTION
2d21ac55 A	53	The
	54	.Fn rename
	55	system call causes the link named
	56	.Fa old
9bccf70c	57	to be renamed as
2d21ac55	58	.Fa new .
9bccf70c	59	If
2d21ac55	60	.Fa new
9bccf70c A	61	exists, it is first removed.
9bccf70c A	62	Both
2d21ac55	63	.Fa old
9bccf70c	64	and
2d21ac55 A	65	.Fa new
	66	must be of the same type
	67	(that is, both must be either directories or non-directories)
	68	and must reside on the same file system.
9bccf70c	69	.Pp
2d21ac55 A	70	The
	71	.Fn rename
	72	system call guarantees that an instance of
	73	.Fa new
	74	will always exist,
	75	even if the system should crash in the middle of the operation.
9bccf70c A	76	.Pp
9bccf70c A	77	If the final component of
2d21ac55	78	.Fa old
9bccf70c A	79	is a symbolic link,
	80	the symbolic link is renamed,
	81	not the file or directory to which it points.
fe8ab488 A	82	.Pp
	83	The
	84	.Fn renameat
	85	system call is equivalent to
	86	.Fn rename
	87	except in the case where either
	88	.Fa from
	89	or
	90	.Fa to
	91	specifies a relative path.
	92	If
	93	.Fa from
	94	is a relative path, the file to be renamed is located
	95	relative to the directory associated with the file descriptor
	96	.Fa fromfd
	97	instead of the current working directory.
	98	If the
	99	.Fa to
	100	is a relative path, the same happens only relative to the directory associated
	101	with
	102	.Fa tofd .
	103	If the
	104	.Fn renameat
	105	is passed the special value
	106	.Dv AT_FDCWD
	107	in the
	108	.Fa fromfd
	109	or
	110	.Fa tofd
	111	parameter, the current working directory is used in the determination
	112	of the file for the respective path parameter.
b0d623f7	113	.Sh CAVEATS
2d21ac55	114	The system can deadlock if a loop is present in the file system graph.
9bccf70c A	115	This loop takes the form of an entry in directory
	116	.Ql Pa a ,
	117	say
	118	.Ql Pa a/foo ,
	119	being a hard link to directory
	120	.Ql Pa b ,
	121	and an entry in
	122	directory
	123	.Ql Pa b ,
	124	say
	125	.Ql Pa b/bar ,
	126	being a hard link
	127	to directory
	128	.Ql Pa a .
	129	When such a loop exists and two separate processes attempt to
	130	perform
	131	.Ql rename a/foo b/bar
	132	and
	133	.Ql rename b/bar a/foo ,
	134	respectively,
	135	the system may deadlock attempting to lock
	136	both directories for modification.
2d21ac55 A	137	.Pp
	138	Whether or not hard links to directories are supported is specific to
	139	the underlying filesystem implementation.
	140	.Pp
	141	It is recommended that any hard links to directories in an underlying
	142	filesystem should be replaced by symbolic links by the system administrator
	143	to avoid the possibility of deadlocks.
b0d623f7 A	144	.Pp
	145	Moving or renaming a file or directory into a directory with inheritable ACLs does not result in ACLs being set on the file or directory. Use
	146	.Xr acl 3
	147	in conjunction with
	148	.Fn rename
	149	to set ACLs on the file or directory.
9bccf70c A	150	.Sh RETURN VALUES
	151	A 0 value is returned if the operation succeeds, otherwise
	152	.Fn rename
	153	returns -1 and the global variable
	154	.Va errno
	155	indicates the reason for the failure.
	156	.Sh ERRORS
2d21ac55 A	157	The
	158	.Fn rename
	159	system call will fail and neither of the argument files will be
9bccf70c A	160	affected if:
9bccf70c A	161	.Bl -tag -width Er
2d21ac55 A	162	.\" ===========
	163	.It Bq Er EACCES
	164	A component of either path prefix denies search permission.
	165	.\" ===========
	166	.It Bq Er EACCES
	167	The requested operation requires writing in a directory
	168	(e.g.,
	169	.Fa new ,
	170	new/.., or old/..) whose modes disallow this.
	171	.\" ===========
	172	.It Bq Er EDQUOT
	173	The directory in which the entry for the new name
	174	is being placed cannot be extended because the
	175	user's quota of disk blocks on the file system
	176	containing the directory has been exhausted.
	177	.\" ===========
	178	.It Bq Er EFAULT
	179	.Em Path
	180	points outside the process's allocated address space.
	181	.\" ===========
	182	.It Bq Er EINVAL
	183	.Fa Old
	184	is a parent directory of
	185	.Fa new ,
	186	or an attempt is made to rename
	187	.Ql \&.
	188	or
	189	.Ql \&.. .
	190	.\" ===========
	191	.It Bq Er EIO
	192	An I/O error occurs while making or updating a directory entry.
	193	.\" ===========
	194	.It Bq Er EISDIR
	195	.Fa new
	196	is a directory, but
	197	.Fa old
	198	is not a directory.
	199	.\" ===========
	200	.It Bq Er ELOOP
	201	Too many symbolic links are encountered in translating either pathname.
	202	This is taken to be indicative of a looping symbolic link.
	203	.\" ===========
9bccf70c	204	.It Bq Er ENAMETOOLONG
2d21ac55	205	A component of a pathname exceeds
9bccf70c	206	.Dv {NAME_MAX}
2d21ac55	207	characters, or an entire path name exceeds
9bccf70c A	208	.Dv {PATH_MAX}
9bccf70c A	209	characters.
2d21ac55	210	.\" ===========
9bccf70c A	211	.It Bq Er ENOENT
9bccf70c A	212	A component of the
2d21ac55	213	.Fa old
9bccf70c A	214	path does not exist,
9bccf70c A	215	or a path prefix of
2d21ac55	216	.Fa new
9bccf70c	217	does not exist.
2d21ac55 A	218	.\" ===========
	219	.It Bq Er ENOSPC
	220	The directory in which the entry for the new name is being placed
	221	cannot be extended because there is no space left on the file
	222	system containing the directory.
	223	.\" ===========
	224	.It Bq Er ENOTDIR
	225	A component of either path prefix is not a directory.
	226	.\" ===========
	227	.It Bq Er ENOTDIR
	228	.Fa old
	229	is a directory, but
	230	.Fa new
	231	is not a directory.
	232	.\" ===========
	233	.It Bq Er ENOTEMPTY
	234	.Fa New
	235	is a directory and is not empty.
	236	.\" ===========
9bccf70c A	237	.It Bq Er EPERM
9bccf70c A	238	The directory containing
2d21ac55	239	.Fa old
9bccf70c A	240	is marked sticky,
9bccf70c A	241	and neither the containing directory nor
2d21ac55	242	.Fa old
9bccf70c	243	are owned by the effective user ID.
2d21ac55	244	.\" ===========
9bccf70c A	245	.It Bq Er EPERM
9bccf70c A	246	The
2d21ac55	247	.Fa new
9bccf70c A	248	file exists,
9bccf70c A	249	the directory containing
2d21ac55	250	.Fa new
9bccf70c A	251	is marked sticky,
9bccf70c A	252	and neither the containing directory nor
2d21ac55	253	.Fa new
9bccf70c	254	are owned by the effective user ID.
2d21ac55	255	.\" ===========
9bccf70c A	256	.It Bq Er EROFS
	257	The requested link requires writing in a directory on a read-only file
	258	system.
2d21ac55 A	259	.\" ===========
	260	.It Bq Er EXDEV
	261	The link named by
	262	.Fa new
	263	and the file named by
	264	.Fa old
	265	are on different logical devices (file systems).
	266	Note that this error code will not be returned
	267	if the implementation permits cross-device links.
9bccf70c	268	.El
fe8ab488 A	269	.Pp
	270	In addition to the errors returned by the
	271	.Fn rename ,
	272	the
	273	.Fn renameat
	274	may fail if:
	275	.Bl -tag -width Er
	276	.It Bq Er EBADF
	277	The
	278	.Fa from
	279	argument does not specify an absolute path and the
	280	.Fa fromfd
	281	argument is neither
	282	.Dv AT_FDCWD
	283	nor a valid file descriptor open for searching, or the
	284	.Fa to
	285	argument does not specify an absolute path and the
	286	.Fa tofd
	287	argument is neither
	288	.Dv AT_FDCWD
	289	nor a valid file descriptor open for searching.
	290	.It Bq Er ENOTDIR
	291	The
	292	.Fa from
	293	argument is not an absolute path and
	294	.Fa fromfd
	295	is neither
	296	.Dv AT_FDCWD
	297	nor a file descriptor associated with a directory, or the
	298	.Fa to
	299	argument is not an absolute path and
	300	.Fa tofd
	301	is neither
	302	.Dv AT_FDCWD
	303	nor a file descriptor associated with a directory.
2d21ac55 A	304	.Sh CONFORMANCE
	305	The restriction on renaming a directory whose permissions disallow writing
	306	is based on the fact that UFS directories contain a ".." entry.
	307	If renaming a directory would move it to another parent directory,
	308	this entry needs to be changed.
	309	.Pp
	310	This restriction has been generalized to disallow renaming
	311	of any write-disabled directory,
	312	even when this would not require a change to the ".." entry.
	313	For consistency, HFS+ directories emulate this behavior.
9bccf70c	314	.Sh SEE ALSO
2d21ac55	315	.Xr open 2 ,
9bccf70c A	316	.Xr symlink 7
	317	.Sh STANDARDS
	318	The
	319	.Fn rename
	320	function conforms to
	321	.St -p1003.1-88 .
fe8ab488 A	322	The
	323	.Fn renameat
	324	system call is expected to conform to POSIX.1-2008 .