xnu-4903.270.47.tar.gz

[apple/xnu.git] / bsd / man / man2 / searchfs.2

diff --git a/bsd/man/man2/searchfs.2 b/bsd/man/man2/searchfs.2
index c3b602b4da4afc6fce56866144aebac9e901279e..b90765b34826ccea4079929758404b1d56018247 100644 (file)
--- a/bsd/man/man2/searchfs.2
+++ b/bsd/man/man2/searchfs.2
@@ -16,7 +16,7 @@
 .\" 
 .\"     @(#)searchfs.2
 .
 .\" 
 .\"     @(#)searchfs.2
 .

-.Dd December 15, 2003
+.Dd November 16, 2017

 .Dt SEARCHFS 2
 .Os Darwin
 .Sh NAME
 .Dt SEARCHFS 2
 .Os Darwin
 .Sh NAME


@@ -26,7 +26,7 @@
 .Fd #include <sys/attr.h>
 .Fd #include <unistd.h>
 .Ft int
 .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
 .
 .Sh DESCRIPTION
 The


@@ -79,7 +79,7 @@ struct fssearchblock {
     struct attrlist *   returnattrs;
     void *              returnbuffer;
     size_t              returnbuffersize;
     struct attrlist *   returnattrs;
     void *              returnbuffer;
     size_t              returnbuffersize;

-    unsigned long       maxmatches;
+    unsigned int        maxmatches;

     struct timeval      timelimit;
     void *              searchparams1;
     size_t              sizeofsearchparams1;
     struct timeval      timelimit;
     void *              searchparams1;
     size_t              sizeofsearchparams1;


@@ -105,7 +105,11 @@ structure are defined as follows.
 .
 .It returnattrs
 .Fn searchfs 
 .
 .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. 
 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 
 .
 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
 .Pp
 .
 .It searchparams1


@@ -196,7 +200,7 @@ This is discussed in detail below.
 The 
 .Fa numMatches 
 parameter points to an 
 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.
 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 
 .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 
 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 
 .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
 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 
 .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
 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 
 .
 .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
 .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
 .Pp
 .
 .Bl -item -compact


@@ -631,6 +657,10 @@ ATTR_CMN_OWNERID
 ATTR_CMN_GRPID
 .It
 ATTR_CMN_ACCESSMASK
 ATTR_CMN_GRPID
 .It
 ATTR_CMN_ACCESSMASK

+.It
+ATTR_CMN_FILEID
+.It
+ATTR_CMN_PARENTID

 .Pp
 .
 .It
 .Pp
 .
 .It


@@ -647,6 +677,97 @@ ATTR_FILE_RSRCLENGTH
 ATTR_FILE_RSRCALLOCSIZE
 .El
 .
 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.
 .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 {
 .Pp
 .
 struct SearchAttrBuf {

-    unsigned long   length;
+    u_int32_t       length;

     char            finderInfo[32];
 };
 typedef struct SearchAttrBuf SearchAttrBuf;
 .Pp
 .
 struct ResultAttrBuf {
     char            finderInfo[32];
 };
 typedef struct SearchAttrBuf SearchAttrBuf;
 .Pp
 .
 struct ResultAttrBuf {

-    unsigned long   length;
+    u_int32_t       length;

     attrreference_t name;
     fsobj_id_t      parObjID;
 };
     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;
     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;
     searchstate_t   state;
     ResultAttrBuf * thisEntry;
     attrlist_t      returnAttrList;