]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/getattrlistbulk.2
xnu-6153.121.1.tar.gz
[apple/xnu.git] / bsd / man / man2 / getattrlistbulk.2
1 .\" Copyright (c) 2013 Apple Computer, Inc. All rights reserved.
2 .\"
3 .\" The contents of this file constitute Original Code as defined in and
4 .\" are subject to the Apple Public Source License Version 1.1 (the
5 .\" "License"). You may not use this file except in compliance with the
6 .\" License. Please obtain a copy of the License at
7 .\" http://www.apple.com/publicsource and read it before using this file.
8 .\"
9 .\" This Original Code and all software distributed under the License are
10 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
11 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
12 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
13 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
14 .\" License for the specific language governing rights and limitations
15 .\" under the License.
16 .\"
17 .\" @(#)getattrlistbulk.2
18 .
19 .Dd November 15, 2013
20 .Dt GETATTRLISTBULK 2
21 .Os Darwin
22 .Sh NAME
23 .Nm getattrlistbulk
24 .Nd get file system attributes for multiple directory entries
25 .Sh SYNOPSIS
26 .Fd #include <sys/attr.h>
27 .Fd #include <unistd.h>
28 .Pp
29 .Ft int
30 .Fn getattrlistbulk "int dirfd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "uint64_t options"
31 .
32 .
33 .Sh DESCRIPTION
34 The
35 .Fn getattrlistbulk
36 function iterates over the items in a directory and returns information about
37 each directory entry like
38 .Xr getattrlist 2 .
39 Note: when
40 .Fn getattrlistbulk
41 returns information about a symbolic link, the information returned is about the link itself, not the target of the link.
42 The order of the directory entries (and their associated metadata) vended by
43 .Fn getattrlistbulk
44 is not specified. Some file systems may return entries in lexicographic sort order and others may not.
45 .Pp
46 The function reads directory entries from the directory referenced by the file
47 descriptor
48 .Fa dirfd .
49 The
50 .Fa attrList
51 parameter determines what attributes are returned for each entry.
52 Attributes of those directory entries are placed into the buffer specified by
53 .Fa attrBuf
54 and
55 .Fa attrBufSize .
56 The
57 .Fa options
58 parameter allows you to modify the behaviour of the call.
59 .Pp
60 .
61 .Pp
62 .
63 .\" dirfd parameter
64 .
65 The
66 .Fa dirfd
67 parameter must be a file descriptor that references a directory that you have opened for reading.
68 .Pp
69 .
70 .\" attrList parameter
71 .
72 The
73 .Fa attrList
74 parameter is a pointer to an
75 .Vt attrlist
76 structure.
77 All fields of this structure must be filled before calling the function.
78 See the discussion of the
79 .Xr getattrlist 2
80 function for a detailed description of this structure.
81 To get an attribute, the corresponding bit in the appropriate
82 .Vt attrgroup_t
83 field of the
84 .Vt attrlist
85 structure must be set.
86 Volume attributes cannot be requested but all other supported getattrlist attributes can be used. For this function,
87 .Dv ATTR_CMN_NAME
88 and
89 .Dv ATTR_CMN_RETURNED_ATTRS
90 are required and the absence of these attributes in the attrList parameter results in an error. Note that
91 not all attributes supported by
92 .Fn getattrlist
93 may be vended back by this call, which is why the aforementioned flag must be supplied. In particular
94 .Dv ATTR_CMN_FULLPATH
95 may not be valid on all directory entries whose information is requested by this call.
96 .Pp
97 .
98 .\" attrBuf and attrBufSize parameters
99 .
100 The
101 .Fa attrBuf
102 and
103 .Fa attrBufSize
104 parameters specify a buffer into which the function places attribute values.
105 The attributes for any given directory entry are grouped together and
106 packed in exactly the same way as they are returned from
107 .Xr getattrlist 2
108 and are subject to exactly the same alignment specifications
109 and restrictions. These groups are then placed into the buffer, one after another.
110 .Xr getattrlist 2 should be consulted on details of the attributes that can be
111 requested for and returned. The name of the entry itself is provided by the
112 .Dv ATTR_CMN_NAME
113 attribute. Each group starts with a leading
114 .Vt uint32_t
115 , which will always be 8-byte aligned that contains the overall length of the group.
116 You can step from one group to the next by simply adding this length to your pointer.
117 The sample code (below) shows how to do this.
118 The initial contents of this buffer are ignored.
119 .Pp
120 .
121 .\" options parameter
122 .
123 The
124 .Fa options
125 parameter is a bit set that controls the behaviour of
126 .Fn getattrlistbulk .
127 The following option bits are defined.
128 .
129 .Bl -tag -width FSOPT_PACK_INVAL_ATTRS
130 .
131 .It FSOPT_PACK_INVAL_ATTRS
132 If this is bit is set, then all requested attributes,
133 even ones that are not supported by the object or file
134 file system, will be returned the attrBuf. The attributes
135 actually returned can be determined by looking at the
136 attribute_set_t structure returned for the
137 .Dv ATTR_CMN_RETURNED_ATTRS
138 attribute. Default values will be returned for invalid
139 attributes and should be ignored.
140 .Pp
141 Please see the discussion of this flag in
142 .Xr getattrlist 2
143 .
144 .El
145 .Pp
146 If
147 .Dv ATTR_CMN_ERROR
148 has been requested and an error specific to a directory entry occurs,
149 an error will be reported. The
150 .Dv ATTR_CMN_ERROR
151 attribute is a uint32_t which, if non-zero, specifies the error code
152 that was encountered during the processing of that directory entry. The
153 .Dv ATTR_CMN_ERROR
154 attribute will be after
155 .Dv ATTR_CMN_RETURNED_ATTRS
156 attribute in the returned buffer.
157 .Pp
158 It is typical to ask for a combination of common, file, and directory
159 attributes and then use the value of the
160 .Dv ATTR_CMN_OBJTYPE
161 attribute to parse the resulting attribute buffer.
162 .Pp
163 A directory which is a mount point for a file system, will have a value of
164 .Dq DIR_MNTSTATUS_MNTPOINT
165 set for its ATTR_DIR_MOUNTSTATUS attribute entry.
166 However the attributes for the mount point will be those from the (underlying) file system.
167 To get the attributes of the mounted root directory, call
168 .Xr getattrlist 2
169 on the mount point.
170 .Pp
171 A directory which is a firmlink will have the
172 .Dq SF_FIRMLINK
173 flag set in its ATTR_CMN_FLAGS attribute entry.
174 However, the attributes returned by
175 .Fn getattrlistbulk
176 will be those from the firmlink, not the firmlink's target.
177 To get the attribute of the firmlink's target, call
178 .Xr getattrlist 2
179 on the firmlink.
180 .
181 .Sh RETURN VALUES
182 Upon successful completion the numbers of entries successfully read
183 is returned. A value of 0 indicates there are no more entries. Once 0 is returned,
184 no further entries are returned even if new entries are added to the directory.
185 Directory iteration should be restarted either by repostioning the offset to 0 by
186 .Fn lseek
187 or by closing the file descriptor and opening the directory again. On error,
188 a value of -1 is returned and
189 .Va errno
190 is set to indicate the error.
191 .Pp
192 When iterating all entries in a directory,
193 .Fn getattrlistbulk
194 is called repeatedly until a 0 is returned. In such a case if
195 .Fn readdir
196 and
197 .Fn getattrlistbulk
198 calls on the same fd are mixed, the behavior is undefined.
199
200 .Pp
201 .Sh ERRORS
202 .Fn getattrlistbulk
203 will fail if:
204 .Bl -tag -width Er
205 .
206 .It Bq Er EBADF
207 .Fa dirfd
208 is not a valid file descriptor for a directory open for reading.
209 .
210 .It Bq Er ENOTDIR
211 The File descriptor
212 .Fa dirfd
213 is not a directory.
214 .
215 .It Bq Er EACCES
216 Search permission is denied on the directory whose descriptor is given
217 as input.
218 .
219 .It Bq Er EFAULT
220 .Fa attrList
221 or
222 .Em attrBuf
223 points to an invalid address.
224 .
225 .It Bq Er ERANGE
226 The buffer was too small.
227 .
228 .It Bq Er EINVAL
229 The
230 .Fa bitmapcount
231 field of
232 .Fa attrList
233 is not
234 .Dv ATTR_BIT_MAP_COUNT .
235 .
236 .It Bq Er EINVAL
237 An invalid attribute was requested.
238 .
239 .It Bq Er EINVAL
240 Volume attributes were requested.
241 .
242 .It Bq Er EINVAL
243 .Dv ATTR_CMN_NAME
244 or
245 .Dv ATTR_CMN_RETURNED_ATTRS
246 was not requested in the attrList parameter.
247 .
248 .It Bq Er EIO
249 An I/O error occurred while reading from or writing to the file system.
250 .El
251 .Pp
252 .
253 .Sh EXAMPLES
254 .
255 The following code lists the contents of a directory using
256 .Fn getattrlistbulk .
257 The listing includes the file type.
258 .
259 .Bd -literal
260 #include <sys/syscall.h>
261 #include <sys/attr.h>
262 #include <sys/errno.h>
263 #include <sys/vnode.h>
264 #include <unistd.h>
265 #include <fcntl.h>
266 #include <stdio.h>
267 #include <assert.h>
268 #include <stddef.h>
269 #include <string.h>
270 #include <stdbool.h>
271
272 typedef struct val_attrs {
273 uint32_t length;
274 attribute_set_t returned;
275 uint32_t error;
276 attrreference_t name_info;
277 char *name;
278 fsobj_type_t obj_type;
279 } val_attrs_t;
280
281
282 void demo(const char *dirpath)
283 {
284 int error;
285 int dirfd;
286 struct attrlist attrList;
287 char *entry_start;
288 char attrBuf[256];
289
290 memset(&attrList, 0, sizeof(attrList));
291 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
292 attrList.commonattr = ATTR_CMN_RETURNED_ATTRS |
293 ATTR_CMN_NAME |
294 ATTR_CMN_ERROR |
295 ATTR_CMN_OBJTYPE;
296
297 error = 0;
298 dirfd = open(dirpath, O_RDONLY, 0);
299 if (dirfd < 0) {
300 error = errno;
301 printf("Could not open directory %s", dirpath);
302 perror("Error was ");
303 } else {
304 for (;;) {
305 int retcount;
306
307 retcount = getattrlistbulk(dirfd, &attrList, &attrBuf[0],
308 sizeof(attrBuf), 0);
309 printf("\engetattrlistbulk returned %d", retcount);
310 if (retcount == -1) {
311 error = errno;
312 perror("Error returned : ");
313 printf("\en");
314 break;
315 } else if (retcount == 0) {
316 /* No more entries in directory */
317 error = 0;
318 break;
319 } else {
320 int index;
321 uint32_t total_length;
322 char *field;
323
324 entry_start = &attrBuf[0];
325 total_length = 0;
326 printf(" -> entries returned");
327 for (index = 0; index < retcount; index++) {
328 val_attrs_t attrs = {0};
329
330 printf("\en Entry %d", index);
331 printf(" -- ");
332 field = entry_start;
333 attrs.length = *(uint32_t *)field;
334 printf(" Length %d ", attrs.length);
335 total_length += attrs.length;
336 printf(" Total Length %d ", total_length);
337 field += sizeof(uint32_t);
338 printf(" -- ");
339
340 /* set starting point for next entry */
341 entry_start += attrs.length;
342
343 attrs.returned = *(attribute_set_t *)field;
344 field += sizeof(attribute_set_t);
345
346 if (attrs.returned.commonattr & ATTR_CMN_ERROR) {
347 attrs.error = *(uint32_t *)field;
348 field += sizeof(uint32_t);
349 }
350
351 if (attrs.returned.commonattr & ATTR_CMN_NAME) {
352 attrs.name = field;
353 attrs.name_info = *(attrreference_t *)field;
354 field += sizeof(attrreference_t);
355 printf(" %s ", (attrs.name +
356 attrs.name_info.attr_dataoffset));
357 }
358
359 /* Check for error for this entry */
360 if (attrs.error) {
361 /*
362 * Print error and move on to next
363 * entry
364 */
365 printf("Error in reading attributes for directory \
366 entry %d", attrs.error);
367 continue;
368 }
369
370 printf(" -- ");
371 if (attrs.returned.commonattr & ATTR_CMN_OBJTYPE) {
372 attrs.obj_type = *(fsobj_type_t *)field;
373 field += sizeof(fsobj_type_t);
374
375 switch (attrs.obj_type) {
376 case VREG:
377 printf("file ");
378 break;
379 case VDIR:
380 printf("directory ");
381 break;
382 default:
383 printf("obj_type = %-2d ", attrs.obj_type);
384 break;
385 }
386 }
387 printf(" -- ");
388 }
389 }
390 }
391 (void)close(dirfd);
392 }
393 }
394 .Ed
395 .Pp
396 .
397 .Sh SEE ALSO
398 .
399 .Xr getattrlist 2 ,
400 .Xr lseek 2
401 .
402 .Sh HISTORY
403 A
404 .Fn getattrlistbulk
405 function call appeared in OS X version 10.10
406 .