SEARCHFS(2) | System Calls Manual | SEARCHFS(2) |
searchfs
— search
a volume quickly
#include
<sys/attr.h>
#include <unistd.h>
int
searchfs
(const
char* path, struct
fssearchblock* searchBlock,
unsigned long*
numMatches, unsigned int
scriptCode, unsigned int
options, struct
searchstate* state);
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).
The fields of the fssearchblock structure are defined as follows.
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.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.searchfs
() to return.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.
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.
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.searchfs
() will consider
substrings to be successful matches when evaluating the
ATTR_CMN_NAME
attribute.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.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.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).
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).
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).
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).
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).
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.
EAGAIN
.ENOBUFS
. You should
allocate a larger returned attributes buffer and try again.
numMatches will be zero in this case.EAGAIN
.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.
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) 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), 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 <sys/attr.h>.
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.
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.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.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.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.
Not all volumes support searchfs
(). You
can test whether a volume supports searchfs
() by
using getattrlist(2) 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
.
searchfs
() will fail if:
ENOTSUP
]searchfs
().ENOTDIR
]ENAMETOOLONG
]NAME_MAX
characters, or an entire path name exceeded
PATH_MAX
characters.ENOENT
]EACCES
]ELOOP
]EFAULT
]EINVAL
]EAGAIN
]searchfs
() again to look for more.ENOBUFS
]EBUSY
]EIO
]The list of attributes valid for searching and returning to the
caller may be substantially smaller than that of the
getattrlist(2) 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) system call. This varies from filesystem
to filesystem.
The list of attributes that are valid as search criteria currently includes the following list of attributes for a particular filesystem object.
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) system call. Note that again, this list may be substantially smaller than what is available via getattrlist(2)
The following code searches a volume for files of the specified type and creator.
#include <assert.h> #include <stdio.h> #include <stddef.h> #include <string.h> #include <sys/attr.h> #include <sys/errno.h> #include <unistd.h> 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; }
A searchfs
() function call appeared in
Darwin 1.3.1 (Mac OS X version 10.0).
November 16, 2017 | Darwin |