bsd/man/man2/getdirentriesattr.2

   1 .\" Copyright (c) 2003 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 .\"     @(#)getdirentriesattr.2
  18 .
  19 .Dd December 15, 2003
  20 .Dt GETDIRENTRIESATTR 2
  21 .Os Darwin
  22 .Sh NAME
  23 .Nm getdirentriesattr
  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 .Fd #if __LP64__
  30 .Ft int
  31 .Fn getdirentriesattr "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned int * count" "unsigned int * basep" "unsigned int * newState" "unsigned int options"
  32 .Fd #else
  33 .Ft int
  34 .Fn getdirentriesattr "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long * count" "unsigned long * basep" "unsigned long * newState" "unsigned long options"
  35 .Fd #endif
  36 .
  37 .
  38 .Sh DESCRIPTION
  39 The
  40 .Fn getdirentriesattr
  41 function reads directory entries and returns their attributes (that is, metadata).
  42 You can think of it as a combination of
  43 .Xr getdirentries 2
  44 and
  45 .Xr getattrlist 2 .
  46 .Fn getdirentriesattr
  47 iterates over the items in a directory like
  48 .Xr getdirentries 2 ,
  49 and returns information about each directory entry like
  50 .Xr getattrlist 2 .
  51 Note: when
  52 .Fn getdirentriesattr
  53 returns information about a symbolic link, the information returned is about the link itself, not the target of the link.
  54 .Pp
  55 The function reads directory entries from the directory referenced by the
  56 file descriptor
  57 .Fa fd .
  58 Attributes of those directory entries are placed into the buffer specified by
  59 .Fa attrBuf
  60 and
  61 .Fa attrBufSize .
  62 The
  63 .Fa attrList
  64 parameter determines what attributes are returned for each entry.
  65 The
  66 .Fa count
  67 parameter contains the number of directory entries requested and returned.
  68 The
  69 .Fa basep
  70 parameter returns the directory offset in a manner similar to
  71 .Xr getdirentries 2 .
  72 The
  73 .Fa newState
  74 parameter allows you to check whether the directory has been modified while
  75 you were reading it.
  76 The
  77 .Fa options
  78 parameter lets you control specific aspects of the function's behaviour.
  79 .Pp
  80 .
  81 The
  82 .Fn getdirentriesattr
  83 function is only supported by certain volume format implementations.
  84 For maximum compatibility, client programs should use high-level APIs
  85 (such as the Carbon File Manager) to access file system attributes.
  86 These high-level APIs include logic to emulate file system attributes
  87 on volumes that don't support
  88 .Fn getdirentriesattr .
  89 .Pp
  90 .
  91 .\" fd parameter
  92 .
  93 The
  94 .Fa fd
  95 parameter must be a file descriptor that references a directory that you have opened for reading.
  96 .Pp
  97 .
  98 .\" attrList parameter
  99 .
 100 The
 101 .Fa attrList
 102 parameter is a pointer to an
 103 .Vt attrlist
 104 structure.
 105 You are responsible for filling out all fields of this structure before calling the function.
 106 See the discussion of the
 107 .Xr getattrlist 2
 108 function for a detailed description of this structure.
 109 To get an attribute you must set the corresponding bit in the appropriate
 110 .Vt attrgroup_t
 111 field of the
 112 .Vt attrlist
 113 structure.
 114 You must not request volume attributes.
 115 .Pp
 116 .
 117 .\" attrBuf and attrBufSize parameters
 118 .
 119 The
 120 .Fa attrBuf
 121 and
 122 .Fa attrBufSize
 123 parameters specify a buffer into which the function places attribute values.
 124 The attributes for any given directory entry are grouped together and
 125 packed in exactly the same way as they are returned from
 126 .Xr getattrlist 2 .
 127 These groups are then placed into the buffer, one after another.
 128 As each group starts with a leading
 129 .Vt u_int32_t
 130 that contains the
 131 overall length of the group, you can step from one group to the next
 132 by simply adding this length to your pointer.
 133 The sample code (below) shows how to do this.
 134 The initial contents of this buffer are ignored.
 135 .Pp
 136 .
 137 .\" count parameter
 138 .
 139 The
 140 .Fa count
 141 parameter points to an
 142 .Vt unsigned long
 143 or
 144 .Vt unsigned int
 145 variable.
 146 You should initialise this variable to be the number of directory entries for which
 147 you wish to get attributes.
 148 On return, this variable contains the number of directory entries whose attributes
 149 have been placed into the attribute buffer.
 150 This may be smaller than the number that you requested.
 151 .Pp
 152 .
 153 .\" basep parameter
 154 The
 155 .Fa basep
 156 parameter returns the offset of the last directory entry read, in a
 157 manner identical to
 158 .Xr getdirentries 2 .
 159 You can use this value to reset a directory iteration to a known position
 160 using
 161 .Xr lseek 2 .
 162 However, since the variable is too small to hold an
 163 .Vt off_t ,
 164 you should use
 165 .Xr lseek 2
 166 to get the directory's current position instead of using this parameter.
 167 The initial value of the variable is ignored.
 168 .Pp
 169 .
 170 .\" newState parameter
 171 .
 172 The
 173 .Fa newState
 174 parameter returns a value that changes if the directory has been modified.
 175 If you're iterating through the directory by making repeated calls to
 176 .Fn getdirentriesattr ,
 177 you can compare subsequent values of
 178 .Fa newState
 179 to determine whether the directory has been modified (and thus restart
 180 your iteration at the beginning).
 181 The initial value of the variable is ignored.
 182 .Pp
 183 .
 184 .\" options parameter
 185 .
 186 The
 187 .Fa options
 188 parameter is a bit set that controls the behaviour of
 189 .Fn getdirentriesattr .
 190 The following option bits are defined.
 191 .
 192 .Bl -tag -width FSOPT_NOINMEMUPDATE
 193 .
 194 .It FSOPT_NOINMEMUPDATE
 195 This tells
 196 .Fn getdirentriesattr
 197 to return the directory entries from disk rather than taking the extra step of looking
 198 at data structures in-memory which may contain changes that haven't been flushed to disk.
 199 .Pp
 200 This option allowed for specific performance optimizations for specific clients on older systems.
 201 We currently recommend that clients not set this option and that file system
 202 implementations ignore it.
 203 .
 204 .El
 205 .Pp
 206 It is typical to ask for a combination of common, file, and directory
 207 attributes and then use the value of the
 208 .Dv ATTR_CMN_OBJTYPE
 209 attribute to parse the resulting attribute buffer.
 210 .
 211 .Sh RETURN VALUES
 212 Upon successful completion a value of 0 or 1 is returned.
 213 The value 0 indicates that the routine completed successfully.
 214 The value 1 indicates that the routine completed successfully and has
 215 returned the last entry in the directory.
 216 On error, a value of -1 is returned and
 217 .Va errno
 218 is set to indicate the error.
 219 .
 220 .Sh COMPATIBILITY
 221 Not all volumes support
 222 .Fn getdirentriesattr .
 223 You can test whether a volume supports
 224 .Fn getdirentriesattr
 225 by using
 226 .Xr getattrlist 2
 227 to get the volume capabilities attribute
 228 .Dv ATTR_VOL_CAPABILITIES ,
 229 and then testing the
 230 .Dv VOL_CAP_INT_READDIRATTR
 231 flag.
 232 .Pp
 233 .
 234 The
 235 .Fn getdirentriesattr
 236 function has been undocumented for more than two years.
 237 In that time a number of volume format implementations have been created without
 238 a proper specification for the behaviour of this routine.
 239 You may encounter volume format implementations with slightly different
 240 behaviour than what is described here.
 241 Your program is expected to be tolerant of this variant behaviour.
 242 .Pp
 243 .
 244 If you're implementing a volume format that supports
 245 .Fn getdirentriesattr ,
 246 you should be careful to support the behaviour specified by this document.
 247 .
 248 .Pp
 249 If the directory contains a mount point, then
 250 .Dv DIR_MNTSTATUS_MNTPOINT
 251 will be set in the
 252 .Dv ATTR_DIR_MOUNTSTATUS
 253 for that entry; all other attributes for that entry, however,
 254 will be for the underlying file system (as opposed to the mounted
 255 file system).
 256 .Xr getattrlist 2
 257 should be used to get the attributes for the mount point.
 258 .Sh ERRORS
 259 .Fn getdirentriesattr
 260 will fail if:
 261 .Bl -tag -width Er
 262 .
 263 .It Bq Er ENOTSUP
 264 The volume does not support
 265 .Fn getdirentriesattr .
 266 .
 267 .It Bq Er EBADF
 268 .Fa fd
 269 is not a valid file descriptor for a directory open for reading.
 270 .
 271 .It Bq Er EFAULT
 272 .Fa attrList
 273 or
 274 .Em attrBuf
 275 points to an invalid address.
 276 .
 277 .It Bq Er EINVAL
 278 The
 279 .Fa bitmapcount
 280 field of
 281 .Fa attrList
 282 is not
 283 .Dv ATTR_BIT_MAP_COUNT .
 284 .
 285 .It Bq Er EINVAL
 286 You requested an invalid attribute.
 287 .
 288 .It Bq Er EINVAL
 289 You requested volume attributes.
 290 .
 291 .It Bq Er EINVAL
 292 The
 293 .Fa options
 294 parameter contains an invalid flag.
 295 .
 296 .It Bq Er EIO
 297 An I/O error occurred while reading from or writing to the file system.
 298 .El
 299 .Pp
 300 .
 301 .Sh EXAMPLES
 302 .
 303 The following code lists the contents of a directory using
 304 .Fn getdirentriesattr .
 305 The listing includes the file type and creator for files.
 306 .
 307 .Bd -literal
 308 #include <assert.h>
 309 #include <stdio.h>
 310 #include <stddef.h>
 311 #include <string.h>
 312 #include <sys/attr.h>
 313 #include <sys/errno.h>
 314 #include <unistd.h>
 315 #include <sys/vnode.h>
 316 #include <stdbool.h>
 317 #include <fcntl.h>
 318 .Pp
 319 .
 320 typedef struct attrlist attrlist_t;
 321 .Pp
 322 .
 323 struct FInfoAttrBuf {
 324     u_int32_t       length;
 325     attrreference_t name;
 326     fsobj_type_t    objType;
 327     char            finderInfo[32];
 328     u_int32_t       dirStatus;
 329 } __attribute__((aligned(4), packed));
 330 typedef struct FInfoAttrBuf FInfoAttrBuf;
 331 .Pp
 332 .
 333 enum {
 334     kEntriesPerCall = 10
 335 };
 336 .Pp
 337 .
 338 static int FInfoDemo(const char *dirPath)
 339 {
 340     int             err;
 341     int             junk;
 342     int             dirFD;
 343     attrlist_t      attrList;
 344 #ifdef __LP64__
 345     unsigned int    index;
 346     unsigned int    count;
 347     unsigned int    junkBaseP;
 348     unsigned int    oldState;
 349     unsigned int    newState;
 350 #else
 351     unsigned long   index;
 352     unsigned long   count;
 353     unsigned long   junkBaseP;
 354     unsigned long   oldState;
 355     unsigned long   newState;
 356 #endif
 357     bool            oldStateValid;
 358     bool            done;
 359     FInfoAttrBuf *  thisEntry;
 360     char            attrBuf[kEntriesPerCall * (sizeof(FInfoAttrBuf) + 64)];
 361 .Pp
 362 .
 363     // attrBuf is big enough for kEntriesPerCall entries, assuming that
 364     // the average name length is less than 64.
 365 .Pp
 366 .
 367     memset(&attrList, 0, sizeof(attrList));
 368     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 369     attrList.commonattr  =    ATTR_CMN_NAME
 370                             | ATTR_CMN_OBJTYPE
 371                             | ATTR_CMN_FNDRINFO;
 372     attrList.dirattr     = ATTR_DIR_MOUNTSTATUS;
 373 .Pp
 374
 375     err = 0;
 376     dirFD = open(dirPath, O_RDONLY, 0);
 377     if (dirFD < 0) {
 378         err = errno;
 379     }
 380     if (err == 0) {
 381         oldStateValid = false;
 382         done = false;
 383         do {
 384             count = kEntriesPerCall;
 385 .Pp
 386             err = getdirentriesattr(
 387                 dirFD,
 388                 &attrList,
 389                 &attrBuf,
 390                 sizeof(attrBuf),
 391                 &count,
 392                 &junkBaseP,
 393                 &newState,
 394                 0
 395             );
 396             if (err < 0) {
 397                 err = errno;
 398             } else {
 399                 done = err;
 400                 err = 0;
 401             }
 402 .Pp
 403             if (err == 0) {
 404                 if (oldStateValid) {
 405                     if (newState != oldState) {
 406                         printf("*** Directory has changed\en");
 407                         oldState = newState;
 408                     }
 409                 } else {
 410                     oldState = newState;
 411                     oldStateValid = true;
 412                 }
 413 .Pp
 414                 thisEntry = (FInfoAttrBuf *) attrBuf;
 415 .Pp
 416                 for (index = 0; index < count; index++) {
 417                     switch (thisEntry->objType) {
 418                         case VREG:
 419                             printf(
 420                                 "'%4.4s' '%4.4s' ",
 421                                 &thisEntry->finderInfo[0],
 422                                 &thisEntry->finderInfo[4]
 423                             );
 424                             break;
 425                         case VDIR:
 426                             if (thisEntry->dirStatus & DIR_MNTSTATUS_MNTPOINT)
 427                                 printf("mount-point   ");
 428                             else
 429                                 printf("directory     ");
 430                             break;
 431                         default:
 432                             printf(
 433                                 "objType = %-2d  ",
 434                                 thisEntry->objType
 435                             );
 436                             break;
 437                     }
 438                     printf(
 439                         "%s\en",
 440                         ((char *) &thisEntry->name)
 441                             + thisEntry->name.attr_dataoffset
 442                     );
 443 .Pp
 444                     // Advance to the next entry.
 445 .Pp
 446                     thisEntry = (FInfoAttrBuf*)((char*)thisEntry + thisEntry->length);
 447                 }
 448             }
 449         } while ( err == 0 && ! done );
 450     }
 451 .Pp
 452     if (dirFD != -1) {
 453         junk = close(dirFD);
 454         assert(junk == 0);
 455     }
 456 .Pp
 457     return err;
 458 }
 459 .Ed
 460 .Pp
 461 .
 462 .Sh SEE ALSO
 463 .
 464 .Xr getattrlist 2 ,
 465 .Xr getdirentries 2 ,
 466 .Xr lseek 2
 467 .
 468 .Sh HISTORY
 469 A
 470 .Fn getdirentriesattr
 471 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 472 .