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