X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=lib%2Ffts_.h;h=2843107ea2495c127850e4d99fab6867befaadd4;hb=331f6ee713f7038d6d1a1c0451016c8aaab6a079;hp=4bf903bd3f267f95e00eb00ffe6dacadbe2613b0;hpb=359c0a71713e606f440d40f55a43c77349df2aaa;p=gnulib.git

diff --git a/lib/fts_.h b/lib/fts_.h
index 4bf903bd3..2843107ea 100644
--- a/lib/fts_.h
+++ b/lib/fts_.h
@@ -1,6 +1,6 @@
 /* Traverse a file hierarchy.
 
-   Copyright (C) 2004, 2005 Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -73,8 +73,10 @@ typedef struct {
 	dev_t fts_dev;			/* starting device # */
 	char *fts_path;			/* file name for this descent */
 	int fts_rfd;			/* fd for root */
+	int fts_cwd_fd;			/* the file descriptor on which the
+					   virtual cwd is open, or AT_FDCWD */
 	size_t fts_pathlen;		/* sizeof(path) */
-	size_t fts_nitems;			/* elements in the sort array */
+	size_t fts_nitems;		/* elements in the sort array */
 	int (*fts_compar) (struct _ftsent const **, struct _ftsent const **);
 					/* compare fn */
 
@@ -88,7 +90,8 @@ typedef struct {
 # define FTS_WHITEOUT	0x0080		/* return whiteout information */
 
   /* There are two ways to detect cycles.
-     The lazy way, with which one may process a directory that is a
+     The lazy way (which works only with FTS_PHYSICAL),
+     with which one may process a directory that is a
      part of the cycle several times before detecting the cycle.
      The `tight' way, whereby fts uses more memory (proportional
      to number of `active' directories, aka distance from root
@@ -96,10 +99,31 @@ typedef struct {
      to detect any cycle right away.  For example, du must use
      this option to avoid counting disk space in a cycle multiple
      times, but chown -R need not.
-     The default is to use the constant-memory lazy way. */
+     The default is to use the constant-memory lazy way, when possible
+     (see below).
+
+     However, with FTS_LOGICAL (when following symlinks, e.g., chown -L)
+     using lazy cycle detection is inadequate.  For example, traversing
+     a directory containing a symbolic link to a peer directory, it is
+     possible to encounter the same directory twice even though there
+     is no cycle:
+     dir
+     ...
+     slink -> dir
+     So, when FTS_LOGICAL is selected, we have to use a different
+     mode of cycle detection: FTS_TIGHT_CYCLE_CHECK.  */
 # define FTS_TIGHT_CYCLE_CHECK	0x0100
 
-# define FTS_OPTIONMASK	0x01ff		/* valid user option mask */
+  /* Use this flag to enable semantics with which the parent
+     application may be made both more efficient and more robust.
+     Whereas the default is to visit each directory in a recursive
+     traversal (via chdir), using this flag makes it so the initial
+     working directory is never changed.  Instead, these functions
+     perform the traversal via a virtual working directory, maintained
+     through the file descriptor member, fts_cwd_fd.  */
+# define FTS_CWDFD		0x0200
+
+# define FTS_OPTIONMASK	0x03ff		/* valid user option mask */
 
 # define FTS_NAMEONLY	0x1000		/* (private) child names only */
 # define FTS_STOP	0x2000		/* (private) unrecoverable error */
@@ -121,9 +145,10 @@ typedef struct {
 		   of thousands.  */
 		struct hash_table *ht;
 
-		/* This data structure uses lazy checking, as done by rm via
-	           cycle-check.c.  It's the default, but it's not appropriate
-	           for programs like du.  */
+		/* FIXME: rename these two members to have the fts_ prefix */
+		/* This data structure uses a lazy cycle-detection algorithm,
+		   as done by rm via cycle-check.c.  It's the default,
+		   but it's not appropriate for programs like du.  */
 		struct cycle_check_state *state;
 	} fts_cycle;
 # endif