.\"
.\" @(#)searchfs.2
.
-.Dd December 15, 2003
+.Dd November 16, 2017
.Dt SEARCHFS 2
.Os Darwin
.Sh NAME
.Fd #include <sys/attr.h>
.Fd #include <unistd.h>
.Ft int
-.Fn searchfs "const char * path" "struct fssearchblock * searchBlock" "unsigned long * numMatches" "unsigned long scriptCode" "unsigned long options" "struct searchstate * state"
+.Fn searchfs "const char* path" "struct fssearchblock* searchBlock" "unsigned long* numMatches" "unsigned int scriptCode" "unsigned int options" "struct searchstate* state"
.
.Sh DESCRIPTION
The
struct attrlist * returnattrs;
void * returnbuffer;
size_t returnbuffersize;
- unsigned long maxmatches;
+ unsigned int maxmatches;
struct timeval timelimit;
void * searchparams1;
size_t sizeofsearchparams1;
.
.It returnattrs
.Fn searchfs
-can return arbitrary attributes of the file system objects that it finds.
+can return arbitrary attributes of the file system objects that meet the designated
+search criteria passed in via
+.Vt searchparams1
+and
+.Vt searchparams2.
This field must point to an
.Vt attrlist
structure that specifies the attributes that you want returned.
.
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 monopolising kernel resources.
+from monopolizing kernel resources.
.Pp
.
.It searchparams1
The
.Fa numMatches
parameter points to an
-.Vt unsigned long
+.Vt unsigned int
variable.
The initial value of this variable is ignored.
On return, this variable contains the number of matching file system objects found.
.It SRCHFS_SKIPLINKS
If this bit is set,
.Fn searchfs
-will only return one reference for a hard linked file, rather that a reference
+will only return one reference for a hard linked file, rather than a reference
for each hard link to the file.
.Pp
This option is not recommended for general development.
Its primary client is the
.Xr quotacheck 2
-utility.
+utility. Note that not all filesystems that support
+.Fn searchfs
+support this option and may return EINVAL if it is requested.
.Pp
.
This option is privileged (the caller's effective UID must be 0) and cannot
The values are packed in exactly the same way as they would be returned from
.Xr getattrlist 2 ,
including the leading
-.Vt unsigned long
-length value.
+.Vt 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>.
.Pp
.
The attribute values in the first and second search buffers form a lower and upper bound for
The
.Fa options
parameter contains an invalid flag or sizeofsearchparams1/2 is greater than
-SEARCHFS_MAX_SEARCHPARMS (see attr.h).
+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.
.
.It Bq Er EAGAIN
The search terminated with partial results, either because
.Pp
.
.Sh CAVEATS
-Not all attributes can be searched for using
-.Fn searchfs .
-The list currently includes:
+
+The list of attributes valid for searching and returning to the caller may
+be substantially smaller than that of the
+.Xr getattrlist 2
+system call. See the following lists for the currently available search criteria.
+In general, a filesystem that supports
+.Fn searchfs
+will typically supply per-item attributes for matched objects that are also
+supported by the
+.Xr getdirentries 2
+system call. This varies from filesystem to filesystem.
+
+
+.Sh SEARCH ATTRIBUTES
+
+The list of attributes that are valid as search criteria currently includes the
+following list of attributes for a particular filesystem object.
+
.Pp
.
.Bl -item -compact
ATTR_CMN_GRPID
.It
ATTR_CMN_ACCESSMASK
+.It
+ATTR_CMN_FILEID
+.It
+ATTR_CMN_PARENTID
.Pp
.
.It
ATTR_FILE_RSRCALLOCSIZE
.El
.
+
+.Sh 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
+.Xr getattrlist 2
+system call. Note that again, this list may be substantially smaller than what is available via
+.Xr getattrlist 2
+
+.Pp
+.
+.Bl -item -compact
+.It
+ATTR_CMN_NAME
+.It
+ATTR_CMN_DEVID
+.It
+ATTR_CMN_FSID
+.It
+ATTR_CMN_OBJTYPE
+.It
+ATTR_CMN_OBJTAG
+.It
+ATTR_CMN_OBJID
+.It
+ATTR_CMN_OBJPERMANENTID
+.It
+ATTR_CMN_PAROBJID
+.It
+ATTR_CMN_SCRIPT
+.It
+ATTR_CMN_CRTIME
+.It
+ATTR_CMN_MODTIME
+.It
+ATTR_CMN_CHGTIME
+.It
+ATTR_CMN_ACCTIME
+.It
+ATTR_CMN_BKUPTIME
+.It
+ATTR_CMN_FNDRINFO
+.It
+ATTR_CMN_OWNERID
+.It
+ATTR_CMN_GRPID
+.It
+ATTR_CMN_ACCESSMASK
+.It
+ATTR_CMN_FLAGS
+.It
+ATTR_CMN_USERACCESS
+.It
+ATTR_CMN_FILEID
+.It
+ATTR_CMN_PARENTID
+.Pp
+.
+.It
+ATTR_DIR_LINKCOUNT
+.It
+ATTR_DIR_ENTRYCOUNT
+.It
+ATTR_DIR_MOUNTSTATUS
+.Pp
+.
+.It
+ATTR_FILE_LINKCOUNT
+.It
+ATTR_FILE_TOTALSIZE
+.It
+ATTR_FILE_ALLOCSIZE
+.It
+ATTR_FILE_IOBLOCKSIZE
+.It
+ATTR_FILE_CLUMPSIZE
+.It
+ATTR_FILE_DEVTYPE
+.It
+ATTR_FILE_DATALENGTH
+.It
+ATTR_FILE_DATAALLOCSIZE
+.It
+ATTR_FILE_RSRCLENGTH
+.It
+ATTR_FILE_RSRCALLOCSIZE
+.El
+.
+
+
.Sh EXAMPLES
.
The following code searches a volume for files of the specified type and creator.
.Pp
.
struct SearchAttrBuf {
- unsigned long length;
+ u_int32_t length;
char finderInfo[32];
};
typedef struct SearchAttrBuf SearchAttrBuf;
.Pp
.
struct ResultAttrBuf {
- unsigned long length;
+ u_int32_t length;
attrreference_t name;
fsobj_id_t parObjID;
};
static const unsigned char kAllOnes[4] = { 0xFF, 0xFF, 0xFF, 0xFF };
unsigned long matchCount;
unsigned long matchIndex;
- unsigned long options;
+ unsigned int options;
searchstate_t state;
ResultAttrBuf * thisEntry;
attrlist_t returnAttrList;
projects / apple / xnu.git / blobdiff