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. 42The order of the directory entries (and their associated metadata) vended by 43.Fn getattrlistbulk 44is not specified. Some file systems may return entries in lexicographic sort order and others may not. 45.Pp 46The function reads directory entries from the directory referenced by the file 47descriptor 48.Fa dirfd . 49The 50.Fa attrList 51parameter determines what attributes are returned for each entry. 52Attributes of those directory entries are placed into the buffer specified by 53.Fa attrBuf 54and 55.Fa attrBufSize . 56The 57.Fa options 58parameter allows you to modify the behaviour of the call. 59.Pp 60. 61.Pp 62. 63.\" dirfd parameter 64. 65The 66.Fa dirfd 67parameter must be a file descriptor that references a directory that you have opened for reading. 68.Pp 69. 70.\" attrList parameter 71. 72The 73.Fa attrList 74parameter is a pointer to an 75.Vt attrlist 76structure. 77All fields of this structure must be filled before calling the function. 78See the discussion of the 79.Xr getattrlist 2 80function for a detailed description of this structure. 81To get an attribute, the corresponding bit in the appropriate 82.Vt attrgroup_t 83field of the 84.Vt attrlist 85structure must be set. 86Volume attributes cannot be requested but all other supported getattrlist attributes can be used. For this function, 87.Dv ATTR_CMN_NAME 88and 89.Dv ATTR_CMN_RETURNED_ATTRS 90are required and the absence of these attributes in the attrList parameter results in an error. Note that 91not all attributes supported by 92.Fn getattrlist 93may be vended back by this call, which is why the aforementioned flag must be supplied. In particular 94.Dv ATTR_CMN_FULLPATH 95may not be valid on all directory entries whose information is requested by this call. 96.Pp 97. 98.\" attrBuf and attrBufSize parameters 99. 100The 101.Fa attrBuf 102and 103.Fa attrBufSize 104parameters specify a buffer into which the function places attribute values. 105The attributes for any given directory entry are grouped together and 106packed in exactly the same way as they are returned from 107.Xr getattrlist 2 108and are subject to exactly the same alignment specifications 109and 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 111requested for and returned. The name of the entry itself is provided by the 112.Dv ATTR_CMN_NAME 113attribute. 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. 116You can step from one group to the next by simply adding this length to your pointer. 117The sample code (below) shows how to do this. 118The initial contents of this buffer are ignored. 119.Pp 120. 121.\" options parameter 122. 123The 124.Fa options 125parameter is a bit set that controls the behaviour of 126.Fn getattrlistbulk . 127The following option bits are defined. 128. 129.Bl -tag -width FSOPT_PACK_INVAL_ATTRS 130. 131.It FSOPT_PACK_INVAL_ATTRS 132If this is bit is set, then all requested attributes, 133even ones that are not supported by the object or file 134file system, will be returned the attrBuf. The attributes 135actually returned can be determined by looking at the 136attribute_set_t structure returned for the 137.Dv ATTR_CMN_RETURNED_ATTRS 138attribute. Default values will be returned for invalid 139attributes and should be ignored. 140.Pp 141Please see the discussion of this flag in 142.Xr getattrlist 2 143. 144.El 145.Pp 146If 147.Dv ATTR_CMN_ERROR 148has been requested and an error specific to a directory entry occurs, 149an error will be reported. The 150.Dv ATTR_CMN_ERROR 151attribute is a uint32_t which, if non-zero, specifies the error code 152that was encountered during the processing of that directory entry. The 153.Dv ATTR_CMN_ERROR 154attribute will be after 155.Dv ATTR_CMN_RETURNED_ATTRS 156attribute in the returned buffer. 157.Pp 158It is typical to ask for a combination of common, file, and directory 159attributes and then use the value of the 160.Dv ATTR_CMN_OBJTYPE 161attribute to parse the resulting attribute buffer. 162.Pp 163A directory which is a mount point for a file system, will have a value of 164.Dq DIR_MNTSTATUS_MNTPOINT 165set for its ATTR_DIR_MOUNTSTATUS attribute entry. 166However the attributes for the mount point will be those from the (underlying) file system. 167To get the attributes of the mounted root directory, call 168.Xr getattrlist 2 169on the mount point. 170.Pp 171A directory which is a firmlink will have the 172.Dq SF_FIRMLINK 173flag set in its ATTR_CMN_FLAGS attribute entry. 174However, the attributes returned by 175.Fn getattrlistbulk 176will be those from the firmlink, not the firmlink's target. 177To get the attribute of the firmlink's target, call 178.Xr getattrlist 2 179on the firmlink. 180. 181.Sh RETURN VALUES 182Upon successful completion the numbers of entries successfully read 183is returned. A value of 0 indicates there are no more entries. Once 0 is returned, 184no further entries are returned even if new entries are added to the directory. 185Directory iteration should be restarted either by repostioning the offset to 0 by 186.Fn lseek 187or by closing the file descriptor and opening the directory again. On error, 188a value of -1 is returned and 189.Va errno 190is set to indicate the error. 191.Pp 192When iterating all entries in a directory, 193.Fn getattrlistbulk 194is called repeatedly until a 0 is returned. In such a case if 195.Fn readdir 196and 197.Fn getattrlistbulk 198calls on the same fd are mixed, the behavior is undefined. 199 200.Pp 201.Sh ERRORS 202.Fn getattrlistbulk 203will fail if: 204.Bl -tag -width Er 205. 206.It Bq Er EBADF 207.Fa dirfd 208is not a valid file descriptor for a directory open for reading. 209. 210.It Bq Er ENOTDIR 211The File descriptor 212.Fa dirfd 213is not a directory. 214. 215.It Bq Er EACCES 216Search permission is denied on the directory whose descriptor is given 217as input. 218. 219.It Bq Er EFAULT 220.Fa attrList 221or 222.Em attrBuf 223points to an invalid address. 224. 225.It Bq Er ERANGE 226The buffer was too small. 227. 228.It Bq Er EINVAL 229The 230.Fa bitmapcount 231field of 232.Fa attrList 233is not 234.Dv ATTR_BIT_MAP_COUNT . 235. 236.It Bq Er EINVAL 237An invalid attribute was requested. 238. 239.It Bq Er EINVAL 240Volume attributes were requested. 241. 242.It Bq Er EINVAL 243.Dv ATTR_CMN_NAME 244or 245.Dv ATTR_CMN_RETURNED_ATTRS 246was not requested in the attrList parameter. 247. 248.It Bq Er EIO 249An I/O error occurred while reading from or writing to the file system. 250.El 251.Pp 252. 253.Sh EXAMPLES 254. 255The following code lists the contents of a directory using 256.Fn getattrlistbulk . 257The 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 272typedef 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 282void 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 403A 404.Fn getattrlistbulk 405function call appeared in OS X version 10.10 406. 407