--- name: "searchfs" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/searchfs" --- # searchfs(2) search a volume quickly ## NAME **searchfs** – search a volume quickly ## SYNOPSIS **#include \** **#include \** *int*\ **searchfs**(*const char\* path*, *struct fssearchblock\* searchBlock*, *unsigned long\* numMatches*, *unsigned int scriptCode*, *unsigned int options*, *struct searchstate\* state*); ## DESCRIPTION The **searchfs**() function searches the volume (that is, mounted file system) specified by *path* for file system objects matching the criteria specified by *searchBlock*, *scriptCode*, and *options*. The *numMatches* parameter returns the number of matching file system objects found. The function also returns attributes of those file system objects in a buffer specified by *searchBlock*. The *searchState* parameter allows you search the volume using multiple calls to **searchfs**(), resuming the search where it left off. The routine will only return objects to which you have access (that is, you have execute permissions on the directories leading to this object from the root). The *path* parameter must reference a valid file system object on the volume to be searched. Typically the path is to the volume's root directory. The entire volume is always searched. All directories listed in the path name leading to this object must be searchable. The *searchBlock* parameter is a pointer to an *fssearchblock* structure, as defined by ⟨*sys/attr.h*⟩ (shown below). You are responsible for filling out all fields of this structure before calling the function. ``` struct fssearchblock { struct attrlist * returnattrs; void * returnbuffer; size_t returnbuffersize; unsigned int maxmatches; struct timeval timelimit; void * searchparams1; size_t sizeofsearchparams1; void * searchparams2; size_t sizeofsearchparams2; struct attrlist searchattrs; }; ``` For information about the *attrlist* structure, see the discussion of [getattrlist(2)](/getattrlist/2.md). The fields of the *fssearchblock* structure are defined as follows. - returnattrs **searchfs**() can return arbitrary attributes of the file system objects that meet the designated search criteria passed in via *searchparams1* and *searchparams2.* This field must point to an *attrlist* structure that specifies the attributes that you want returned. To request an attribute you must set the corresponding bit in the appropriate *attrgroup\_t* field of the *attrlist* structure. You are responsible for filling out all fields of this structure before calling the function. You must not request volume attributes. - returnbuffer **searchfs**() places attributes of the matching file system objects into this returned attributes buffer. The attributes for any given object are grouped together and packed in exactly the same way as they would be returned from getdirentriesattr(2). The initial contents of this buffer are ignored. - returnbuffersize Set this field to the size, in bytes, of the buffer pointed to by *returnbuffer*. - maxmatches Specifies the maximum number of matches that you want this call to **searchfs**() to return. - timelimit Specifies the maximum time that you want this call to **searchfs**() to run. If you're implementing a volume format, you should impose your own internal limit on the duration of this call to prevent a malicious user program from monopolizing kernel resources. - searchparams1 Specifies the lower bound of the search criteria. This is discussed in detail below. You must place attribute values into the buffer in the same way as they would be returned by [getattrlist(2)](/getattrlist/2.md), where the *searchattrs* field determines the exact layout of the attribute values. - sizeofsearchparams1 Set this field to the size, in bytes, of the buffer pointed to by *searchparams1*. - searchparams2 Specifies the upper bound of the search criteria. This is discussed in detail below. You must place attribute values into the buffer in the same way as they would be returned by [getattrlist(2)](/getattrlist/2.md), where the *searchattrs* field determines the exact layout of the attribute values. - sizeofsearchparams2 Set this field to the size, in bytes, of the buffer pointed to by *searchparams2*. - searchattrs Specifies the attributes that you want you use for your search criteria. You are responsible for filling out all fields of this structure before calling the function. To search for an attribute you must set the corresponding bit in the appropriate *attrgroup\_t* field of the *attrlist* structure, and place the appropriate values into the *searchparam1* and *searchparam2* buffers. The attributes specified here determine the format of those buffers. This is discussed in detail below. The *numMatches* parameter points to an *unsigned* *int* variable. The initial value of this variable is ignored. On return, this variable contains the number of matching file system objects found. The is always less than or equal to the *maxmatches* field of the *searchBlock* parameter. The attributes for the matching objects have been placed into the returned attributes buffer. The *scriptCode* parameter is currently ignored. You should always pass in the value 0x08000103, which corresponds to the UTF-8 text encoding value defined by ⟨*CarbonCore/TextCommon.h*⟩. The *options* parameter is a bit set that controls the behaviour of **searchfs**(). The following option bits are defined. - SRCHFS\_START If this bit is set, **searchfs**() will ignore the *state* parameter and start a new search. Otherwise **searchfs**() assumes that *searchstate* is valid and attempts to resume a previous search based on that state. - SRCHFS\_MATCHPARTIALNAMES If this bit is set, **searchfs**() will consider substrings to be successful matches when evaluating the ATTR\_CMN\_NAME attribute. - SRCHFS\_MATCHDIRS If this bit is set, **searchfs**() will search for directories that match the search criteria. To get meaningful results you must specify either this bit or SRCHFS\_MATCHFILES, or both. - SRCHFS\_MATCHFILES If this bit is set, **searchfs**() will search for files that match the search criteria. To get meaningful results you must specify either this bit or SRCHFS\_MATCHDIRS, or both. - SRCHFS\_SKIPLINKS If this bit is set, **searchfs**() will only return one reference for a hard linked file, rather than a reference for each hard link to the file. This option is not recommended for general development. Its primary client is the quotacheck(2) utility. Note that not all filesystems that support **searchfs**() support this option and may return EINVAL if it is requested. This option is privileged (the caller's effective UID must be 0) and cannot be used if you request the ATTR\_CMN\_NAME or ATTR\_CMN\_PAROBJID attributes. Introduced with Darwin 7.0 (Mac OS X version 10.3). - SRCHFS\_SKIPINVISIBLE If this bit is set, **searchfs**() will not match any invisible file system objects (that is, objects whose ATTR\_CMN\_FNDRINFO attribute has bit 6 set in the ninth byte) or any objects within invisible directories. Introduced with Darwin 7.0 (Mac OS X version 10.3). - SRCHFS\_SKIPPACKAGES If this bit is set, **searchfs**() will not match any file system objects that are inside a package. A package is defined as a directory whose extension matches one of the extensions that are configured into the kernel by Launch Services. Introduced with Darwin 7.0 (Mac OS X version 10.3). - SRCHFS\_SKIPINAPPROPRIATE If this bit is set, **searchfs**() will not match any file system objects that are within an inappropriate directory. The current list of inappropriate directories contains one item: /System. Introduced with Darwin 7.0 (Mac OS X version 10.3). - SRCHFS\_NEGATEPARAMS If this bit is set, **searchfs**() will return all the file system objects that do not match the search criteria. Introduced with Darwin 7.0 (Mac OS X version 10.3). - SRCHFS\_NOFOLLOW If this bit is set, **searchfs**() will not follow a symlink if it occurs as the last component of *path*. - SRCHFS\_NOFOLLOW\_ANY If this bit is set, **searchfs**() will not follow a symlink if it occurs as the last component of *path*. In addition an error is returned if a symlink is encountered before the last component of *path*. The *state* parameter is a pointer to an opaque data structure that **searchfs**() uses to maintain the state of a search between successive calls. In your first call to **searchfs**(), you specify the SRCHFS\_START flag in the *options* parameter. This tells **searchfs**() that the search state is invalid and that it should start a new search. When this call completes, it may have only returned partial results; in that case, it will have updated the structure pointed to by *state*. If you call **searchfs**() again, this time without specifying the SRCHFS\_START flag in the *options* parameter, it will resume the search where it left off, using the search state that it previously stored in the state structure. You do not need to explicitly dispose of this state. The **searchfs**() function returns significant errors in the followings cases. - If it has found as many objects as you requested in the *maxmatches* field of the *searchBlock* parameter, it will return EAGAIN. - If there is not enough space in the returned attributes buffer for the first match, it will return ENOBUFS. You should allocate a larger returned attributes buffer and try again. *numMatches* will be zero in this case. - If the timeout expires it will return EAGAIN. - If you attempt to resume a search (that is, SRCHFS\_START is not specified in the *options* parameter) and the catalog has changed since the last search, the function will return EBUSY. You must start your search again from the beginning. If **searchfs**() returns EAGAIN, the value in *numMatches* may be greater than zero. This is known as a partial result. You should be sure to process these matches before calling **searchfs**() again. ## SEARCH CRITERIA You specify the search criteria using a combination of the *searchattrs*, *searchparams1*, *sizeofsearchparams1,* *searchparams2*, and *sizeofsearchparams2* fields of the *searchBlock* parameter, and various flags in the *options* parameter. The *searchattrs* field determines the attributes considered when comparing a file system object to the search criteria. You can specify that an attribute should be considered by setting the corresponding bit in the appropriate *attrgroup\_t* field of the *attrlist* structure. See the discussion of [getattrlist(2)](/getattrlist/2.md) for a detailed description of this structure. The *searchparams1*, *sizeofsearchparams1*, *searchparams2*, and *sizeofsearchparams2* fields specify the attribute values that must be matched. The format of each of these buffers is determined by the attributes that you're searching for. The values are packed in exactly the same way as they would be returned from [getattrlist(2)](/getattrlist/2.md), including the leading *u\_int32\_t* length value. Note that the size of these buffers must be bounded by SEARCHFS\_MAX\_SEARCHPARMS bytes, which is defined in \. The attribute values in the first and second search buffers form a lower and upper bound for the search, respectively. These have different meanings depending on the type of attribute. - For string attributes (specifically ATTR\_CMN\_NAME, the object name), the value in the first search buffer is significant and the value in the second search buffer is ignored. The string comparison is either an exact match or a substring match depending on the SRCHFS\_MATCHPARTIALNAMES flag in the *options* parameter. - For structured attributes (specifically ATTR\_CMN\_FNDRINFO, the Finder information), the value from the file system object is masked (logical AND) with the value in the second search buffer and then compared, byte for byte, against the value in the first search buffer. If it is equal, the object is a match. - For scalar attributes (all other attributes, for example, ATTR\_CMN\_MODTIME, the modification date), the values in the first and second search buffers are literally a lower and upper bound. An object matches the criteria if its value is greater than or equal to the value in the first buffer and less than or equal to the value in the second. ## RETURN VALUES Upon successful completion, a value of 0 is returned. This means that the entire volume has been searched and all matches returned. Otherwise, a value of -1 is returned and *errno* is set to indicate the error. See the discussion of the EAGAIN, ENOBUFS, and EBUSY error codes above. ## COMPATIBILITY Not all volumes support **searchfs**(). You can test whether a volume supports **searchfs**() by using [getattrlist(2)](/getattrlist/2.md) to get the volume capabilities attribute ATTR\_VOL\_CAPABILITIES, and then testing the VOL\_CAP\_INT\_SEARCHFS flag. The **searchfs**() function has been undocumented for more than two years. In that time a number of volume format implementations have been created without a proper specification for the behaviour of this routine. You may encounter volume format implementations with slightly different behaviour than what is described here. Your program is expected to be tolerant of this variant behaviour. If you're implementing a volume format that supports **searchfs**(), you should be careful to support the behaviour specified by this document. A bug in systems prior to Darwin 7.0 (Mac OS X version 10.3) makes searching for the ATTR\_CMN\_BKUPTIME attribute tricky. The bug causes the attribute to consume two items in the search attribute buffers, the first in the proper place and the second between ATTR\_CMN\_FNDRINFO and ATTR\_CMN\_OWNERID. ## ERRORS **searchfs**() will fail if: - \[ENOTSUP\] The volume does not support **searchfs**(). - \[ENOTDIR\] A component of the path prefix is not a directory. - \[ENAMETOOLONG\] A component of a path name exceeded NAME\_MAX characters, or an entire path name exceeded PATH\_MAX characters. - \[ENOENT\] The file system object does not exist. - \[EACCES\] Search permission is denied for a component of the path prefix. - \[ELOOP\] Too many symbolic links were encountered in translating the pathname. - \[EFAULT\] One of the pointer parameters points to an invalid address. - \[EINVAL\] The *options* parameter contains an invalid flag or sizeofsearchparams1/2 is greater than SEARCHFS\_MAX\_SEARCHPARMS (see attr.h). Additionally, filesystems that do not support SRCHFS\_SKIPLINKS may return EINVAL if this search option is requested. EINVAL may also be returned if you request attributes for either searching or to be returned for matched entries if the filesystem does not support vending that particular attribute. - \[EAGAIN\] The search terminated with partial results, either because *numMatches* has hit the limit specified by *maxmatches* or because the timeout expired. Process the matches returned so far and then call **searchfs**() again to look for more. - \[ENOBUFS\] The returned attributes buffer is too small for the first match. You should allocate a larger returned attributes buffer and try again. *numMatches* will be zero in this case. - \[EBUSY\] The search could not be resumed because the volume has changed. - \[EIO\] An I/O error occurred while reading from or writing to the file system. ## CAVEATS The list of attributes valid for searching and returning to the caller may be substantially smaller than that of the [getattrlist(2)](/getattrlist/2.md) system call. See the following lists for the currently available search criteria. In general, a filesystem that supports **searchfs**() will typically supply per-item attributes for matched objects that are also supported by the [getdirentries(2)](/getdirentries/2.md) system call. This varies from filesystem to filesystem. ## SEARCH ATTRIBUTES The list of attributes that are valid as search criteria currently includes the following list of attributes for a particular filesystem object. - ATTR\_CMN\_NAME - ATTR\_CMN\_OBJID - ATTR\_CMN\_PAROBJID - ATTR\_CMN\_CRTIME - ATTR\_CMN\_MODTIME - ATTR\_CMN\_CHGTIME - ATTR\_CMN\_ACCTIME - ATTR\_CMN\_BKUPTIME - ATTR\_CMN\_FNDRINFO - ATTR\_CMN\_OWNERID - ATTR\_CMN\_GRPID - ATTR\_CMN\_ACCESSMASK - ATTR\_CMN\_FILEID - ATTR\_CMN\_PARENTID - ATTR\_DIR\_ENTRYCOUNT - ATTR\_FILE\_DATALENGTH - ATTR\_FILE\_DATAALLOCSIZE - ATTR\_FILE\_RSRCLENGTH - ATTR\_FILE\_RSRCALLOCSIZE ## RETURN ATTRIBUTES As mentioned above, the list of attributes that are available to be returned to the caller vary by filesystem, but should include the following attributes, in the following order. The buffer should be assumed to be packed similar to the output buffer of the [getattrlist(2)](/getattrlist/2.md) system call. Note that again, this list may be substantially smaller than what is available via [getattrlist(2)](/getattrlist/2.md) - ATTR\_CMN\_NAME - ATTR\_CMN\_DEVID - ATTR\_CMN\_FSID - ATTR\_CMN\_OBJTYPE - ATTR\_CMN\_OBJTAG - ATTR\_CMN\_OBJID - ATTR\_CMN\_OBJPERMANENTID - ATTR\_CMN\_PAROBJID - ATTR\_CMN\_SCRIPT - ATTR\_CMN\_CRTIME - ATTR\_CMN\_MODTIME - ATTR\_CMN\_CHGTIME - ATTR\_CMN\_ACCTIME - ATTR\_CMN\_BKUPTIME - ATTR\_CMN\_FNDRINFO - ATTR\_CMN\_OWNERID - ATTR\_CMN\_GRPID - ATTR\_CMN\_ACCESSMASK - ATTR\_CMN\_FLAGS - ATTR\_CMN\_USERACCESS - ATTR\_CMN\_FILEID - ATTR\_CMN\_PARENTID - ATTR\_DIR\_LINKCOUNT - ATTR\_DIR\_ENTRYCOUNT - ATTR\_DIR\_MOUNTSTATUS - ATTR\_FILE\_LINKCOUNT - ATTR\_FILE\_TOTALSIZE - ATTR\_FILE\_ALLOCSIZE - ATTR\_FILE\_IOBLOCKSIZE - ATTR\_FILE\_CLUMPSIZE - ATTR\_FILE\_DEVTYPE - ATTR\_FILE\_DATALENGTH - ATTR\_FILE\_DATAALLOCSIZE - ATTR\_FILE\_RSRCLENGTH - ATTR\_FILE\_RSRCALLOCSIZE ## EXAMPLES The following code searches a volume for files of the specified type and creator. ``` #include #include #include #include #include #include #include typedef struct attrlist attrlist_t; typedef struct fssearchblock fssearchblock_t; typedef struct searchstate searchstate_t; struct SearchAttrBuf { u_int32_t length; char finderInfo[32]; }; typedef struct SearchAttrBuf SearchAttrBuf; struct ResultAttrBuf { u_int32_t length; attrreference_t name; fsobj_id_t parObjID; }; typedef struct ResultAttrBuf ResultAttrBuf; enum { kMatchesPerCall = 16 }; static int SearchFSDemo( const char *volPath, const char *type, const char *creator ) { int err; fssearchblock_t searchBlock; SearchAttrBuf lower; SearchAttrBuf upper; static const unsigned char kAllOnes[4] = { 0xFF, 0xFF, 0xFF, 0xFF }; unsigned long matchCount; unsigned long matchIndex; unsigned int options; searchstate_t state; ResultAttrBuf * thisEntry; attrlist_t returnAttrList; char resultAttrBuf[ kMatchesPerCall * (sizeof(ResultAttrBuf) + 64)]; // resultAttrBuf is big enough for kMatchesPerCall entries, // assuming that the average name length is less than 64. assert(strlen(type) == 4); assert(strlen(creator) == 4); memset(&searchBlock, 0, sizeof(searchBlock)); searchBlock.searchattrs.bitmapcount = ATTR_BIT_MAP_COUNT; searchBlock.searchattrs.commonattr = ATTR_CMN_FNDRINFO; memset(&lower, 0, sizeof(lower)); memset(&upper, 0, sizeof(upper)); lower.length = sizeof(lower); upper.length = sizeof(upper); memcpy(&lower.finderInfo[0], type, 4); memcpy(&lower.finderInfo[4], creator, 4); memcpy(&upper.finderInfo[0], kAllOnes, 4); memcpy(&upper.finderInfo[4], kAllOnes, 4); searchBlock.searchparams1 = &lower; searchBlock.sizeofsearchparams1 = sizeof(lower); searchBlock.searchparams2 = &upper; searchBlock.sizeofsearchparams2 = sizeof(lower); searchBlock.timelimit.tv_sec = 0; searchBlock.timelimit.tv_usec = 100 * 1000; searchBlock.maxmatches = kMatchesPerCall; memset(&returnAttrList, 0, sizeof(returnAttrList)); returnAttrList.bitmapcount = ATTR_BIT_MAP_COUNT; returnAttrList.commonattr = ATTR_CMN_NAME | ATTR_CMN_PAROBJID; searchBlock.returnattrs = &returnAttrList; searchBlock.returnbuffer = resultAttrBuf; searchBlock.returnbuffersize = sizeof(resultAttrBuf); options = SRCHFS_START | SRCHFS_MATCHFILES; do { err = searchfs( volPath, &searchBlock, &matchCount, 0x08000103, options, &state ); if (err != 0) { err = errno; } if ( (err == 0) || (err == EAGAIN) ) { thisEntry = (ResultAttrBuf *) resultAttrBuf; for (matchIndex = 0; matchIndex < matchCount; matchIndex++) { printf("%08x ", thisEntry->parObjID.fid_objno); printf( "%s\n", ((char *) &thisEntry->name) + thisEntry->name.attr_dataoffset ); // Advance to the next entry. ((char *) thisEntry) += thisEntry->length; } } options &= ~SRCHFS_START; } while (err == EAGAIN); return err; } ``` ## SEE ALSO [getattrlist(2)](/getattrlist/2.md) ## HISTORY A **searchfs**() function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).