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