searchfs(2) - Useful Manual Pages

SYNOPSIS

#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.

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), 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), 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.