1 files changed, 72 insertions, 17 deletions
diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3
index bba6f61094d5..ee558b892c8c 100644
--- a/lib/libc/gen/fts.3
+++ b/lib/libc/gen/fts.3
@@ -25,10 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     @(#)fts.3	8.5 (Berkeley) 4/16/94
-.\" $FreeBSD$
-.\"
-.Dd January 12, 2014
+.Dd June 30, 2025
 .Dt FTS 3
 .Os
 .Sh NAME
@@ -40,6 +37,8 @@
 .In fts.h
 .Ft FTS *
 .Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)"
+.Ft FTS *
+.Fn fts_open_b "char * const *path_argv" "int options" "int (^compar)(const FTSENT * const *, const FTSENT * const *)"
 .Ft FTSENT *
 .Fn fts_read "FTS *ftsp"
 .Ft FTSENT *
@@ -62,7 +61,9 @@ functions are provided for traversing
 file hierarchies.
 A simple overview is that the
 .Fn fts_open
-function returns a
+and
+.Fn fts_open_b
+functions return a
 .Dq handle
 on a file hierarchy, which is then supplied to
 the other
@@ -179,6 +180,12 @@ by one of the other
 values.
 .It Dv FTS_DNR
 A directory which cannot be read.
+This immediately follows
+.Dv FTS_D ,
+in place of
+.Dv FTS_DP ,
+when the directory could not be entered, or could be entered but not
+read.
 This is an error return, and the
 .Fa fts_errno
 field will be set to indicate what caused the error.
@@ -189,6 +196,8 @@ or
 .Ql ..\&
 which was not specified as a file name to
 .Fn fts_open
+or
+.Fn fts_open_b
 (see
 .Dv FTS_SEEDOT ) .
 .It Dv FTS_DP
@@ -237,6 +246,8 @@ A path for accessing the file from the current directory.
 The path for the file relative to the root of the traversal.
 This path contains the path specified to
 .Fn fts_open
+or
+.Fn fts_open_b
 as a prefix.
 .It Fa fts_pathlen
 The length of the string referenced by
@@ -383,12 +394,16 @@ must be specified.
 The options are selected by
 .Em or Ns 'ing
 the following values:
-.Bl -tag -width "FTS_PHYSICAL"
+.Bl -tag -width "FTS_COMFOLLOWDIR"
 .It Dv FTS_COMFOLLOW
 This option causes any symbolic link specified as a root path to be
 followed immediately whether or not
 .Dv FTS_LOGICAL
 is also specified.
+.It Dv FTS_COMFOLLOWDIR
+This option is similar to
+.Dv FTS_COMFOLLOW ,
+but only follows symbolic links to directories.
 .It Dv FTS_LOGICAL
 This option causes the
 .Nm
@@ -444,6 +459,15 @@ field to
 and leave the contents of the
 .Fa statp
 field undefined.
+.It Dv FTS_NOSTAT_TYPE
+This option is similar to
+.Dv FTS_NOSTAT ,
+but attempts to populate
+.Fa fts_info
+based on information from the
+.Fa d_type
+field of
+.Vt struct dirent .
 .It Dv FTS_PHYSICAL
 This option causes the
 .Nm
@@ -521,6 +545,15 @@ the directory traversal order is in the order listed in
 .Fa path_argv
 for the root paths, and in the order listed in the directory for
 everything else.
+.Sh FTS_OPEN_B
+The
+.Fn fts_open_b
+function is identical to
+.Fn fts_open
+except that it takes a block pointer instead of a function pointer.
+The block is copied before
+.Fn fts_open_b
+returns, so the original can safely go out of scope or be released.
 .Sh FTS_READ
 The
 .Fn fts_read
@@ -596,9 +629,13 @@ As a special case, if
 has not yet been called for a hierarchy,
 .Fn fts_children
 will return a pointer to the files in the logical directory specified to
-.Fn fts_open ,
+.Fn fts_open
+or
+.Fn fts_open_b ,
 i.e., the arguments specified to
-.Fn fts_open .
+.Fn fts_open
+or
+.Fn fts_open_b .
 Otherwise, if the
 .Vt FTSENT
 structure most recently returned by
@@ -719,6 +756,8 @@ function closes a file hierarchy stream
 .Fa ftsp
 and restores the current directory to the directory from which
 .Fn fts_open
+or
+.Fn fts_open_b
 was called to open
 .Fa ftsp .
 The
@@ -726,29 +765,38 @@ The
 function
 returns 0 on success, and \-1 if an error occurs.
 .Sh ERRORS
-The function
+The
 .Fn fts_open
-may fail and set
+and
+.Fn fts_open_b
+functions may fail and set
 .Va errno
 for any of the errors specified for the library functions
 .Xr open 2
 and
 .Xr malloc 3 .
+The
+.Fn fts_open_b
+function may also fail and set
+.Va errno
+to
+.Dv ENOSYS
+if the blocks runtime is missing.
 .Pp
-The function
+The
 .Fn fts_close
-may fail and set
+function may fail and set
 .Va errno
 for any of the errors specified for the library functions
 .Xr chdir 2
 and
 .Xr close 2 .
 .Pp
-The functions
+The
 .Fn fts_read
 and
 .Fn fts_children
-may fail and set
+functions may fail and set
 .Va errno
 for any of the errors specified for the library functions
 .Xr chdir 2 ,
@@ -758,12 +806,12 @@ for any of the errors specified for the library functions
 and
 .Xr stat 2 .
 .Pp
-In addition,
+In addition, the
 .Fn fts_children ,
-.Fn fts_open
+.Fn fts_open ,
 and
 .Fn fts_set
-may fail and set
+functions may fail and set
 .Va errno
 as follows:
 .Bl -tag -width Er
@@ -791,6 +839,13 @@ functions were introduced in
 principally to provide for alternative interfaces to the
 .Nm
 functionality using different data structures.
+Blocks support and the
+.Dv FTS_COMFOLLOWDIR
+and
+.Dv FTS_NOSTAT
+options were added in
+.Fx 15.0
+based on similar functionality in macOS.
 .Sh BUGS
 The
 .Fn fts_open