Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_getparents.2

raw
1 .\" Copyright (c) 2019-2024 Oracle. All rights reserved.
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\" %%%LICENSE_END
6 .TH IOCTL-XFS-GETPARENTS 2 2024-04-09 "XFS"
7 .SH NAME
8 ioctl_xfs_getparents \- query XFS directory parent information
9 .SH SYNOPSIS
10 .br
11 .B #include <xfs/xfs_fs.h>
12 .PP
13 .BI "int ioctl(int " fd ", XFS_IOC_GETPARENTS, struct xfs_getparents *" arg );
14 .PP
15 .BI "int ioctl(int " fd ", XFS_IOC_GETPARENTS_BY_HANDLE, struct xfs_getparents_by_handle *" arg );
16 .SH DESCRIPTION
17 This command is used to retrieve the directory parent pointers of either the
18 currently opened file or a file handle.
19 Parent pointers point upwards in the directory tree from a child file towards a
20 parent directories.
21 Each entry in a parent directory must have a corresponding parent pointer in
22 the child.
23
24 Calling programs should allocate a large memory buffer and initialize a header
25 of the following form:
26 .PP
27 .in +4n
28 .nf
29 struct xfs_getparents {
30 struct xfs_attrlist_cursor gp_cursor;
31 __u16 gp_iflags;
32 __u16 gp_oflags;
33 __u32 gp_bufsize;
34 __u64 __pad;
35 __u64 gp_buffer;
36 };
37
38 struct xfs_getparents_by_handle {
39 struct xfs_handle gph_handle;
40 struct xfs_getparents gph_request;
41 };
42 .fi
43 .in
44
45 .PP
46 The field
47 .I gp_cursor
48 tracks the progress of iterating through the parent pointers.
49 Calling programs must initialize this to zero before the first system call
50 and must not touch it after that.
51
52 .PP
53 The field
54 .I gp_iflags
55 control the behavior of the query operation and provide more information
56 about the outcome of the operation.
57 There are no input flags currently defined; this field must be zero.
58
59 .PP
60 The field
61 .I gp_oflags
62 contains information about the query itself.
63 Possibly output flags are:
64 .RS 0.4i
65 .TP
66 .B XFS_GETPARENTS_OFLAG_ROOT
67 The file queried was the root directory.
68 .TP
69 .B XFS_GETPARENTS_OFLAG_DONE
70 There are no more parent pointers to query.
71 .RE
72
73 .PP
74 The field
75 .I __pad
76 must be zero.
77
78 .PP
79 The field
80 .I gp_bufsize
81 should be set to the size of the buffer, in bytes.
82
83 .PP
84 The field
85 .I gp_buffer
86 should point to an output buffer for the parent pointer records.
87
88 Parent pointer records are returned in the following form:
89 .PP
90 .in +4n
91 .nf
92
93 struct xfs_getparents_rec {
94 struct xfs_handle gpr_parent;
95 __u16 gpr_reclen;
96 char gpr_name[];
97 };
98 .fi
99 .in
100
101 .PP
102 The field
103 .I gpr_parent
104 is a file handle that can be used to open the parent directory.
105
106 .PP
107 The field
108 .I gpr_reclen
109 will be set to the number of bytes used by this parent record.
110
111 .PP
112 The array
113 .I gpr_name
114 will be set to a NULL-terminated byte sequence representing the filename
115 stored in the parent pointer.
116 If the name is a zero-length string, the file queried has no parents.
117
118 .SH SAMPLE PROGRAM
119 Calling programs should allocate a large memory buffer, initialize the head
120 structure to zeroes, set gp_bufsize to the size of the buffer, and call the
121 ioctl.
122 The XFS_GETPARENTS_OFLAG_DONE flag will be set in gp_flags when there are no
123 more parent pointers to be read.
124 The below code is an example of XFS_IOC_GETPARENTS usage:
125
126 .nf
127 #include <stdio.h>
128 #include <string.h>
129 #include <errno.h>
130 #include <xfs/linux.h>
131 #include <xfs/xfs.h>
132 #include <xfs/xfs_types.h>
133 #include <xfs/xfs_fs.h>
134
135 int main() {
136 struct xfs_getparents gp = { };
137 struct xfs_getparents_rec *gpr;
138 int error, fd;
139
140 gp.gp_buffer = (uintptr_t)malloc(65536);
141 if (!gp.gp_buffer) {
142 perror("malloc");
143 return 1;
144 }
145 gp->gp_bufsize = 65536;
146
147 fd = open("/mnt/test/foo.txt", O_RDONLY | O_CREAT);
148 if (fd == -1)
149 return errno;
150
151 do {
152 error = ioctl(fd, XFS_IOC_GETPARENTS, gp);
153 if (error)
154 return error;
155
156 for (gpr = xfs_getparents_first_rec(&gp);
157 gpr != NULL;
158 gpr = xfs_getparents_next_rec(&gp, gpr)) {
159 if (gpr->gpr_name[0] == 0)
160 break;
161
162 printf("inode = %llu\\n",
163 gpr->gpr_parent.ha_fid.fid_ino);
164 printf("generation = %u\\n",
165 gpr->gpr_parent.ha_fid.fid_gen);
166 printf("name = \\"%s\\"\\n\\n",
167 gpr->gpr_name);
168 }
169 } while (!(gp.gp_flags & XFS_GETPARENTS_OFLAG_DONE));
170
171 return 0;
172 }
173 .fi
174
175 .SH RETURN VALUE
176 On error, \-1 is returned, and
177 .I errno
178 is set to indicate the error.
179 .PP
180 .SH ERRORS
181 Error codes can be one of, but are not limited to, the following:
182 .TP
183 .B EFSBADCRC
184 Metadata checksum validation failed while performing the query.
185 .TP
186 .B EFSCORRUPTED
187 Metadata corruption was encountered while performing the query.
188 .TP
189 .B EINVAL
190 One or more of the arguments specified is invalid.
191 .TP
192 .B EMSGSIZE
193 The record buffer was not large enough to store even a single record.
194 .TP
195 .B ENOMEM
196 Not enough memory to retrieve parent pointers.
197 .TP
198 .B EOPNOTSUPP
199 Repairs of the requested metadata object are not supported.
200 .TP
201 .B EROFS
202 Filesystem is read-only and a repair was requested.
203 .TP
204 .B ESHUTDOWN
205 Filesystem is shut down due to previous errors.
206 .TP
207 .B EIO
208 An I/O error was encountered while performing the query.
209 .SH CONFORMING TO
210 This API is specific to XFS filesystem on the Linux kernel.
211 .SH SEE ALSO
212 .BR ioctl (2)