bsd/man/man2/searchfs.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 .\"     @(#)searchfs.2
  18 .
  19 .Dd October 13, 2008
  20 .Dt SEARCHFS 2
  21 .Os Darwin
  22 .Sh NAME
  23 .Nm searchfs
  24 .Nd search a volume quickly
  25 .Sh SYNOPSIS
  26 .Fd #include <sys/attr.h>
  27 .Fd #include <unistd.h>
  28 .Ft int
  29 .Fn searchfs "const char* path" "struct fssearchblock* searchBlock" "unsigned int* numMatches" "unsigned int scriptCode" "unsigned int options" "struct searchstate* state"
  30 .
  31 .Sh DESCRIPTION
  32 The
  33 .Fn searchfs
  34 function searches the volume (that is, mounted file system) specified by
  35 .Fa path
  36 for file system objects matching the criteria specified by
  37 .Fa searchBlock ,
  38 .Fa scriptCode ,
  39 and
  40 .Fa options .
  41 The
  42 .Fa numMatches
  43 parameter returns the number of matching file system objects found.
  44 The function also returns attributes of those file system objects in a buffer
  45 specified by
  46 .Fa searchBlock .
  47 The
  48 .Fa searchState
  49 parameter allows you search the volume using multiple calls to
  50 .Fn searchfs ,
  51 resuming the search where it left off.
  52 The routine will only return objects to which you have access (that is, you
  53 have execute permissions on the directories leading to this object from the root).
  54 .Pp
  55 .
  56 .\" path parameter
  57 .
  58 The
  59 .Fa path
  60 parameter must reference a valid file system object on the volume to be searched.
  61 Typically the path is to the volume's root directory.
  62 The entire volume is always searched.
  63 All directories listed in the path name leading to this object must be
  64 searchable.
  65 .Pp
  66 .
  67 .\" searchBlock parameter
  68 .
  69 The
  70 .Fa searchBlock
  71 parameter is a pointer to an
  72 .Vt fssearchblock
  73 structure, as defined by
  74 .Aq Pa sys/attr.h
  75 (shown below).
  76 You are responsible for filling out all fields of this structure before calling the function.
  77 .Bd -literal
  78 struct fssearchblock {
  79     struct attrlist *   returnattrs;
  80     void *              returnbuffer;
  81     size_t              returnbuffersize;
  82     unsigned int        maxmatches;
  83     struct timeval      timelimit;
  84     void *              searchparams1;
  85     size_t              sizeofsearchparams1;
  86     void *              searchparams2;
  87     size_t              sizeofsearchparams2;
  88     struct attrlist     searchattrs;
  89 };
  90 .Ed
  91 .Pp
  92 .
  93 For information about the
  94 .Vt attrlist
  95 structure, see the discussion of
  96 .Xr getattrlist 2 .
  97 .Pp
  98 .
  99 .\" searchBlock elements
 100 .
 101 The fields of the
 102 .Vt fssearchblock
 103 structure are defined as follows.
 104 .Bl -tag -width sizeofsearchparams1
 105 .
 106 .It returnattrs
 107 .Fn searchfs
 108 can return arbitrary attributes of the file system objects that meet the designated
 109 search criteria passed in via
 110 .Vt searchparams1
 111 and
 112 .Vt searchparams2.
 113 This field must point to an
 114 .Vt attrlist
 115 structure that specifies the attributes that you want returned.
 116 To request an attribute you must set the corresponding bit in the appropriate
 117 .Vt attrgroup_t
 118 field of the
 119 .Vt attrlist
 120 structure.
 121 You are responsible for filling out all fields of this structure before calling the function.
 122 You must not request volume attributes.
 123 .
 124 .It returnbuffer
 125 .Fn searchfs
 126 places attributes of the matching file system objects into this returned attributes buffer.
 127 The attributes for any given object are grouped together and
 128 packed in exactly the same way as they would be returned from
 129 .Xr getdirentriesattr 2 .
 130 The initial contents of this buffer are ignored.
 131 .
 132 .It returnbuffersize
 133 Set this field to the size, in bytes, of the buffer pointed to by
 134 .Fa returnbuffer .
 135 .
 136 .It maxmatches
 137 Specifies the maximum number of matches that you want this call to
 138 .Fn searchfs
 139 to return.
 140 .
 141 .It timelimit
 142 Specifies the maximum time that you want this call to
 143 .Fn searchfs
 144 to run.
 145 .Pp
 146 .
 147 If you're implementing a volume format, you should impose your own internal
 148 limit on the duration of this call to prevent a malicious user program
 149 from monopolizing kernel resources.
 150 .Pp
 151 .
 152 .It searchparams1
 153 Specifies the lower bound of the search criteria.
 154 This is discussed in detail below.
 155 You must place attribute values into the buffer in the same
 156 way as they would be returned by
 157 .Xr getattrlist 2 ,
 158 where the
 159 .Fa searchattrs
 160 field determines the exact layout of the attribute values.
 161 .
 162 .It sizeofsearchparams1
 163 Set this field to the size, in bytes, of the buffer pointed to by
 164 .Fa searchparams1 .
 165 .
 166 .It searchparams2
 167 Specifies the upper bound of the search criteria.
 168 This is discussed in detail below.
 169 You must place attribute values into the buffer in the same
 170 way as they would be returned by
 171 .Xr getattrlist 2 ,
 172 where the
 173 .Fa searchattrs
 174 field determines the exact layout of the attribute values.
 175 .
 176 .It sizeofsearchparams2
 177 Set this field to the size, in bytes, of the buffer pointed to by
 178 .Fa searchparams2 .
 179 .
 180 .It searchattrs
 181 Specifies the attributes that you want you use for your search criteria.
 182 You are responsible for filling out all fields of this structure before calling the function.
 183 To search for an attribute you must set the corresponding bit in the appropriate
 184 .Vt attrgroup_t
 185 field of the
 186 .Vt attrlist
 187 structure, and place the appropriate values into the
 188 .Fa searchparam1
 189 and
 190 .Fa searchparam2
 191 buffers.
 192 The attributes specified here determine the format of those buffers.
 193 This is discussed in detail below.
 194 .
 195 .El
 196 .Pp
 197 .
 198 .\" numMatches parameter
 199 .
 200 The
 201 .Fa numMatches
 202 parameter points to an
 203 .Vt unsigned int
 204 variable.
 205 The initial value of this variable is ignored.
 206 On return, this variable contains the number of matching file system objects found.
 207 The is always less than or equal to the
 208 .Fa maxmatches
 209 field of the
 210 .Fa searchBlock
 211 parameter.
 212 The attributes for the matching objects have been placed into the returned attributes buffer.
 213 .Pp
 214 .
 215 .\" scriptCode parameter
 216 .
 217 The
 218 .Fa scriptCode
 219 parameter is currently ignored.
 220 You should always pass in the value 0x08000103, which corresponds to the
 221 UTF-8 text encoding value defined by
 222 .Aq Pa CarbonCore/TextCommon.h .
 223 .Pp
 224 .
 225 .\" options parameter
 226 .
 227 The
 228 .Fa options
 229 parameter is a bit set that controls the behaviour of
 230 .Fn searchfs .
 231 The following option bits are defined.
 232 .
 233 .Bl -tag -width SRCHFS_MATCHPARTIALNAMES
 234 .
 235 .It SRCHFS_START
 236 If this bit is set,
 237 .Fn searchfs
 238 will ignore the
 239 .Fa state
 240 parameter and start a new search.
 241 Otherwise
 242 .Fn searchfs
 243 assumes that
 244 .Fa searchstate
 245 is valid and attempts to resume a previous search based on that state.
 246 .
 247 .It SRCHFS_MATCHPARTIALNAMES
 248 If this bit is set,
 249 .Fn searchfs
 250 will consider substrings to be successful matches when evaluating the
 251 .Dv ATTR_CMN_NAME
 252 attribute.
 253 .
 254 .It SRCHFS_MATCHDIRS
 255 If this bit is set,
 256 .Fn searchfs
 257 will search for directories that match the search criteria.
 258 To get meaningful results you must specify either this bit or
 259 .Dv SRCHFS_MATCHFILES ,
 260 or both.
 261 .
 262 .It SRCHFS_MATCHFILES
 263 If this bit is set,
 264 .Fn searchfs
 265 will search for files that match the search criteria.
 266 To get meaningful results you must specify either this bit or
 267 .Dv SRCHFS_MATCHDIRS ,
 268 or both.
 269 .
 270 .It SRCHFS_SKIPLINKS
 271 If this bit is set,
 272 .Fn searchfs
 273 will only return one reference for a hard linked file, rather than a reference
 274 for each hard link to the file.
 275 .Pp
 276 This option is not recommended for general development.
 277 Its primary client is the
 278 .Xr quotacheck 2
 279 utility.  Note that not all filesystems that support
 280 .Fn searchfs
 281 support this option and may return EINVAL if it is requested.
 282 .Pp
 283 .
 284 This option is privileged (the caller's effective UID must be 0) and cannot
 285 be used if you request the
 286 .Dv ATTR_CMN_NAME
 287 or
 288 .Dv ATTR_CMN_PAROBJID
 289 attributes.
 290 .Pp
 291 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 292 .
 293 .It SRCHFS_SKIPINVISIBLE
 294 If this bit is set,
 295 .Fn searchfs
 296 will not match any invisible file system objects (that is, objects whose
 297 .Dv ATTR_CMN_FNDRINFO
 298 attribute has bit 6 set in the ninth byte) or any objects within
 299 invisible directories.
 300 .Pp
 301 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 302 .
 303 .It SRCHFS_SKIPPACKAGES
 304 If this bit is set,
 305 .Fn searchfs
 306 will not match any file system objects that are inside a package.
 307 A package is defined as a directory whose extension matches one
 308 of the extensions that are configured into the kernel by Launch Services.
 309 .Pp
 310 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 311 .
 312 .It SRCHFS_SKIPINAPPROPRIATE
 313 If this bit is set,
 314 .Fn searchfs
 315 will not match any file system objects that are within an inappropriate directory.
 316 The current list of inappropriate directories contains one item: /System.
 317 .Pp
 318 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 319 .
 320 .It SRCHFS_NEGATEPARAMS
 321 If this bit is set,
 322 .Fn searchfs
 323 will return all the file system objects that do not match the search criteria.
 324 .Pp
 325 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 326 .
 327 .El
 328 .Pp
 329 .
 330 .\" state parameter
 331 .
 332 The
 333 .Fa state
 334 parameter is a pointer to an opaque data structure that
 335 .Fn searchfs
 336 uses to maintain the state of a search between successive calls.
 337 In your first call to
 338 .Fn searchfs ,
 339 you specify the
 340 .Dv SRCHFS_START
 341 flag in the
 342 .Fa options
 343 parameter.
 344 This tells
 345 .Fn searchfs
 346 that the search state is invalid and that it should start a new search.
 347 When this call completes, it may have only returned partial results;
 348 in that case, it will have updated the structure pointed to by
 349 .Fa state .
 350 If you call
 351 .Fn searchfs
 352 again, this time without specifying the
 353 .Dv SRCHFS_START
 354 flag in the
 355 .Fa options
 356 parameter, it will resume the search where it left off, using the search state
 357 that it previously stored in the state structure.
 358 You do not need to explicitly dispose of this state.
 359 .Pp
 360 .
 361 The
 362 .Fn searchfs
 363 function returns significant errors in the followings cases.
 364 .
 365 .Bl -bullet
 366 .
 367 .It
 368 If it has found as many objects as you requested in the
 369 .Fa maxmatches
 370 field of the
 371 .Fa searchBlock
 372 parameter, it will return
 373 .Dv EAGAIN .
 374 .
 375 .It
 376 If there is not enough space in the returned attributes buffer for the first match,
 377 it will return
 378 .Dv ENOBUFS .
 379 You should allocate a larger returned attributes buffer and try again.
 380 .Fa numMatches
 381 will be zero in this case.
 382 .
 383 .It
 384 If the timeout expires it will return
 385 .Dv EAGAIN .
 386 .
 387 .It
 388 If you attempt to resume a search (that is,
 389 .Dv SRCHFS_START
 390 is not specified in the
 391 .Fa options
 392 parameter) and the catalog has changed since the last search,
 393 the function will return
 394 .Dv EBUSY .
 395 You must start your search again from the beginning.
 396 .
 397 .El
 398 .Pp
 399 .
 400 If
 401 .Fn searchfs
 402 returns
 403 .Dv EAGAIN ,
 404 the value in
 405 .Fa numMatches
 406 may be greater than zero.
 407 This is known as a partial result.
 408 You should be sure to process these matches before calling
 409 .Fn searchfs
 410 again.
 411 .
 412 .Sh SEARCH CRITERIA
 413 .
 414 You specify the search criteria using a combination of the
 415 .Fa searchattrs ,
 416 .Fa searchparams1 ,
 417 .Fa sizeofsearchparams1,
 418 .Fa searchparams2 ,
 419 and
 420 .Fa sizeofsearchparams2
 421 fields of the
 422 .Fa searchBlock
 423 parameter, and various flags in the
 424 .Fa options
 425 parameter.
 426 The
 427 .Fa searchattrs
 428 field determines the attributes considered when comparing a file system object to
 429 the search criteria.
 430 You can specify that an attribute should be considered by setting the corresponding
 431 bit in the appropriate
 432 .Vt attrgroup_t
 433 field of the
 434 .Vt attrlist
 435 structure.
 436 See the discussion of
 437 .Xr getattrlist 2
 438 for a detailed description of this structure.
 439 .Pp
 440 .
 441 The
 442 .Fa searchparams1 ,
 443 .Fa sizeofsearchparams1 ,
 444 .Fa searchparams2 ,
 445 and
 446 .Fa sizeofsearchparams2
 447 fields specify the attribute values that must be matched.
 448 The format of each of these buffers is determined by the attributes that you're searching for.
 449 The values are packed in exactly the same way as they would be returned from
 450 .Xr getattrlist 2 ,
 451 including the leading
 452 .Vt u_int32_t
 453 length value.  Note that the size of these buffers must be bounded by SEARCHFS_MAX_SEARCHPARMS bytes,
 454 which is defined in <sys/attr.h>.
 455 .Pp
 456 .
 457 The attribute values in the first and second search buffers form a lower and upper bound for
 458 the search, respectively.
 459 These have different meanings depending on the type of attribute.
 460 .
 461 .Bl -bullet
 462 .
 463 .It
 464 For string attributes (specifically
 465 .Dv ATTR_CMN_NAME ,
 466 the object name), the value in the first search
 467 buffer is significant and the value in the second search buffer is ignored.
 468 The string comparison is either an exact match or a substring match depending on
 469 the
 470 .Dv SRCHFS_MATCHPARTIALNAMES
 471 flag in the
 472 .Fa options
 473 parameter.
 474 .
 475 .It
 476 For structured attributes (specifically
 477 .Dv ATTR_CMN_FNDRINFO ,
 478 the Finder information), the value from the
 479 file system object is masked (logical AND) with the value in the second search buffer and then
 480 compared, byte for byte, against the value in the first search buffer.
 481 If it is equal, the object is a match.
 482 .
 483 .It
 484 For scalar attributes (all other attributes, for example,
 485 .Dv ATTR_CMN_MODTIME ,
 486 the modification date), the values in the first and second search
 487 buffers are literally a lower and upper bound.
 488 An object matches the criteria if its value is greater than or equal to the value in
 489 the first buffer and less than or equal to the value in the second.
 490 .
 491 .El
 492 .
 493 .Sh RETURN VALUES
 494 Upon successful completion, a value of 0 is returned.
 495 This means that the entire volume has been searched and all matches returned.
 496 Otherwise, a value of -1 is returned and
 497 .Va errno
 498 is set to indicate the error.
 499 .Pp
 500 .
 501 See the discussion of the
 502 .Dv EAGAIN ,
 503 .Dv ENOBUFS ,
 504 and
 505 .Dv EBUSY
 506 error codes above.
 507 .
 508 .Sh COMPATIBILITY
 509 Not all volumes support
 510 .Fn searchfs .
 511 You can test whether a volume supports
 512 .Fn searchfs
 513 by using
 514 .Xr getattrlist 2
 515 to get the volume capabilities attribute
 516 .Dv ATTR_VOL_CAPABILITIES ,
 517 and then testing the
 518 .Dv VOL_CAP_INT_SEARCHFS
 519 flag.
 520 .Pp
 521 .
 522 The
 523 .Fn searchfs
 524 function has been undocumented for more than two years.
 525 In that time a number of volume format implementations have been created without
 526 a proper specification for the behaviour of this routine.
 527 You may encounter volume format implementations with slightly different
 528 behaviour than what is described here.
 529 Your program is expected to be tolerant of this variant behaviour.
 530 .Pp
 531 .
 532 If you're implementing a volume format that supports
 533 .Fn searchfs ,
 534 you should be careful to support the behaviour specified by this document.
 535 .Pp
 536 .
 537 A bug in systems prior to Darwin 7.0 (Mac OS X version 10.3) makes searching for the
 538 .Dv ATTR_CMN_BKUPTIME
 539 attribute tricky.
 540 The bug causes the attribute to consume two items in the search attribute buffers, the
 541 first in the proper place and the second between
 542 .Dv ATTR_CMN_FNDRINFO
 543 and
 544 .Dv ATTR_CMN_OWNERID .
 545 .
 546 .Sh ERRORS
 547 .Fn searchfs
 548 will fail if:
 549 .Bl -tag -width Er
 550 .
 551 .It Bq Er ENOTSUP
 552 The volume does not support
 553 .Fn searchfs .
 554 .
 555 .It Bq Er ENOTDIR
 556 A component of the path prefix is not a directory.
 557 .
 558 .It Bq Er ENAMETOOLONG
 559 A component of a path name exceeded
 560 .Dv NAME_MAX
 561 characters, or an entire path name exceeded
 562 .Dv PATH_MAX
 563 characters.
 564 .
 565 .It Bq Er ENOENT
 566 The file system object does not exist.
 567 .
 568 .It Bq Er EACCES
 569 Search permission is denied for a component of the path prefix.
 570 .
 571 .It Bq Er ELOOP
 572 Too many symbolic links were encountered in translating the pathname.
 573 .
 574 .It Bq Er EFAULT
 575 One of the pointer parameters points to an invalid address.
 576 .
 577 .It Bq Er EINVAL
 578 The
 579 .Fa options
 580 parameter contains an invalid flag or sizeofsearchparams1/2 is greater than
 581 SEARCHFS_MAX_SEARCHPARMS (see attr.h).  Additionally, filesystems that do
 582 not support SRCHFS_SKIPLINKS may return EINVAL if this search option
 583 is requested.
 584 .
 585 .It Bq Er EAGAIN
 586 The search terminated with partial results, either because
 587 .Fa numMatches
 588 has hit the limit specified by
 589 .Fa maxmatches
 590 or because the timeout expired.
 591 Process the matches returned so far and then call
 592 .Fn searchfs
 593 again to look for more.
 594 .Pp
 595 .
 596 .It Bq Er ENOBUFS
 597 The returned attributes buffer is too small for the first match.
 598 You should allocate a larger returned attributes buffer and try again.
 599 .Fa numMatches
 600 will be zero in this case.
 601 .
 602 .It Bq Er EBUSY
 603 The search could not be resumed because the volume has changed.
 604 .
 605 .It Bq Er EIO
 606 An I/O error occurred while reading from or writing to the file system.
 607 .El
 608 .Pp
 609 .
 610 .Sh CAVEATS
 611 The list of searchable attributes currently includes:
 612 .Pp
 613 .
 614 .Bl -item -compact
 615 .It
 616 ATTR_CMN_NAME
 617 .It
 618 ATTR_CMN_OBJID
 619 .It
 620 ATTR_CMN_PAROBJID
 621 .It
 622 ATTR_CMN_CRTIME
 623 .It
 624 ATTR_CMN_MODTIME
 625 .It
 626 ATTR_CMN_CHGTIME
 627 .It
 628 ATTR_CMN_ACCTIME
 629 .It
 630 ATTR_CMN_BKUPTIME
 631 .It
 632 ATTR_CMN_FNDRINFO
 633 .It
 634 ATTR_CMN_BKUPTIME
 635 .It
 636 ATTR_CMN_OWNERID
 637 .It
 638 ATTR_CMN_GRPID
 639 .It
 640 ATTR_CMN_ACCESSMASK
 641 .It
 642 ATTR_CMN_FILEID
 643 .It
 644 ATTR_CMN_PARENTID
 645 .Pp
 646 .
 647 .It
 648 ATTR_DIR_ENTRYCOUNT
 649 .Pp
 650 .
 651 .It
 652 ATTR_FILE_DATALENGTH
 653 .It
 654 ATTR_FILE_DATAALLOCSIZE
 655 .It
 656 ATTR_FILE_RSRCLENGTH
 657 .It
 658 ATTR_FILE_RSRCALLOCSIZE
 659 .El
 660 .
 661 .Sh EXAMPLES
 662 .
 663 The following code searches a volume for files of the specified type and creator.
 664 .
 665 .Bd -literal
 666 #include <assert.h>
 667 #include <stdio.h>
 668 #include <stddef.h>
 669 #include <string.h>
 670 #include <sys/attr.h>
 671 #include <sys/errno.h>
 672 #include <unistd.h>
 673 .Pp
 674 .
 675 typedef struct attrlist         attrlist_t;
 676 typedef struct fssearchblock    fssearchblock_t;
 677 typedef struct searchstate      searchstate_t;
 678 .Pp
 679 .
 680 struct SearchAttrBuf {
 681     u_int32_t       length;
 682     char            finderInfo[32];
 683 };
 684 typedef struct SearchAttrBuf SearchAttrBuf;
 685 .Pp
 686 .
 687 struct ResultAttrBuf {
 688     u_int32_t       length;
 689     attrreference_t name;
 690     fsobj_id_t      parObjID;
 691 };
 692 typedef struct ResultAttrBuf ResultAttrBuf;
 693 .Pp
 694 .
 695 enum {
 696     kMatchesPerCall = 16
 697 };
 698 .Pp
 699 .
 700 static int SearchFSDemo(
 701     const char *volPath,
 702     const char *type,
 703     const char *creator
 704 )
 705 {
 706     int             err;
 707     fssearchblock_t searchBlock;
 708     SearchAttrBuf   lower;
 709     SearchAttrBuf   upper;
 710     static const unsigned char kAllOnes[4] = { 0xFF, 0xFF, 0xFF, 0xFF };
 711     unsigned int    matchCount;
 712     unsigned int    matchIndex;
 713     unsigned int    options;
 714     searchstate_t   state;
 715     ResultAttrBuf * thisEntry;
 716     attrlist_t      returnAttrList;
 717     char            resultAttrBuf[  kMatchesPerCall
 718                                   * (sizeof(ResultAttrBuf) + 64)];
 719 .Pp
 720 .
 721     // resultAttrBuf is big enough for kMatchesPerCall entries,
 722     // assuming that the average name length is less than 64.
 723 .Pp
 724 .
 725     assert(strlen(type)    == 4);
 726     assert(strlen(creator) == 4);
 727 .Pp
 728
 729     memset(&searchBlock, 0, sizeof(searchBlock));
 730     searchBlock.searchattrs.bitmapcount = ATTR_BIT_MAP_COUNT;
 731     searchBlock.searchattrs.commonattr  = ATTR_CMN_FNDRINFO;
 732 .Pp
 733
 734     memset(&lower, 0, sizeof(lower));
 735     memset(&upper, 0, sizeof(upper));
 736     lower.length = sizeof(lower);
 737     upper.length = sizeof(upper);
 738     memcpy(&lower.finderInfo[0], type,     4);
 739     memcpy(&lower.finderInfo[4], creator,  4);
 740     memcpy(&upper.finderInfo[0], kAllOnes, 4);
 741     memcpy(&upper.finderInfo[4], kAllOnes, 4);
 742     searchBlock.searchparams1       = &lower;
 743     searchBlock.sizeofsearchparams1 = sizeof(lower);
 744     searchBlock.searchparams2       = &upper;
 745     searchBlock.sizeofsearchparams2 = sizeof(lower);
 746 .Pp
 747
 748     searchBlock.timelimit.tv_sec  = 0;
 749     searchBlock.timelimit.tv_usec = 100 * 1000;
 750 .Pp
 751
 752     searchBlock.maxmatches = kMatchesPerCall;
 753 .Pp
 754
 755     memset(&returnAttrList, 0, sizeof(returnAttrList));
 756     returnAttrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 757     returnAttrList.commonattr  = ATTR_CMN_NAME | ATTR_CMN_PAROBJID;
 758 .Pp
 759 .
 760     searchBlock.returnattrs = &returnAttrList;
 761     searchBlock.returnbuffer = resultAttrBuf;
 762     searchBlock.returnbuffersize = sizeof(resultAttrBuf);
 763 .Pp
 764
 765     options = SRCHFS_START | SRCHFS_MATCHFILES;
 766 .Pp
 767
 768     do {
 769         err = searchfs(
 770             volPath,
 771             &searchBlock,
 772             &matchCount,
 773             0x08000103,
 774             options,
 775             &state
 776         );
 777         if (err != 0) {
 778             err = errno;
 779         }
 780         if ( (err == 0) || (err == EAGAIN) ) {
 781             thisEntry = (ResultAttrBuf *) resultAttrBuf;
 782 .Pp
 783
 784             for (matchIndex = 0; matchIndex < matchCount; matchIndex++) {
 785                 printf("%08x ", thisEntry->parObjID.fid_objno);
 786                 printf(
 787                     "%s\en",
 788                     ((char *) &thisEntry->name)
 789                         + thisEntry->name.attr_dataoffset
 790                 );
 791 .
 792                 // Advance to the next entry.
 793 .
 794                 ((char *) thisEntry) += thisEntry->length;
 795             }
 796         }
 797 .Pp
 798
 799         options &= ~SRCHFS_START;
 800     } while (err == EAGAIN);
 801 .Pp
 802
 803     return err;
 804 }
 805 .Ed
 806 .
 807 .Sh SEE ALSO
 808 .
 809 .Xr getattrlist 2
 810 .
 811 .Sh HISTORY
 812 A
 813 .Fn searchfs
 814 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 815 .