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 directoy'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 .Sh ERRORS
 249 .Fn getdirentriesattr
 250 will fail if:
 251 .Bl -tag -width Er
 252 .
 253 .It Bq Er ENOTSUP
 254 The volume does not support
 255 .Fn getdirentriesattr .
 256 .
 257 .It Bq Er EBADF
 258 .Fa fd
 259 is not a valid file descriptor for a directory open for reading.
 260 .
 261 .It Bq Er EFAULT
 262 .Fa attrList
 263 or
 264 .Em attrBuf
 265 points to an invalid address.
 266 .
 267 .It Bq Er EINVAL
 268 The
 269 .Fa bitmapcount
 270 field of
 271 .Fa attrList
 272 is not
 273 .Dv ATTR_BIT_MAP_COUNT .
 274 .
 275 .It Bq Er EINVAL
 276 You requested an invalid attribute.
 277 .
 278 .It Bq Er EINVAL
 279 You requested volume attributes.
 280 .
 281 .It Bq Er EINVAL
 282 The
 283 .Fa options
 284 parameter contains an invalid flag.
 285 .
 286 .It Bq Er EIO
 287 An I/O error occurred while reading from or writing to the file system.
 288 .El
 289 .Pp
 290 .
 291 .Sh EXAMPLES
 292 .
 293 The following code lists the contents of a directory using
 294 .Fn getdirentriesattr .
 295 The listing includes the file type and creator for files.
 296 .
 297 .Bd -literal
 298 #include <assert.h>
 299 #include <stdio.h>
 300 #include <stddef.h>
 301 #include <string.h>
 302 #include <sys/attr.h>
 303 #include <sys/errno.h>
 304 #include <unistd.h>
 305 #include <sys/vnode.h>
 306 #include <stdbool.h>
 307 #include <fcntl.h>
 308 .Pp
 309 .
 310 typedef struct attrlist attrlist_t;
 311 .Pp
 312 .
 313 struct FInfoAttrBuf {
 314     u_int32_t       length;
 315     attrreference_t name;
 316     fsobj_type_t    objType;
 317     char            finderInfo[32];
 318 };
 319 typedef struct FInfoAttrBuf FInfoAttrBuf;
 320 .Pp
 321 .
 322 enum {
 323     kEntriesPerCall = 10
 324 };
 325 .Pp
 326 .
 327 static int FInfoDemo(const char *dirPath)
 328 {
 329     int             err;
 330     int             junk;
 331     int             dirFD;
 332     attrlist_t      attrList;
 333 #ifdef __LP64__
 334     unsigned int    index;
 335     unsigned int    count;
 336     unsigned int    junkBaseP;
 337     unsigned int    oldState;
 338     unsigned int    newState;
 339 #else
 340     unsigned long   index;
 341     unsigned long   count;
 342     unsigned long   junkBaseP;
 343     unsigned long   oldState;
 344     unsigned long   newState;
 345 #endif
 346     bool            oldStateValid;
 347     bool            done;
 348     FInfoAttrBuf *  thisEntry;
 349     char            attrBuf[kEntriesPerCall * (sizeof(FInfoAttrBuf) + 64)];
 350 .Pp
 351 .
 352     // attrBuf is big enough for kEntriesPerCall entries, assuming that
 353     // the average name length is less than 64.
 354 .Pp
 355 .
 356     memset(&attrList, 0, sizeof(attrList));
 357     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 358     attrList.commonattr  =    ATTR_CMN_NAME
 359                             | ATTR_CMN_OBJTYPE
 360                             | ATTR_CMN_FNDRINFO;
 361 .Pp
 362
 363     err = 0;
 364     dirFD = open(dirPath, O_RDONLY, 0);
 365     if (dirFD < 0) {
 366         err = errno;
 367     }
 368     if (err == 0) {
 369         oldStateValid = false;
 370         done = false;
 371         do {
 372             count = kEntriesPerCall;
 373 .Pp
 374             err = getdirentriesattr(
 375                 dirFD,
 376                 &attrList,
 377                 &attrBuf,
 378                 sizeof(attrBuf),
 379                 &count,
 380                 &junkBaseP,
 381                 &newState,
 382                 0
 383             );
 384             if (err < 0) {
 385                 err = errno;
 386             } else {
 387                 done = err;
 388                 err = 0;
 389             }
 390 .Pp
 391             if (err == 0) {
 392                 if (oldStateValid) {
 393                     if (newState != oldState) {
 394                         printf("*** Directory has changed\en");
 395                         oldState = newState;
 396                     }
 397                 } else {
 398                     oldState = newState;
 399                     oldStateValid = true;
 400                 }
 401 .Pp
 402                 thisEntry = (FInfoAttrBuf *) attrBuf;
 403 .Pp
 404                 for (index = 0; index < count; index++) {
 405                     switch (thisEntry->objType) {
 406                         case VREG:
 407                             printf(
 408                                 "'%4.4s' '%4.4s' ",
 409                                 &thisEntry->finderInfo[0],
 410                                 &thisEntry->finderInfo[4]
 411                             );
 412                             break;
 413                         case VDIR:
 414                             printf("directory     ");
 415                             break;
 416                         default:
 417                             printf(
 418                                 "objType = %-2d  ",
 419                                 thisEntry->objType
 420                             );
 421                             break;
 422                     }
 423                     printf(
 424                         "%s\en",
 425                         ((char *) &thisEntry->name)
 426                             + thisEntry->name.attr_dataoffset
 427                     );
 428 .Pp
 429                     // Advance to the next entry.
 430 .Pp
 431                     ((char *) thisEntry) += thisEntry->length;
 432                 }
 433             }
 434         } while ( err == 0 && ! done );
 435     }
 436 .Pp
 437     if (dirFD != -1) {
 438         junk = close(dirFD);
 439         assert(junk == 0);
 440     }
 441 .Pp
 442     return err;
 443 }
 444 .Ed
 445 .Pp
 446 .
 447 .Sh SEE ALSO
 448 .
 449 .Xr getattrlist 2 ,
 450 .Xr getdirentries 2 ,
 451 .Xr lseek 2
 452 .
 453 .Sh HISTORY
 454 A
 455 .Fn getdirentriesattr
 456 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 457 .