Commit | Line | Data |
---|---|---|
3f6f0ccf KB |
1 | .\" Copyright (c) 1983, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
786fe04f | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
88b3ccf2 | 5 | .\" |
3f6f0ccf | 6 | .\" @(#)rename.2 8.1 (Berkeley) %G% |
786fe04f | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt RENAME 2 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm rename | |
13 | .Nd change the name of a file | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <stdio.h> | |
16 | .Ft int | |
17 | .Fn rename "const char *from" "const char *to" | |
18 | .Sh DESCRIPTION | |
19 | .Fn Rename | |
786fe04f | 20 | causes the link named |
931b8415 | 21 | .Fa from |
786fe04f | 22 | to be renamed as |
931b8415 | 23 | .Fa to . |
786fe04f | 24 | If |
931b8415 CL |
25 | .Fa to |
26 | exists, it is first removed. | |
786fe04f | 27 | Both |
931b8415 | 28 | .Fa from |
786fe04f | 29 | and |
931b8415 | 30 | .Fa to |
786fe04f KM |
31 | must be of the same type (that is, both directories or both |
32 | non-directories), and must reside on the same file system. | |
931b8415 CL |
33 | .Pp |
34 | .Fn Rename | |
786fe04f | 35 | guarantees that an instance of |
931b8415 | 36 | .Fa to |
786fe04f KM |
37 | will always exist, even if the system should crash in |
38 | the middle of the operation. | |
931b8415 | 39 | .Pp |
dbe80be1 | 40 | If the final component of |
931b8415 | 41 | .Fa from |
dbe80be1 KM |
42 | is a symbolic link, |
43 | the symbolic link is renamed, | |
44 | not the file or directory to which it points. | |
931b8415 | 45 | .Sh CAVEAT |
786fe04f | 46 | The system can deadlock if a loop in the file system graph is present. |
931b8415 CL |
47 | This loop takes the form of an entry in directory |
48 | .Ql Pa a , | |
49 | say | |
50 | .Ql Pa a/foo , | |
51 | being a hard link to directory | |
52 | .Ql Pa b , | |
53 | and an entry in | |
54 | directory | |
55 | .Ql Pa b , | |
56 | say | |
57 | .Ql Pa b/bar , | |
58 | being a hard link | |
59 | to directory | |
60 | .Ql Pa a . | |
786fe04f | 61 | When such a loop exists and two separate processes attempt to |
931b8415 CL |
62 | perform |
63 | .Ql rename a/foo b/bar | |
64 | and | |
65 | .Ql rename b/bar a/foo , | |
786fe04f KM |
66 | respectively, |
67 | the system may deadlock attempting to lock | |
68 | both directories for modification. | |
69 | Hard links to directories should be | |
70 | replaced by symbolic links by the system administrator. | |
931b8415 | 71 | .Sh RETURN VALUES |
786fe04f | 72 | A 0 value is returned if the operation succeeds, otherwise |
931b8415 CL |
73 | .Fn rename |
74 | returns -1 and the global variable | |
75 | .Va errno | |
786fe04f | 76 | indicates the reason for the failure. |
931b8415 CL |
77 | .Sh ERRORS |
78 | .Fn Rename | |
786fe04f | 79 | will fail and neither of the argument files will be |
931b8415 CL |
80 | affected if: |
81 | .Bl -tag -width ENAMETOOLONG | |
82 | .It Bq Er EINVAL | |
b5984ffe | 83 | Either pathname contains a character with the high-order bit set. |
931b8415 | 84 | .It Bq Er ENAMETOOLONG |
b5984ffe KM |
85 | A component of either pathname exceeded 255 characters, |
86 | or the entire length of either path name exceeded 1023 characters. | |
931b8415 CL |
87 | .It Bq Er ENOENT |
88 | A component of the | |
89 | .Fa from | |
90 | path does not exist, | |
91 | or a path prefix of | |
92 | .Fa to | |
93 | does not exist. | |
94 | .It Bq Er EACCES | |
786fe04f | 95 | A component of either path prefix denies search permission. |
931b8415 | 96 | .It Bq Er EACCES |
b5984ffe KM |
97 | The requested link requires writing in a directory with a mode |
98 | that denies write permission. | |
931b8415 CL |
99 | .It Bq Er EPERM |
100 | The directory containing | |
101 | .Fa from | |
102 | is marked sticky, | |
103 | and neither the containing directory nor | |
104 | .Fa from | |
fd690c8b | 105 | are owned by the effective user ID. |
931b8415 CL |
106 | .It Bq Er EPERM |
107 | The | |
108 | .Fa to | |
109 | file exists, | |
110 | the directory containing | |
111 | .Fa to | |
112 | is marked sticky, | |
113 | and neither the containing directory nor | |
114 | .Fa to | |
fd690c8b | 115 | are owned by the effective user ID. |
931b8415 | 116 | .It Bq Er ELOOP |
b5984ffe | 117 | Too many symbolic links were encountered in translating either pathname. |
931b8415 | 118 | .It Bq Er ENOTDIR |
b5984ffe | 119 | A component of either path prefix is not a directory. |
931b8415 CL |
120 | .It Bq Er ENOTDIR |
121 | .Fa from | |
122 | is a directory, but | |
123 | .Fa to | |
124 | is not a directory. | |
125 | .It Bq Er EISDIR | |
126 | .Fa to | |
127 | is a directory, but | |
128 | .Fa from | |
129 | is not a directory. | |
130 | .It Bq Er EXDEV | |
131 | The link named by | |
132 | .Fa to | |
133 | and the file named by | |
134 | .Fa from | |
786fe04f KM |
135 | are on different logical devices (file systems). Note that this error |
136 | code will not be returned if the implementation permits cross-device | |
137 | links. | |
931b8415 | 138 | .It Bq Er ENOSPC |
fd690c8b KM |
139 | The directory in which the entry for the new name is being placed |
140 | cannot be extended because there is no space left on the file | |
141 | system containing the directory. | |
931b8415 | 142 | .It Bq Er EDQUOT |
fd690c8b KM |
143 | The directory in which the entry for the new name |
144 | is being placed cannot be extended because the | |
145 | user's quota of disk blocks on the file system | |
146 | containing the directory has been exhausted. | |
931b8415 | 147 | .It Bq Er EIO |
b5984ffe | 148 | An I/O error occurred while making or updating a directory entry. |
931b8415 | 149 | .It Bq Er EROFS |
786fe04f KM |
150 | The requested link requires writing in a directory on a read-only file |
151 | system. | |
931b8415 CL |
152 | .It Bq Er EFAULT |
153 | .Em Path | |
786fe04f | 154 | points outside the process's allocated address space. |
931b8415 CL |
155 | .It Bq Er EINVAL |
156 | .Fa From | |
786fe04f | 157 | is a parent directory of |
931b8415 CL |
158 | .Fa to , |
159 | or an attempt is made to rename | |
160 | .Ql \&. | |
161 | or | |
162 | .Ql \&.. . | |
163 | .It Bq Er ENOTEMPTY | |
164 | .Fa To | |
b5984ffe | 165 | is a directory and is not empty. |
931b8415 CL |
166 | .El |
167 | .Sh SEE ALSO | |
168 | .Xr open 2 | |
a4f7c557 | 169 | .Xr symlink 7 |
931b8415 CL |
170 | .Sh STANDARDS |
171 | .Fn Rename | |
172 | conforms to IEEE Std 1003.1-1988 | |
173 | .Pq Dq Tn POSIX . |