X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/5b2abdfbf4211b6592cdd02b9507555a0ecbb04b..HEAD:/gen/fts.3

diff --git a/gen/fts.3 b/gen/fts.3
index 9a02ab3..9b72747 100644
--- a/gen/fts.3
+++ b/gen/fts.3
@@ -32,7 +32,7 @@
 .\"     @(#)fts.3	8.5 (Berkeley) 4/16/94
 .\" $FreeBSD: src/lib/libc/gen/fts.3,v 1.13 2001/09/20 12:32:45 ru Exp $
 .\"
-.Dd April 16, 1994
+.Dd Sept 24, 2012
 .Dt FTS 3
 .Os
 .Sh NAME
@@ -46,6 +46,8 @@
 .In fts.h
 .Ft FTS *
 .Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT **, const FTSENT **)"
+.Ft FTS *
+.Fn fts_open_b "char * const *path_argv" "int options" "int (^compar)(const FTSENT **, const FTSENT **)"
 .Ft FTSENT *
 .Fn fts_read "FTS *ftsp"
 .Ft FTSENT *
@@ -62,7 +64,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
@@ -169,6 +173,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
@@ -218,6 +224,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
@@ -364,7 +372,7 @@ must be specified.
 The options are selected by
 .Em or Ns 'ing
 the following values:
-.Bl -tag -width "FTS_PHYSICAL"
+.Bl -tag -width "FTS_NOSTAT_TYPE"
 .It Dv FTS_COMFOLLOW
 This option causes any symbolic link specified as a root path to be
 followed immediately whether or not
@@ -413,15 +421,41 @@ structures reference file characteristic information (the
 .Fa statp
 field) for each file visited.
 This option relaxes that requirement as a performance optimization,
-allowing the
+not calling
+.Xr stat 2
+whenever possible.
+If
+.Xr stat 2
+doesn't need to be called, the
 .Nm
-functions to set the
+functions will set the
 .Fa fts_info
 field to
-.Dv FTS_NSOK
-and leave the contents of the
+.Dv FTS_NSOK ;
+otherwise
+.Fa fts_info
+will be set to the correct file information value corresponding to the
+.Xr stat 2
+information.
+In any case, the
 .Fa statp
-field undefined.
+field will always be undefined.
+Note that because
+.Nm
+detects directory cycles and dangling symbolic links,
+.Xr stat 2
+is always called for directories and is called for symbolic links when
+.Dv FTS_LOGICAL
+is set.
+.It Dv FTS_NOSTAT_TYPE
+Like
+.Dv FTS_NOSTAT
+but if the file type is returned by
+.Xr readdir 3 ,
+the corresponding file information value is returned in
+.Fa fts_info
+instead of
+.Dv FTS_NSOK .
 .It Dv FTS_PHYSICAL
 This option causes the
 .Nm
@@ -499,6 +533,30 @@ 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 like
+.Fn fts_open
+except
+.Fa compar
+is a block pointer instead of a function pointer.
+This block is passed to
+.Xr qsort_b 3
+(whereas
+.Fn fts_open
+passes its function pointer to
+.Xr qsort 3 ) .
+.Bd -ragged -offset indent
+Note: The
+.Fn Block_copy
+function (defined in
+.In Blocks.h )
+is used by
+.Fn fts_open_b
+to make a copy of the block, especially for the case when a stack-based
+block might go out of scope when the subroutine returns.
+.Ed
 .Sh FTS_READ
 The
 .Fn fts_read
@@ -752,7 +810,8 @@ The options were invalid.
 .Xr find 1 ,
 .Xr chdir 2 ,
 .Xr stat 2 ,
-.Xr qsort 3
+.Xr qsort 3 ,
+.Xr qsort_b 3
 .Sh STANDARDS
 The
 .Nm