[PATCH 1/4] fts.3: note that lstat(2) may also provide fts_statp

[PATCH 1/4] fts.3: note that lstat(2) may also provide fts_statp

[наб]

[-- Attachment #1: Type: text/plain, Size: 2484 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index 495ae1d8b..bf3e075f2 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -104,7 +104,7 @@ typedef struct _ftsent {
     struct _ftsent *fts_parent;   /* parent directory */
     struct _ftsent *fts_link;     /* next file structure */
     struct _ftsent *fts_cycle;    /* cycle structure */
-    struct stat    *fts_statp;    /* stat(2) information */
+    struct stat    *fts_statp;    /* [l]stat(2) information */
 .\" Also:
 .\"     ino_t fts_ino;                  /* inode (only for directories)*/
 .\"     dev_t fts_dev;                  /* device (only for directories)*/
@@ -186,7 +186,7 @@ A regular file.
 .TP
 .B FTS_NS
 A file for which no
-.BR stat (2)
+.RB [ l ] stat (2)
 information was available.
 The contents of the
 .I fts_statp
@@ -197,7 +197,7 @@ field will be set to indicate what caused the error.
 .TP
 .B FTS_NSOK
 A file for which no
-.BR stat (2)
+.RB [ l ] stat (2)
 information was requested.
 The contents of the
 .I fts_statp
@@ -328,7 +328,7 @@ field are undefined.
 .TP
 .I fts_statp
 A pointer to
-.BR stat (2)
+.RB [ l ] stat (2)
 information for the file.
 .\" .El
 .PP
@@ -391,7 +391,13 @@ instead of the symbolic links themselves.
 If this option is set, the only symbolic links for which
 .I FTSENT
 structures
-are returned to the application are those referencing nonexistent files.
+are returned to the application are those referencing nonexistent files:
+the
+.I fts_statp
+field is obtained via
+.BR stat (2)
+with a fallback to
+.BR lstat (2).
 Either
 .B FTS_LOGICAL
 or
@@ -442,7 +448,11 @@ of the target files they point to.
 If this option is set,
 .I FTSENT
 structures for all symbolic links in the
-hierarchy are returned to the application.
+hierarchy are returned to the application:
+the
+.I fts_statp
+is obtained via
+.BR lstat (2).
 Either
 .B FTS_LOGICAL
 or
@@ -749,7 +759,7 @@ for any of the errors specified for
 .BR opendir (3),
 .BR readdir (3),
 and
-.BR stat (2).
+.RB [ l ] stat (2).
 .PP
 In addition,
 .BR fts_children (),
@@ -811,6 +821,7 @@ a program using the LFS APIs (e.g., when compiling with
 .SH SEE ALSO
 .BR find (1),
 .BR chdir (2),
+.BR lstat (2),
 .BR stat (2),
 .BR ftw (3),
 .BR qsort (3)
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 2/4] fts.3: list primary modes first, remove triplicate requirement spiel

[наб]

[-- Attachment #1: Type: text/plain, Size: 2127 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 56 +++++++++++++++++++-----------------------------------
 1 file changed, 20 insertions(+), 36 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index bf3e075f2..44465b815 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -376,12 +376,6 @@ The options are selected by ORing
 the following values:
 .\" .Bl -tag -width "FTS_PHYSICAL"
 .TP
-.B FTS_COMFOLLOW
-This option causes any symbolic link specified as a root path to be
-followed immediately whether or not
-.B FTS_LOGICAL
-is also specified.
-.TP
 .B FTS_LOGICAL
 This option causes the
 fts routines to return
@@ -398,14 +392,27 @@ field is obtained via
 .BR stat (2)
 with a fallback to
 .BR lstat (2).
-Either
-.B FTS_LOGICAL
-or
+.TP
 .B FTS_PHYSICAL
-.I must
-be provided to the
-.BR fts_open ()
-function.
+This option causes the
+fts routines to return
+.I FTSENT
+structures for symbolic links themselves instead
+of the target files they point to.
+If this option is set,
+.I FTSENT
+structures for all symbolic links in the
+hierarchy are returned to the application:
+the
+.I fts_statp
+is obtained via
+.BR lstat (2).
+.TP
+.B FTS_COMFOLLOW
+This option causes any symbolic link specified as a root path to be
+followed immediately, as if via
+.BR FTS_LOGICAL ,
+regardless of the primary mode.
 .TP
 .B FTS_NOCHDIR
 As a performance optimization, the
@@ -439,29 +446,6 @@ and leave the contents of the
 .I statp
 field undefined.
 .TP
-.B FTS_PHYSICAL
-This option causes the
-fts routines to return
-.I FTSENT
-structures for symbolic links themselves instead
-of the target files they point to.
-If this option is set,
-.I FTSENT
-structures for all symbolic links in the
-hierarchy are returned to the application:
-the
-.I fts_statp
-is obtained via
-.BR lstat (2).
-Either
-.B FTS_LOGICAL
-or
-.B FTS_PHYSICAL
-.I must
-be provided to the
-.BR fts_open ()
-function.
-.TP
 .B FTS_SEEDOT
 By default, unless they are specified as path arguments to
 .BR fts_open (),
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 3/4] fts.3: wfix

[наб]

[-- Attachment #1: Type: text/plain, Size: 805 bytes --]

This list consistently uses "this option", force that for FTS_NOCHDIR
too

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index 44465b815..627bb5afc 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -419,8 +419,7 @@ As a performance optimization, the
 fts functions change directories as they walk the file hierarchy.
 This has the side-effect that an application cannot rely on being
 in any particular directory during the traversal.
-The
-.B FTS_NOCHDIR
+This
 option turns off this optimization, and the
 fts functions will not change the current directory.
 Note that applications should not themselves change their current directory
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 4/4] fts.3: tfix

[наб]

[-- Attachment #1: Type: text/plain, Size: 765 bytes --]

statp -> fts_statp

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index 627bb5afc..601a74cd5 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -433,7 +433,7 @@ pathnames were provided as arguments to
 By default, returned
 .I FTSENT
 structures reference file characteristic information (the
-.I statp
+.I fts_statp
 field) for each file visited.
 This option relaxes that requirement as a performance optimization,
 allowing the
@@ -442,7 +442,7 @@ fts functions to set the
 field to
 .B FTS_NSOK
 and leave the contents of the
-.I statp
+.I fts_statp
 field undefined.
 .TP
 .B FTS_SEEDOT
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/4] fts.3: note that lstat(2) may also provide fts_statp

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2952 bytes --]

Hi наб!

On 7/4/22 00:23, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

It seems you've been investigating about these structures.  Would you 
mind adding a new .3type page about them, maybe?

Thanks,

Alex

> ---
>   man3/fts.3 | 25 ++++++++++++++++++-------
>   1 file changed, 18 insertions(+), 7 deletions(-)
> 
> diff --git a/man3/fts.3 b/man3/fts.3
> index 495ae1d8b..bf3e075f2 100644
> --- a/man3/fts.3
> +++ b/man3/fts.3
> @@ -104,7 +104,7 @@ typedef struct _ftsent {
>       struct _ftsent *fts_parent;   /* parent directory */
>       struct _ftsent *fts_link;     /* next file structure */
>       struct _ftsent *fts_cycle;    /* cycle structure */
> -    struct stat    *fts_statp;    /* stat(2) information */
> +    struct stat    *fts_statp;    /* [l]stat(2) information */
>   .\" Also:
>   .\"     ino_t fts_ino;                  /* inode (only for directories)*/
>   .\"     dev_t fts_dev;                  /* device (only for directories)*/
> @@ -186,7 +186,7 @@ A regular file.
>   .TP
>   .B FTS_NS
>   A file for which no
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information was available.
>   The contents of the
>   .I fts_statp
> @@ -197,7 +197,7 @@ field will be set to indicate what caused the error.
>   .TP
>   .B FTS_NSOK
>   A file for which no
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information was requested.
>   The contents of the
>   .I fts_statp
> @@ -328,7 +328,7 @@ field are undefined.
>   .TP
>   .I fts_statp
>   A pointer to
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information for the file.
>   .\" .El
>   .PP
> @@ -391,7 +391,13 @@ instead of the symbolic links themselves.
>   If this option is set, the only symbolic links for which
>   .I FTSENT
>   structures
> -are returned to the application are those referencing nonexistent files.
> +are returned to the application are those referencing nonexistent files:
> +the
> +.I fts_statp
> +field is obtained via
> +.BR stat (2)
> +with a fallback to
> +.BR lstat (2).
>   Either
>   .B FTS_LOGICAL
>   or
> @@ -442,7 +448,11 @@ of the target files they point to.
>   If this option is set,
>   .I FTSENT
>   structures for all symbolic links in the
> -hierarchy are returned to the application.
> +hierarchy are returned to the application:
> +the
> +.I fts_statp
> +is obtained via
> +.BR lstat (2).
>   Either
>   .B FTS_LOGICAL
>   or
> @@ -749,7 +759,7 @@ for any of the errors specified for
>   .BR opendir (3),
>   .BR readdir (3),
>   and
> -.BR stat (2).
> +.RB [ l ] stat (2).
>   .PP
>   In addition,
>   .BR fts_children (),
> @@ -811,6 +821,7 @@ a program using the LFS APIs (e.g., when compiling with
>   .SH SEE ALSO
>   .BR find (1),
>   .BR chdir (2),
> +.BR lstat (2),
>   .BR stat (2),
>   .BR ftw (3),
>   .BR qsort (3)

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/4] fts.3: note that lstat(2) may also provide fts_statp

[наб]

[-- Attachment #1: Type: text/plain, Size: 432 bytes --]

Hi!

On Mon, Jul 04, 2022 at 01:04:53AM +0200, Alejandro Colomar wrote:
> It seems you've been investigating about these structures.  Would you mind
> adding a new .3type page about them, maybe?

These are largely editorial changes whose lack annoyed me, I haven't
investigated much of anything here ‒ I'm barely an fts user, much less
an expert, so I'm not qualified to write a manual from whole cloth.

Best,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/4] fts.3: note that lstat(2) may also provide fts_statp

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 648 bytes --]

Hi!

On 7/4/22 01:12, наб wrote:
> Hi!
> 
> On Mon, Jul 04, 2022 at 01:04:53AM +0200, Alejandro Colomar wrote:
>> It seems you've been investigating about these structures.  Would you mind
>> adding a new .3type page about them, maybe?
> 
> These are largely editorial changes whose lack annoyed me, I haven't
> investigated much of anything here ‒ I'm barely an fts user, much less
> an expert, so I'm not qualified to write a manual from whole cloth.

Ahh, okay then.  Thanks anyway.  I'll review the patch set tomorrow.

Cheers,

Alex

> 
> Best,
> наб

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/4] fts.3: note that lstat(2) may also provide fts_statp

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3065 bytes --]

Hi наб!

On 7/4/22 00:23, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man3/fts.3 | 25 ++++++++++++++++++-------
>   1 file changed, 18 insertions(+), 7 deletions(-)
> 
> diff --git a/man3/fts.3 b/man3/fts.3
> index 495ae1d8b..bf3e075f2 100644
> --- a/man3/fts.3
> +++ b/man3/fts.3
> @@ -104,7 +104,7 @@ typedef struct _ftsent {
>       struct _ftsent *fts_parent;   /* parent directory */
>       struct _ftsent *fts_link;     /* next file structure */
>       struct _ftsent *fts_cycle;    /* cycle structure */
> -    struct stat    *fts_statp;    /* stat(2) information */
> +    struct stat    *fts_statp;    /* [l]stat(2) information */
>   .\" Also:
>   .\"     ino_t fts_ino;                  /* inode (only for directories)*/
>   .\"     dev_t fts_dev;                  /* device (only for directories)*/
> @@ -186,7 +186,7 @@ A regular file.
>   .TP
>   .B FTS_NS
>   A file for which no
> -.BR stat (2)
> +.RB [ l ] stat (2)

I was trying to guess in which case lstat(2) has info but stat(2) 
hasn't.  I guess it's in the case of a dangling link (ENOENT for 
stat(2)), right?  Any other cases?

I guess that would be a good thing to add to the commit msg.

Cheers,

Alex

>   information was available.
>   The contents of the
>   .I fts_statp
> @@ -197,7 +197,7 @@ field will be set to indicate what caused the error.
>   .TP
>   .B FTS_NSOK
>   A file for which no
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information was requested.
>   The contents of the
>   .I fts_statp
> @@ -328,7 +328,7 @@ field are undefined.
>   .TP
>   .I fts_statp
>   A pointer to
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information for the file.
>   .\" .El
>   .PP
> @@ -391,7 +391,13 @@ instead of the symbolic links themselves.
>   If this option is set, the only symbolic links for which
>   .I FTSENT
>   structures
> -are returned to the application are those referencing nonexistent files.
> +are returned to the application are those referencing nonexistent files:
> +the
> +.I fts_statp
> +field is obtained via
> +.BR stat (2)
> +with a fallback to
> +.BR lstat (2).
>   Either
>   .B FTS_LOGICAL
>   or
> @@ -442,7 +448,11 @@ of the target files they point to.
>   If this option is set,
>   .I FTSENT
>   structures for all symbolic links in the
> -hierarchy are returned to the application.
> +hierarchy are returned to the application:
> +the
> +.I fts_statp
> +is obtained via
> +.BR lstat (2).
>   Either
>   .B FTS_LOGICAL
>   or
> @@ -749,7 +759,7 @@ for any of the errors specified for
>   .BR opendir (3),
>   .BR readdir (3),
>   and
> -.BR stat (2).
> +.RB [ l ] stat (2).
>   .PP
>   In addition,
>   .BR fts_children (),
> @@ -811,6 +821,7 @@ a program using the LFS APIs (e.g., when compiling with
>   .SH SEE ALSO
>   .BR find (1),
>   .BR chdir (2),
> +.BR lstat (2),
>   .BR stat (2),
>   .BR ftw (3),
>   .BR qsort (3)

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 2/4] fts.3: list primary modes first, remove triplicate requirement spiel

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2794 bytes --]

Hi,

Please break this commit into smaller chunks.
I'd like commits that move code to _only_ move code,
and do anything else (adjust style/formatting, remove duplicates, ...) 
in a subsequent patch.
See also: 
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#style-check-your-changes>

It's hard for me to read this patch as is.  Sorry :/

Cheers,

Alex

On 7/4/22 00:23, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man3/fts.3 | 56 +++++++++++++++++++-----------------------------------
>   1 file changed, 20 insertions(+), 36 deletions(-)
> 
> diff --git a/man3/fts.3 b/man3/fts.3
> index bf3e075f2..44465b815 100644
> --- a/man3/fts.3
> +++ b/man3/fts.3
> @@ -376,12 +376,6 @@ The options are selected by ORing
>   the following values:
>   .\" .Bl -tag -width "FTS_PHYSICAL"
>   .TP
> -.B FTS_COMFOLLOW
> -This option causes any symbolic link specified as a root path to be
> -followed immediately whether or not
> -.B FTS_LOGICAL
> -is also specified.
> -.TP
>   .B FTS_LOGICAL
>   This option causes the
>   fts routines to return
> @@ -398,14 +392,27 @@ field is obtained via
>   .BR stat (2)
>   with a fallback to
>   .BR lstat (2).
> -Either
> -.B FTS_LOGICAL
> -or
> +.TP
>   .B FTS_PHYSICAL
> -.I must
> -be provided to the
> -.BR fts_open ()
> -function.
> +This option causes the
> +fts routines to return
> +.I FTSENT
> +structures for symbolic links themselves instead
> +of the target files they point to.
> +If this option is set,
> +.I FTSENT
> +structures for all symbolic links in the
> +hierarchy are returned to the application:
> +the
> +.I fts_statp
> +is obtained via
> +.BR lstat (2).
> +.TP
> +.B FTS_COMFOLLOW
> +This option causes any symbolic link specified as a root path to be
> +followed immediately, as if via
> +.BR FTS_LOGICAL ,
> +regardless of the primary mode.
>   .TP
>   .B FTS_NOCHDIR
>   As a performance optimization, the
> @@ -439,29 +446,6 @@ and leave the contents of the
>   .I statp
>   field undefined.
>   .TP
> -.B FTS_PHYSICAL
> -This option causes the
> -fts routines to return
> -.I FTSENT
> -structures for symbolic links themselves instead
> -of the target files they point to.
> -If this option is set,
> -.I FTSENT
> -structures for all symbolic links in the
> -hierarchy are returned to the application:
> -the
> -.I fts_statp
> -is obtained via
> -.BR lstat (2).
> -Either
> -.B FTS_LOGICAL
> -or
> -.B FTS_PHYSICAL
> -.I must
> -be provided to the
> -.BR fts_open ()
> -function.
> -.TP
>   .B FTS_SEEDOT
>   By default, unless they are specified as path arguments to
>   .BR fts_open (),

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 3/4] fts.3: wfix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 983 bytes --]

On 7/4/22 00:23, наб wrote:
> This list consistently uses "this option", force that for FTS_NOCHDIR
> too
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied, наб.

Thanks,

Alex

> ---
>   man3/fts.3 | 3 +--
>   1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/man3/fts.3 b/man3/fts.3
> index 44465b815..627bb5afc 100644
> --- a/man3/fts.3
> +++ b/man3/fts.3
> @@ -419,8 +419,7 @@ As a performance optimization, the
>   fts functions change directories as they walk the file hierarchy.
>   This has the side-effect that an application cannot rely on being
>   in any particular directory during the traversal.
> -The
> -.B FTS_NOCHDIR
> +This
>   option turns off this optimization, and the
>   fts functions will not change the current directory.
>   Note that applications should not themselves change their current directory

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 4/4] fts.3: tfix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1078 bytes --]

Hi,

On 7/4/22 00:23, наб wrote:
> statp -> fts_statp
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

I tried to apply this patch, but it doesn't want to.  I guess it depends 
on previous patches in this set, so I'll wait for v2.

Cheers,

Alex

> ---
>   man3/fts.3 | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man3/fts.3 b/man3/fts.3
> index 627bb5afc..601a74cd5 100644
> --- a/man3/fts.3
> +++ b/man3/fts.3
> @@ -433,7 +433,7 @@ pathnames were provided as arguments to
>   By default, returned
>   .I FTSENT
>   structures reference file characteristic information (the
> -.I statp
> +.I fts_statp
>   field) for each file visited.
>   This option relaxes that requirement as a performance optimization,
>   allowing the
> @@ -442,7 +442,7 @@ fts functions to set the
>   field to
>   .B FTS_NSOK
>   and leave the contents of the
> -.I statp
> +.I fts_statp
>   field undefined.
>   .TP
>   .B FTS_SEEDOT

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 1/5] fts.3: note that lstat(2) may also provide fts_statp

[наб]

[-- Attachment #1: Type: text/plain, Size: 2903 bytes --]

In FTS_PHYSICAL                 mode, it's always lstat()
In FTS_LOGICAL                  mode, it's stat() unless it ENOENTs
                                      in which case it's lstat()
In FTS_PHYSICAL | FTS_COMFOLLOW mode, it's FTS_LOGICAL  for path_argv
                                      and  FTS_PHYSICAL for children

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
All of your comments applied; original 3/4 omitted since you applied it.

 man3/fts.3 | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index 0b3513192..5197b5868 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -104,7 +104,7 @@ typedef struct _ftsent {
     struct _ftsent *fts_parent;   /* parent directory */
     struct _ftsent *fts_link;     /* next file structure */
     struct _ftsent *fts_cycle;    /* cycle structure */
-    struct stat    *fts_statp;    /* stat(2) information */
+    struct stat    *fts_statp;    /* [l]stat(2) information */
 .\" Also:
 .\"     ino_t fts_ino;                  /* inode (only for directories)*/
 .\"     dev_t fts_dev;                  /* device (only for directories)*/
@@ -186,7 +186,7 @@ A regular file.
 .TP
 .B FTS_NS
 A file for which no
-.BR stat (2)
+.RB [ l ] stat (2)
 information was available.
 The contents of the
 .I fts_statp
@@ -197,7 +197,7 @@ field will be set to indicate what caused the error.
 .TP
 .B FTS_NSOK
 A file for which no
-.BR stat (2)
+.RB [ l ] stat (2)
 information was requested.
 The contents of the
 .I fts_statp
@@ -328,7 +328,7 @@ field are undefined.
 .TP
 .I fts_statp
 A pointer to
-.BR stat (2)
+.RB [ l ] stat (2)
 information for the file.
 .\" .El
 .PP
@@ -391,7 +391,13 @@ instead of the symbolic links themselves.
 If this option is set, the only symbolic links for which
 .I FTSENT
 structures
-are returned to the application are those referencing nonexistent files.
+are returned to the application are those referencing nonexistent files:
+the
+.I fts_statp
+field is obtained via
+.BR stat (2)
+with a fallback to
+.BR lstat (2).
 Either
 .B FTS_LOGICAL
 or
@@ -441,7 +447,11 @@ of the target files they point to.
 If this option is set,
 .I FTSENT
 structures for all symbolic links in the
-hierarchy are returned to the application.
+hierarchy are returned to the application:
+the
+.I fts_statp
+field is obtained via
+.BR lstat (2).
 Either
 .B FTS_LOGICAL
 or
@@ -748,7 +758,7 @@ for any of the errors specified for
 .BR opendir (3),
 .BR readdir (3),
 and
-.BR stat (2).
+.RB [ l ] stat (2).
 .PP
 In addition,
 .BR fts_children (),
@@ -810,6 +820,7 @@ a program using the LFS APIs (e.g., when compiling with
 .SH SEE ALSO
 .BR find (1),
 .BR chdir (2),
+.BR lstat (2),
 .BR stat (2),
 .BR ftw (3),
 .BR qsort (3)
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 2/5] fts.3: remove triplicate requirement spiel

[наб]

[-- Attachment #1: Type: text/plain, Size: 815 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index 5197b5868..d3cb0145a 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -398,14 +398,6 @@ field is obtained via
 .BR stat (2)
 with a fallback to
 .BR lstat (2).
-Either
-.B FTS_LOGICAL
-or
-.B FTS_PHYSICAL
-.I must
-be provided to the
-.BR fts_open ()
-function.
 .TP
 .B FTS_NOCHDIR
 As a performance optimization, the
@@ -452,14 +444,6 @@ the
 .I fts_statp
 field is obtained via
 .BR lstat (2).
-Either
-.B FTS_LOGICAL
-or
-.B FTS_PHYSICAL
-.I must
-be provided to the
-.BR fts_open ()
-function.
 .TP
 .B FTS_SEEDOT
 By default, unless they are specified as path arguments to
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 3/5] fts.3: clarify FTS_COMFOLLOW behaviour

[наб]

[-- Attachment #1: Type: text/plain, Size: 713 bytes --]

FTS_COMFOLLOW is equivalent to FTS_LOGICAL for fts_level == 0:
define it as such

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index d3cb0145a..7afaa0da5 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -378,9 +378,9 @@ the following values:
 .TP
 .B FTS_COMFOLLOW
 This option causes any symbolic link specified as a root path to be
-followed immediately whether or not
-.B FTS_LOGICAL
-is also specified.
+followed immediately, as if via
+.BR FTS_LOGICAL ,
+regardless of the primary mode.
 .TP
 .B FTS_LOGICAL
 This option causes the
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 4/5] fts.3: list primary modes first

[наб]

[-- Attachment #1: Type: text/plain, Size: 2113 bytes --]

FTS_LOGICAL sorts before FTS_PHYSICAL,
FTS_COMFOLLOW modifies FTS_PHYSICAL,
the remaining flags follow in sorted order

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index 7afaa0da5..b49d85adc 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -376,12 +376,6 @@ The options are selected by ORing
 the following values:
 .\" .Bl -tag -width "FTS_PHYSICAL"
 .TP
-.B FTS_COMFOLLOW
-This option causes any symbolic link specified as a root path to be
-followed immediately, as if via
-.BR FTS_LOGICAL ,
-regardless of the primary mode.
-.TP
 .B FTS_LOGICAL
 This option causes the
 fts routines to return
@@ -399,6 +393,27 @@ field is obtained via
 with a fallback to
 .BR lstat (2).
 .TP
+.B FTS_PHYSICAL
+This option causes the
+fts routines to return
+.I FTSENT
+structures for symbolic links themselves instead
+of the target files they point to.
+If this option is set,
+.I FTSENT
+structures for all symbolic links in the
+hierarchy are returned to the application:
+the
+.I fts_statp
+field is obtained via
+.BR lstat (2).
+.TP
+.B FTS_COMFOLLOW
+This option causes any symbolic link specified as a root path to be
+followed immediately, as if via
+.BR FTS_LOGICAL ,
+regardless of the primary mode.
+.TP
 .B FTS_NOCHDIR
 As a performance optimization, the
 fts functions change directories as they walk the file hierarchy.
@@ -430,21 +445,6 @@ and leave the contents of the
 .I statp
 field undefined.
 .TP
-.B FTS_PHYSICAL
-This option causes the
-fts routines to return
-.I FTSENT
-structures for symbolic links themselves instead
-of the target files they point to.
-If this option is set,
-.I FTSENT
-structures for all symbolic links in the
-hierarchy are returned to the application:
-the
-.I fts_statp
-field is obtained via
-.BR lstat (2).
-.TP
 .B FTS_SEEDOT
 By default, unless they are specified as path arguments to
 .BR fts_open (),
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 5/5] fts.3: tfix

[наб]

[-- Attachment #1: Type: text/plain, Size: 765 bytes --]

statp -> fts_statp

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/fts.3 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man3/fts.3 b/man3/fts.3
index b49d85adc..f4796747f 100644
--- a/man3/fts.3
+++ b/man3/fts.3
@@ -433,7 +433,7 @@ pathnames were provided as arguments to
 By default, returned
 .I FTSENT
 structures reference file characteristic information (the
-.I statp
+.I fts_statp
 field) for each file visited.
 This option relaxes that requirement as a performance optimization,
 allowing the
@@ -442,7 +442,7 @@ fts functions to set the
 field to
 .B FTS_NSOK
 and leave the contents of the
-.I statp
+.I fts_statp
 field undefined.
 .TP
 .B FTS_SEEDOT
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/5] fts.3: note that lstat(2) may also provide fts_statp

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3287 bytes --]

Hi наб,

On 7/5/22 18:21, наб wrote:
> In FTS_PHYSICAL                 mode, it's always lstat()
> In FTS_LOGICAL                  mode, it's stat() unless it ENOENTs
>                                        in which case it's lstat()
> In FTS_PHYSICAL | FTS_COMFOLLOW mode, it's FTS_LOGICAL  for path_argv
>                                        and  FTS_PHYSICAL for children
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch set applied.

Thanks,

Alex

> ---
> All of your comments applied; original 3/4 omitted since you applied it.
> 
>   man3/fts.3 | 25 ++++++++++++++++++-------
>   1 file changed, 18 insertions(+), 7 deletions(-)
> 
> diff --git a/man3/fts.3 b/man3/fts.3
> index 0b3513192..5197b5868 100644
> --- a/man3/fts.3
> +++ b/man3/fts.3
> @@ -104,7 +104,7 @@ typedef struct _ftsent {
>       struct _ftsent *fts_parent;   /* parent directory */
>       struct _ftsent *fts_link;     /* next file structure */
>       struct _ftsent *fts_cycle;    /* cycle structure */
> -    struct stat    *fts_statp;    /* stat(2) information */
> +    struct stat    *fts_statp;    /* [l]stat(2) information */
>   .\" Also:
>   .\"     ino_t fts_ino;                  /* inode (only for directories)*/
>   .\"     dev_t fts_dev;                  /* device (only for directories)*/
> @@ -186,7 +186,7 @@ A regular file.
>   .TP
>   .B FTS_NS
>   A file for which no
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information was available.
>   The contents of the
>   .I fts_statp
> @@ -197,7 +197,7 @@ field will be set to indicate what caused the error.
>   .TP
>   .B FTS_NSOK
>   A file for which no
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information was requested.
>   The contents of the
>   .I fts_statp
> @@ -328,7 +328,7 @@ field are undefined.
>   .TP
>   .I fts_statp
>   A pointer to
> -.BR stat (2)
> +.RB [ l ] stat (2)
>   information for the file.
>   .\" .El
>   .PP
> @@ -391,7 +391,13 @@ instead of the symbolic links themselves.
>   If this option is set, the only symbolic links for which
>   .I FTSENT
>   structures
> -are returned to the application are those referencing nonexistent files.
> +are returned to the application are those referencing nonexistent files:
> +the
> +.I fts_statp
> +field is obtained via
> +.BR stat (2)
> +with a fallback to
> +.BR lstat (2).
>   Either
>   .B FTS_LOGICAL
>   or
> @@ -441,7 +447,11 @@ of the target files they point to.
>   If this option is set,
>   .I FTSENT
>   structures for all symbolic links in the
> -hierarchy are returned to the application.
> +hierarchy are returned to the application:
> +the
> +.I fts_statp
> +field is obtained via
> +.BR lstat (2).
>   Either
>   .B FTS_LOGICAL
>   or
> @@ -748,7 +758,7 @@ for any of the errors specified for
>   .BR opendir (3),
>   .BR readdir (3),
>   and
> -.BR stat (2).
> +.RB [ l ] stat (2).
>   .PP
>   In addition,
>   .BR fts_children (),
> @@ -810,6 +820,7 @@ a program using the LFS APIs (e.g., when compiling with
>   .SH SEE ALSO
>   .BR find (1),
>   .BR chdir (2),
> +.BR lstat (2),
>   .BR stat (2),
>   .BR ftw (3),
>   .BR qsort (3)

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]