1VFS_RENAME(9)                    The Linux VFS                   VFS_RENAME(9)
2
3
4

NAME

6       vfs_rename - rename a filesystem object
7

SYNOPSIS

9       int vfs_rename(struct inode * old_dir, struct dentry * old_dentry,
10                      struct inode * new_dir, struct dentry * new_dentry,
11                      struct inode ** delegated_inode, unsigned int flags);
12

ARGUMENTS

14       old_dir
15           parent of source
16
17       old_dentry
18           source
19
20       new_dir
21           parent of destination
22
23       new_dentry
24           destination
25
26       delegated_inode
27           returns an inode needing a delegation break
28
29       flags
30           rename flags
31

DESCRIPTION

33       The caller must hold multiple mutexes--see lock_rename).
34
35       If vfs_rename discovers a delegation in need of breaking at either the
36       source or destination, it will return -EWOULDBLOCK and return a
37       reference to the inode in delegated_inode. The caller should then break
38       the delegation and retry. Because breaking a delegation may take a long
39       time, the caller should drop all locks before doing so.
40
41       Alternatively, a caller may pass NULL for delegated_inode. This may be
42       appropriate for callers that expect the underlying filesystem not to be
43       NFS exported.
44
45       The worst of all namespace operations - renaming directory.
46       “Perverted” doesn't even start to describe it. Somebody in UCB had a
47       heck of a trip...
48

PROBLEMS

50       a) we can get into loop creation. b) race potential - two innocent
51       renames can create a loop together. That's where 4.4 screws up. Current
52       fix: serialization on sb->s_vfs_rename_mutex. We might be more
53       accurate, but that's another story. c) we have to lock _four_ objects -
54       parents and victim (if it exists), and source (if it is not a
55       directory). And that - after we got ->i_mutex on parents (until then we
56       don't know whether the target exists). Solution: try to be smart with
57       locking order for inodes. We rely on the fact that tree topology may
58       change only under ->s_vfs_rename_mutex _and_ that parent of the object
59       we move will be locked. Thus we can rank directories by the tree
60       (ancestors first) and rank all non-directories after them. That works
61       since everybody except rename does “lock parent, lookup, lock child”
62       and rename is under ->s_vfs_rename_mutex. HOWEVER, it relies on the
63       assumption that any object with ->lookup has no more than 1 dentry. If
64       “hybrid” objects will ever appear, we'd better make sure that there's
65       no link(2) for them. d) conversion from fhandle to dentry may come in
66       the wrong moment - when we are removing the target. Solution: we will
67       have to grab ->i_mutex in the fhandle_to_dentry code. [FIXME - current
68       nfsfh.c relies on ->i_mutex on parents, which works but leads to some
69       truly excessive locking].
70

72Kernel Hackers Manual 3.10         June 2019                     VFS_RENAME(9)
Impressum