xref: /dflybsd-src/lib/libc/sys/rename.2 (revision a9656fbcd49c376aba5e04370d8b0f1fa96e063c)
1.\" Copyright (c) 1983, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)rename.2	8.1 (Berkeley) 6/4/93
33.\" $FreeBSD: src/lib/libc/sys/rename.2,v 1.8.2.7 2001/12/14 18:34:01 ru Exp $
34.\"
35.Dd July 31, 2010
36.Dt RENAME 2
37.Os
38.Sh NAME
39.Nm rename
40.Nd change the name of a file
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In stdio.h
45.Ft int
46.Fn rename "const char *from" "const char *to"
47.Ft int
48.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
49.Sh DESCRIPTION
50.Fn Rename
51causes the link named
52.Fa from
53to be renamed as
54.Fa to .
55If
56.Fa to
57exists, it is first removed.
58Both
59.Fa from
60and
61.Fa to
62must be of the same type (that is, both directories or both
63non-directories), and must reside on the same file system.
64.Pp
65.Fn Rename
66guarantees that if
67.Fa to
68already exists, an instance of
69.Fa to
70will always exist, even if the system should crash in
71the middle of the operation.
72.Pp
73If the final component of
74.Fa from
75is a symbolic link,
76the symbolic link is renamed,
77not the file or directory to which it points.
78.Pp
79The
80.Fn renameat
81system call is equivalent to
82.Fn rename
83except in the case where either
84.Fa from
85or
86.Fa to
87specifies a relative path.
88If
89.Fa from
90is a relative path, the file to be renamed is located
91relative to the directory associated with the file descriptor
92.Fa fromfd
93instead of the current working directory.
94If the
95.Fa to
96is a relative path, the same happens only relative to the directory associated
97with
98.Fa tofd .
99If the
100.Fn renameat
101is passed the special value
102.Dv AT_FDCWD
103in the
104.Fa fromfd
105or
106.Fa tofd
107parameter, the current working directory is used in the determination
108of the file for the respective path parameter.
109.\".Sh CAVEAT
110.\"The system can deadlock if a loop in the file system graph is present.
111.\"This loop takes the form of an entry in directory
112.\".Ql Pa a ,
113.\"say
114.\".Ql Pa a/foo ,
115.\"being a hard link to directory
116.\".Ql Pa b ,
117.\"and an entry in
118.\"directory
119.\".Ql Pa b ,
120.\"say
121.\".Ql Pa b/bar ,
122.\"being a hard link
123.\"to directory
124.\".Ql Pa a .
125.\"When such a loop exists and two separate processes attempt to
126.\"perform
127.\".Ql rename a/foo b/bar
128.\"and
129.\".Ql rename b/bar a/foo ,
130.\"respectively,
131.\"the system may deadlock attempting to lock
132.\"both directories for modification.
133.\"Hard links to directories should be
134.\"replaced by symbolic links by the system administrator.
135.Sh RETURN VALUES
136.Rv -std rename
137.Sh ERRORS
138.Fn Rename
139will fail and neither of the argument files will be
140affected if:
141.Bl -tag -width Er
142.It Bq Er ENAMETOOLONG
143A component of either pathname exceeded 255 characters,
144or the entire length of either path name exceeded 1023 characters.
145.It Bq Er ENOENT
146A component of the
147.Fa from
148path does not exist,
149or a path prefix of
150.Fa to
151does not exist.
152.It Bq Er EACCES
153A component of either path prefix denies search permission.
154.It Bq Er EACCES
155The requested link requires writing in a directory with a mode
156that denies write permission.
157.It Bq Er EPERM
158The directory containing
159.Fa from
160is marked sticky,
161and neither the containing directory nor
162.Fa from
163are owned by the effective user ID.
164.It Bq Er EPERM
165The
166.Fa to
167file exists,
168the directory containing
169.Fa to
170is marked sticky,
171and neither the containing directory nor
172.Fa to
173are owned by the effective user ID.
174.It Bq Er ELOOP
175Too many symbolic links were encountered in translating either pathname.
176.It Bq Er ENOTDIR
177A component of either path prefix is not a directory.
178.It Bq Er ENOTDIR
179.Fa from
180is a directory, but
181.Fa to
182is not a directory.
183.It Bq Er EISDIR
184.Fa to
185is a directory, but
186.Fa from
187is not a directory.
188.It Bq Er EXDEV
189The link named by
190.Fa to
191and the file named by
192.Fa from
193are on different logical devices (file systems).  Note that this error
194code will not be returned if the implementation permits cross-device
195links.
196.It Bq Er ENOSPC
197The directory in which the entry for the new name is being placed
198cannot be extended because there is no space left on the file
199system containing the directory.
200.It Bq Er EDQUOT
201The directory in which the entry for the new name
202is being placed cannot be extended because the
203user's quota of disk blocks on the file system
204containing the directory has been exhausted.
205.It Bq Er EIO
206An I/O error occurred while making or updating a directory entry.
207.It Bq Er EROFS
208The requested link requires writing in a directory on a read-only file
209system.
210.It Bq Er EFAULT
211.Em Path
212points outside the process's allocated address space.
213.It Bq Er EINVAL
214.Fa From
215is a parent directory of
216.Fa to ,
217or an attempt is made to rename
218.Ql .\&
219or
220.Ql \&.. .
221.It Bq Er ENOTEMPTY
222.Fa To
223is a directory and is not empty.
224.El
225.Pp
226In addition to the errors returned by the
227.Fn rename ,
228the
229.Fn renameat
230may fail if:
231.Bl -tag -width Er
232.It Bq Er EBADF
233The
234.Fa from
235argument does not specify an absolute path and the
236.Fa fromfd
237argument is neither
238.Dv AT_FDCWD
239nor a valid file descriptor open for searching, or the
240.Fa to
241argument does not specify an absolute path and the
242.Fa tofd
243argument is neither
244.Dv AT_FDCWD
245nor a valid file descriptor open for searching.
246.It Bq Er ENOTDIR
247The
248.Fa from
249argument is not an absolute path and
250.Fa fromfd
251is neither
252.Dv AT_FDCWD
253nor a file descriptor associated with a directory, or the
254.Fa to
255argument is not an absolute path and
256.Fa tofd
257is neither
258.Dv AT_FDCWD
259nor a file descriptor associated with a directory.
260.El
261.Sh SEE ALSO
262.Xr open 2 ,
263.Xr symlink 7
264.Sh STANDARDS
265The
266.Fn rename
267system call is expected to conform to
268.St -p1003.1-96 .
269The
270.Fn renameat
271system call follows The Open Group Extended API Set 2 specification.
272.Sh HISTORY
273The
274.Fn renameat
275system call appeared in
276.Dx 2.7 .
277