X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/91447636331957f3d9b5ca5b508f07c526b0074d..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/searchfs.2 diff --git a/bsd/man/man2/searchfs.2 b/bsd/man/man2/searchfs.2 index c3b602b4d..b90765b34 100644 --- a/bsd/man/man2/searchfs.2 +++ b/bsd/man/man2/searchfs.2 @@ -16,7 +16,7 @@ .\" .\" @(#)searchfs.2 . -.Dd December 15, 2003 +.Dd November 16, 2017 .Dt SEARCHFS 2 .Os Darwin .Sh NAME @@ -26,7 +26,7 @@ .Fd #include .Fd #include .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 @@ -79,7 +79,7 @@ struct fssearchblock { struct attrlist * returnattrs; void * returnbuffer; size_t returnbuffersize; - unsigned long maxmatches; + unsigned int maxmatches; struct timeval timelimit; void * searchparams1; size_t sizeofsearchparams1; @@ -105,7 +105,11 @@ structure are defined as follows. . .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. @@ -142,7 +146,7 @@ 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 monopolising kernel resources. +from monopolizing kernel resources. .Pp . .It searchparams1 @@ -196,7 +200,7 @@ This is discussed in detail below. 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. @@ -266,13 +270,15 @@ or both. .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 @@ -443,8 +449,9 @@ The format of each of these buffers is determined by the attributes that you're 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 . .Pp . The attribute values in the first and second search buffers form a lower and upper bound for @@ -571,7 +578,11 @@ One of the pointer parameters points to an invalid address. 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 @@ -599,9 +610,24 @@ An I/O error occurred while reading from or writing to the file system. .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 @@ -631,6 +657,10 @@ ATTR_CMN_OWNERID ATTR_CMN_GRPID .It ATTR_CMN_ACCESSMASK +.It +ATTR_CMN_FILEID +.It +ATTR_CMN_PARENTID .Pp . .It @@ -647,6 +677,97 @@ ATTR_FILE_RSRCLENGTH 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. @@ -667,14 +788,14 @@ typedef struct searchstate searchstate_t; .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; }; @@ -699,7 +820,7 @@ static int SearchFSDemo( 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;