xref: /freebsd/lib/libsys/rename.2 (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd August 25, 2024
29.Dt RENAME 2
30.Os
31.Sh NAME
32.Nm rename
33.Nd change the name of a file
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
37.In stdio.h
38.Ft int
39.Fn rename "const char *from" "const char *to"
40.Ft int
41.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to"
42.Sh DESCRIPTION
43The
44.Fn rename
45system call
46causes the link named
47.Fa from
48to be renamed as
49.Fa to .
50If
51.Fa to
52exists, it is first removed.
53Both
54.Fa from
55and
56.Fa to
57must be of the same type (that is, both directories or both
58non-directories), and must reside on the same file system.
59.Pp
60The
61.Fn rename
62system call
63guarantees that if
64.Fa to
65already exists, an instance of
66.Fa to
67will always exist, even if the system should crash in
68the middle of the operation.
69.Pp
70If the final component of
71.Fa from
72is a symbolic link,
73the symbolic link is renamed,
74not the file or directory to which it points.
75.Pp
76If
77.Fa from
78and
79.Fa to
80resolve to the same directory entry, or to different directory
81entries for the same existing file,
82.Fn rename
83returns success without taking any further action.
84.Pp
85The
86.Fn renameat
87system call is equivalent to
88.Fn rename
89except in the case where either
90.Fa from
91or
92.Fa to
93specifies a relative path.
94If
95.Fa from
96is a relative path, the file to be renamed is located
97relative to the directory associated with the file descriptor
98.Fa fromfd
99instead of the current working directory.
100If the
101.Fa to
102is a relative path, the same happens only relative to the directory associated
103with
104.Fa tofd .
105If the
106.Fn renameat
107is passed the special value
108.Dv AT_FDCWD
109in the
110.Fa fromfd
111or
112.Fa tofd
113parameter, the current working directory is used in the determination
114of the file for the respective path parameter.
115.\".Sh CAVEAT
116.\"The system can deadlock if a loop in the file system graph is present.
117.\"This loop takes the form of an entry in directory
118.\".Pa a ,
119.\"say
120.\".Pa a/foo ,
121.\"being a hard link to directory
122.\".Pa b ,
123.\"and an entry in
124.\"directory
125.\".Pa b ,
126.\"say
127.\".Pa b/bar ,
128.\"being a hard link
129.\"to directory
130.\".Pa a .
131.\"When such a loop exists and two separate processes attempt to
132.\"perform
133.\".Ql rename a/foo b/bar
134.\"and
135.\".Ql rename b/bar a/foo ,
136.\"respectively,
137.\"the system may deadlock attempting to lock
138.\"both directories for modification.
139.\"Hard links to directories should be
140.\"replaced by symbolic links by the system administrator.
141.Sh RETURN VALUES
142.Rv -std rename
143.Sh ERRORS
144The
145.Fn rename
146system call
147will fail and neither of the argument files will be
148affected if:
149.Bl -tag -width Er
150.It Bq Er ENAMETOOLONG
151A component of either pathname exceeded 255 characters,
152or the entire length of either path name exceeded 1023 characters.
153.It Bq Er ENOENT
154A component of the
155.Fa from
156path does not exist,
157or a path prefix of
158.Fa to
159does not exist.
160.It Bq Er EACCES
161A component of either path prefix denies search permission.
162.It Bq Er EACCES
163The requested link requires writing in a directory with a mode
164that denies write permission.
165.It Bq Er EACCES
166The directory pointed at by the
167.Fa from
168argument denies write permission, and the operation would move
169it to another parent directory.
170.It Bq Er EPERM
171The file pointed at by the
172.Fa from
173argument has its immutable, undeletable or append-only flag set, see the
174.Xr chflags 2
175manual page for more information.
176.It Bq Er EPERM
177The parent directory of the file pointed at by the
178.Fa from
179argument has its immutable or append-only flag set.
180.It Bq Er EPERM
181The parent directory of the file pointed at by the
182.Fa to
183argument has its immutable flag set.
184.It Bq Er EPERM
185The directory containing
186.Fa from
187is marked sticky,
188and neither the containing directory nor
189.Fa from
190are owned by the effective user ID.
191.It Bq Er EPERM
192The file pointed at by the
193.Fa to
194argument
195exists,
196the directory containing
197.Fa to
198is marked sticky,
199and neither the containing directory nor
200.Fa to
201are owned by the effective user ID.
202.It Bq Er ELOOP
203Too many symbolic links were encountered in translating either pathname.
204.It Bq Er ENOTDIR
205A component of either path prefix is not a directory.
206.It Bq Er ENOTDIR
207The
208.Fa from
209argument
210is a directory, but
211.Fa to
212is not a directory.
213.It Bq Er EISDIR
214The
215.Fa to
216argument
217is a directory, but
218.Fa from
219is not a directory.
220.It Bq Er EXDEV
221The link named by
222.Fa to
223and the file named by
224.Fa from
225are on different logical devices (file systems).
226Note that this error
227code will not be returned if the implementation permits cross-device
228links.
229.It Bq Er ENOSPC
230The directory in which the entry for the new name is being placed
231cannot be extended because there is no space left on the file
232system containing the directory.
233.It Bq Er EDQUOT
234The directory in which the entry for the new name
235is being placed cannot be extended because the
236user's quota of disk blocks on the file system
237containing the directory has been exhausted.
238.It Bq Er EIO
239An I/O error occurred while making or updating a directory entry.
240.It Bq Er EINTEGRITY
241Corrupted data was detected while reading from the file system.
242.It Bq Er EROFS
243The requested link requires writing in a directory on a read-only file
244system.
245.It Bq Er EFAULT
246Path
247points outside the process's allocated address space.
248.It Bq Er EINVAL
249The
250.Fa from
251argument
252is a parent directory of
253.Fa to ,
254or an attempt is made to rename
255.Ql .\&
256or
257.Ql \&.. .
258.It Bq Er EINVAL
259The last component of the
260.Fa to
261path is invalid on the target file system.
262.It Bq Er ENOTEMPTY
263The
264.Fa to
265argument
266is a directory and is not empty.
267.It Bq Er ECAPMODE
268.Fn rename
269was called and the process is in capability mode.
270.El
271.Pp
272In addition to the errors returned by the
273.Fn rename ,
274the
275.Fn renameat
276may fail if:
277.Bl -tag -width Er
278.It Bq Er EBADF
279The
280.Fa from
281argument does not specify an absolute path and the
282.Fa fromfd
283argument is neither
284.Dv AT_FDCWD
285nor a valid file descriptor open for searching, or the
286.Fa to
287argument does not specify an absolute path and the
288.Fa tofd
289argument is neither
290.Dv AT_FDCWD
291nor a valid file descriptor open for searching.
292.It Bq Er ENOTDIR
293The
294.Fa from
295argument is not an absolute path and
296.Fa fromfd
297is neither
298.Dv AT_FDCWD
299nor a file descriptor associated with a directory, or the
300.Fa to
301argument is not an absolute path and
302.Fa tofd
303is neither
304.Dv AT_FDCWD
305nor a file descriptor associated with a directory.
306.It Bq Er ECAPMODE
307.Dv AT_FDCWD
308is specified and the process is in capability mode.
309.It Bq Er ENOTCAPABLE
310.Fa path
311is an absolute path or contained a ".." component leading to a directory
312outside of the directory hierarchy specified by
313.Fa fromfd
314or
315.Fa tofd .
316.It Bq Er ENOTCAPABLE
317The
318.Fa fromfd
319file descriptor lacks the
320.Dv CAP_RENAMEAT_SOURCE
321right, or the
322.Fa tofd
323file descriptor lacks the
324.Dv CAP_RENAMEAT_TARGET
325right.
326.El
327.Sh SEE ALSO
328.Xr chflags 2 ,
329.Xr open 2 ,
330.Xr symlink 7
331.Sh STANDARDS
332The
333.Fn rename
334system call is expected to conform to
335.St -p1003.1-96 .
336The
337.Fn renameat
338system call follows The Open Group Extended API Set 2 specification.
339.Sh HISTORY
340The
341.Fn renameat
342system call appeared in
343.Fx 8.0 .
344