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.
  88 .Pp
  89 .
  90 .\" attrBuf and attrBufSize parameters
  91 .
  92 The
  93 .Fa attrBuf
  94 and
  95 .Fa attrBufSize
  96 parameters specify a buffer into which the function places attribute values.
  97 The attributes for any given directory entry are grouped together and
  98 packed in exactly the same way as they are returned from
  99 .Xr getattrlist 2
 100 and are subject to exactly the same alignment specifications
 101 and 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
 103 requested for and returned. The name of the entry itself is provided by the
 104 .Dv ATTR_CMN_NAME
 105 attribute.  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.
 108 You can step from one group to the next by simply adding this length to your pointer.
 109 The sample code (below) shows how to do this.
 110 The initial contents of this buffer are ignored.
 111 .Pp
 112 .
 113 .\" options parameter
 114 .
 115 The
 116 .Fa options
 117 parameter is a bit set that controls the behaviour of
 118 .Fn getattrlistbulk .
 119 The following option bits are defined.
 120 .
 121 .Bl -tag -width FSOPT_PACK_INVAL_ATTRS
 122 .
 123 .It FSOPT_PACK_INVAL_ATTRS
 124 If this is bit is set, then all requested  attributes,
 125 even ones that are not supported by the object or file
 126 file system, will be returned the attrBuf. The attributes
 127 actually returned can be determined by looking at the
 128 attribute_set_t structure returned for the
 129 .Dv ATTR_CMN_RETURNED_ATTRS
 130 attribute. Default values will be returned for invalid
 131 attributes and should be ignored.
 132 .Pp
 133 Please see the discussion of this flag in
 134 .Xr getattrlist 2
 135 .
 136 .El
 137 .Pp
 138 If
 139 .Dv ATTR_CMN_ERROR
 140 has been requested and an error specific to a directory entry occurs,
 141 an error will be reported. The
 142 .Dv ATTR_CMN_ERROR
 143 attribute is a uint32_t which, if non-zero, specifies the error code
 144 that was encountered during the processing of that directory entry. The
 145 .Dv ATTR_CMN_ERROR
 146 attribute will be after
 147 .Dv ATTR_CMN_RETURNED_ATTRS
 148 attribute in the returned buffer.
 149 .Pp
 150 It is typical to ask for a combination of common, file, and directory
 151 attributes and then use the value of the
 152 .Dv ATTR_CMN_OBJTYPE
 153 attribute to parse the resulting attribute buffer.
 154 .Pp
 155 A directory which is a mount point for a file system, will have a value of "DIR_MNTSTATUS_MNTPOINT" set for it's the
 156 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.
 157 .
 158 .Sh RETURN VALUES
 159 Upon successful completion the numbers of entries successfully read
 160 is returned. A value of 0 indicates there are no more entries. Once 0 is returned,
 161 no further entries are returned even if new entries are added to the directory.
 162 Directory iteration should be restarted either by repostioning the offset to 0 by
 163 .Fn lseek
 164 or by closing the file descriptor and opening the directory again. On error,
 165 a value of -1 is returned and
 166 .Va errno
 167 is set to indicate the error.
 168 .Pp
 169 When iterating all entries in a directory,
 170 .Fn getattrlistbulk
 171 is called repeatedly until a 0 is returned. In such a case if
 172 .Fn readdir
 173 and
 174 .Fn getattrlistbulk
 175 calls on the same fd are mixed, the behavior is undefined.
 176
 177 .Pp
 178 .Sh ERRORS
 179 .Fn getattrlistbulk
 180 will fail if:
 181 .Bl -tag -width Er
 182 .
 183 .It Bq Er EBADF
 184 .Fa dirfd
 185 is not a valid file descriptor for a directory open for reading.
 186 .
 187 .It Bq Er ENOTDIR
 188 The File descriptor
 189 .Fa dirfd
 190 is not a directory.
 191 .
 192 .It Bq Er EACCES
 193 Search permission is denied on the directory whose descriptor is given
 194 as input.
 195 .
 196 .It Bq Er EFAULT
 197 .Fa attrList
 198 or
 199 .Em attrBuf
 200 points to an invalid address.
 201 .
 202 .It Bq Er ERANGE
 203 The buffer was too small.
 204 .
 205 .It Bq Er EINVAL
 206 The
 207 .Fa bitmapcount
 208 field of
 209 .Fa attrList
 210 is not
 211 .Dv ATTR_BIT_MAP_COUNT .
 212 .
 213 .It Bq Er EINVAL
 214 An invalid attribute was requested.
 215 .
 216 .It Bq Er EINVAL
 217 Volume attributes were requested.
 218 .
 219 .It Bq Er EINVAL
 220 .Dv ATTR_CMN_NAME
 221 or
 222 .Dv ATTR_CMN_RETURNED_ATTRS
 223 was not requested in the attrList parameter.
 224 .
 225 .It Bq Er EIO
 226 An I/O error occurred while reading from or writing to the file system.
 227 .El
 228 .Pp
 229 .
 230 .Sh EXAMPLES
 231 .
 232 The following code lists the contents of a directory using
 233 .Fn getattrlistbulk .
 234 The 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
 249 typedef 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
 259 void 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
 380 A
 381 .Fn getattrlistbulk
 382 function call appeared in OS X version 10.10
 383 .