docs/166091: [docs][libc] fts(3) should document cases where FTS_NOCHDIR option is set as a side-effect

[Matthew Story]

>Number:         166091
>Category:       docs
>Synopsis:       [docs][libc] fts(3) should document cases where FTS_NOCHDIR option is set as a side-effect
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Mar 14 15:20:01 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator:     Matthew Story
>Release:        8.2
>Organization:
>Environment:
FreeBSD axe0.blackskyresearch.net 8.2-RELEASE-p2 FreeBSD 8.2-RELEASE-p2 #0: Sun Jul  3 00:57:18 EDT 2011     root at osprey.blackskyresearch.net:/usr/obj/usr/src/sys/blackskyresearch-amd64-8-2-20110702  amd64
>Description:
fts(3) sets the FTS_NOCHDIR flag in 2 cases aside from when it is explicitly provided to fts_open(3)

1. FTS_LOGICAL flag is provided to fts_open(3)

 145     /* Logical walks turn on NOCHDIR; symbolic links are too hard. */
 146     if (ISSET(FTS_LOGICAL))
 147         SET(FTS_NOCHDIR);

2. fts_open(3) cannot open(2) `.'

 209     /*
 210      * If using chdir(2), grab a file descriptor pointing to dot to ensure
 211      * that we can get back here; this could be avoided for some paths,
 212      * but almost certainly not worth the effort.  Slashes, symbolic links,
 213      * and ".." are all fairly nasty problems.  Note, if we can't get the
 214      * descriptor we run anyway, just more slowly.
 215      */
 216     if (!ISSET(FTS_NOCHDIR) && (sp->fts_rfd = _open(".", O_RDONLY, 0)) < 0)
 217         SET(FTS_NOCHDIR);

A misunderstanding of the former case caused find(1) to not traverse directories properly for -execdir when the -L option was specified (see bin/166056)
>How-To-Repeat:
man 3 fts
>Fix:
apply patch (patch is against head), patch is available via http here:

http://axe0.blackskyresearch.net/patches/matt/fts.3.add_FTS_NOCHDIR_side_effect_cases.patch.txt

Patch attached with submission follows:

Index: fts.3
===================================================================
--- fts.3	(revision 232972)
+++ fts.3	(working copy)
@@ -410,6 +410,12 @@
 .Vt FTSENT
 structures
 are returned to the application are those referencing non-existent files.
+Providing the 
+.Dv FTS_LOGICAL
+option to the
+.Fn fts_open
+function will set 
+.Dv FTS_NOCHDIR .
 Either
 .Dv FTS_LOGICAL
 or
@@ -435,6 +441,17 @@
 is specified and absolute
 pathnames were provided as arguments to
 .Fn fts_open .
+The
+.Dv FTS_NOCHDIR 
+option will be set if the
+.Dv FTS_LOGICAL 
+option is provided to the
+.Fn fts_open
+function, or if 
+.Fn fts_open
+cannot
+.Xr open 2
+.Ql .\& .
 .It Dv FTS_NOSTAT
 By default, returned
 .Vt FTSENT


>Release-Note:
>Audit-Trail:
>Unformatted: