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 ATRR_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 "DIR_MNTSTATUS_MNTPOINT" set for it's the
 164 ATTR_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.
 165 .
 166 .Sh RETURN VALUES
 167 Upon successful completion the numbers of entries successfully read
 168 is returned. A value of 0 indicates there are no more entries. Once 0 is returned,
 169 no further entries are returned even if new entries are added to the directory.
 170 Directory iteration should be restarted either by repostioning the offset to 0 by
 171 .Fn lseek
 172 or by closing the file descriptor and opening the directory again. On error,
 173 a value of -1 is returned and
 174 .Va errno
 175 is set to indicate the error.
 176 .Pp
 177 When iterating all entries in a directory,
 178 .Fn getattrlistbulk
 179 is called repeatedly until a 0 is returned. In such a case if
 180 .Fn readdir
 181 and
 182 .Fn getattrlistbulk
 183 calls on the same fd are mixed, the behavior is undefined.
 184
 185 .Pp
 186 .Sh ERRORS
 187 .Fn getattrlistbulk
 188 will fail if:
 189 .Bl -tag -width Er
 190 .
 191 .It Bq Er EBADF
 192 .Fa dirfd
 193 is not a valid file descriptor for a directory open for reading.
 194 .
 195 .It Bq Er ENOTDIR
 196 The File descriptor
 197 .Fa dirfd
 198 is not a directory.
 199 .
 200 .It Bq Er EACCES
 201 Search permission is denied on the directory whose descriptor is given
 202 as input.
 203 .
 204 .It Bq Er EFAULT
 205 .Fa attrList
 206 or
 207 .Em attrBuf
 208 points to an invalid address.
 209 .
 210 .It Bq Er ERANGE
 211 The buffer was too small.
 212 .
 213 .It Bq Er EINVAL
 214 The
 215 .Fa bitmapcount
 216 field of
 217 .Fa attrList
 218 is not
 219 .Dv ATTR_BIT_MAP_COUNT .
 220 .
 221 .It Bq Er EINVAL
 222 An invalid attribute was requested.
 223 .
 224 .It Bq Er EINVAL
 225 Volume attributes were requested.
 226 .
 227 .It Bq Er EINVAL
 228 .Dv ATTR_CMN_NAME
 229 or
 230 .Dv ATTR_CMN_RETURNED_ATTRS
 231 was not requested in the attrList parameter.
 232 .
 233 .It Bq Er EIO
 234 An I/O error occurred while reading from or writing to the file system.
 235 .El
 236 .Pp
 237 .
 238 .Sh EXAMPLES
 239 .
 240 The following code lists the contents of a directory using
 241 .Fn getattrlistbulk .
 242 The listing includes the file type.
 243 .
 244 .Bd -literal
 245 #include <sys/syscall.h>
 246 #include <sys/attr.h>
 247 #include <sys/errno.h>
 248 #include <sys/vnode.h>
 249 #include <unistd.h>
 250 #include <fcntl.h>
 251 #include <stdio.h>
 252 #include <assert.h>
 253 #include <stddef.h>
 254 #include <string.h>
 255 #include <stdbool.h>
 256
 257 typedef struct val_attrs {
 258     uint32_t          length;
 259     attribute_set_t   returned;
 260     uint32_t          error;
 261     attrreference_t   name_info;
 262     char              *name;
 263     fsobj_type_t      obj_type;
 264 } val_attrs_t;
 265
 266
 267 void demo(const char *dirpath)
 268 {
 269     int error;
 270     int dirfd;
 271     struct attrlist attrList;
 272     char *entry_start;
 273     char attrBuf[256];
 274
 275     memset(&attrList, 0, sizeof(attrList));
 276     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 277     attrList.commonattr  = ATTR_CMN_RETURNED_ATTRS |
 278                            ATTR_CMN_NAME |
 279                            ATTR_CMN_ERROR |
 280                            ATTR_CMN_OBJTYPE;
 281
 282     error = 0;
 283     dirfd = open(dirpath, O_RDONLY, 0);
 284     if (dirfd < 0) {
 285         error = errno;
 286         printf("Could not open directory %s", dirpath);
 287         perror("Error was ");
 288     } else {
 289         for (;;) {
 290             int retcount;
 291
 292             retcount = getattrlistbulk(dirfd, &attrList, &attrBuf[0],
 293                                sizeof(attrBuf), 0);
 294             printf("\engetattrlistbulk returned %d", retcount);
 295             if (retcount == -1) {
 296                 error = errno;
 297                 perror("Error returned : ");
 298                 printf("\en");
 299                 break;
 300             } else if (retcount == 0) {
 301                 /* No more entries in directory */
 302                 error = 0;
 303                 break;
 304             } else {
 305                 int    index;
 306                 uint32_t total_length;
 307                 char   *field;
 308
 309                 entry_start = &attrBuf[0];
 310                 total_length = 0;
 311                 printf(" -> entries returned");
 312                 for (index = 0; index < retcount; index++) {
 313                     val_attrs_t    attrs = {0};
 314
 315                     printf("\en Entry %d", index);
 316                     printf("  --  ");
 317                     field = entry_start;
 318                     attrs.length = *(uint32_t *)field;
 319                     printf(" Length %d ", attrs.length);
 320                     total_length += attrs.length;
 321                     printf(" Total Length %d ", total_length);
 322                     field += sizeof(uint32_t);
 323                     printf("  --  ");
 324
 325                     /* set starting point for next entry */
 326                     entry_start += attrs.length;
 327
 328                     attrs.returned = *(attribute_set_t *)field;
 329                     field += sizeof(attribute_set_t);
 330
 331                     if (attrs.returned.commonattr & ATTR_CMN_ERROR) {
 332                         attrs.error = *(uint32_t *)field;
 333                         field += sizeof(uint32_t);
 334                     }
 335
 336                     if (attrs.returned.commonattr & ATTR_CMN_NAME) {
 337                         attrs.name =  field;
 338                         attrs.name_info = *(attrreference_t *)field;
 339                         field += sizeof(attrreference_t);
 340                         printf("  %s ", (attrs.name +
 341                             attrs.name_info.attr_dataoffset));
 342                     }
 343
 344                     /* Check for error for this entry */
 345                     if (attrs.error) {
 346                         /*
 347                          * Print error and move on to next
 348                          * entry
 349                          */
 350                         printf("Error in reading attributes for directory \
 351                                entry %d", attrs.error);
 352                         continue;
 353                     }
 354
 355                     printf("  --  ");
 356                     if (attrs.returned.commonattr & ATTR_CMN_OBJTYPE) {
 357                         attrs.obj_type = *(fsobj_type_t *)field;
 358                         field += sizeof(fsobj_type_t);
 359
 360                         switch (attrs.obj_type) {
 361                             case VREG:
 362                                 printf("file  ");
 363                                 break;
 364                             case VDIR:
 365                                 printf("directory    ");
 366                                 break;
 367                             default:
 368                                 printf("obj_type = %-2d  ", attrs.obj_type);
 369                                 break;
 370                         }
 371                     }
 372                     printf("  --  ");
 373                 }
 374             }
 375         }
 376         (void)close(dirfd);
 377     }
 378 }
 379 .Ed
 380 .Pp
 381 .
 382 .Sh SEE ALSO
 383 .
 384 .Xr getattrlist 2 ,
 385 .Xr lseek 2
 386 .
 387 .Sh HISTORY
 388 A
 389 .Fn getattrlistbulk
 390 function call appeared in OS X version 10.10
 391 .