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