git: 8c9b3ad2ec2a - stable/14 - fts: Document thread (un)safety
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 09 Oct 2025 12:21:31 UTC
The branch stable/14 has been updated by des:
URL: https://cgit.FreeBSD.org/src/commit/?id=8c9b3ad2ec2aaff89aa3b106fb827557dc9f941f
commit 8c9b3ad2ec2aaff89aa3b106fb827557dc9f941f
Author: Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2025-10-04 18:35:38 +0000
Commit: Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2025-10-09 12:20:52 +0000
fts: Document thread (un)safety
MFC after: 3 days
Sponsored by: Klara, Inc.
Reviewed by: markj
Differential Revision: https://reviews.freebsd.org/D52828
(cherry picked from commit 64f8416afd4cd042b34e3e975f84fb3493397828)
fts: Further improve the manual page
* Add subsections for the three functions that didn't already have one.
* Add a RETURN VALUES section.
* Improve the grammar somewhat.
* Clarify that fts_read() will not set errno to 0 if called again after
having already returned NULL.
Sponsored by: Klara, Inc.
Reviewed by: bcr, markj
Differential Revision: https://reviews.freebsd.org/D52925
(cherry picked from commit a802334d86c7173ddd7776a20065bd5682f25f67)
---
lib/libc/gen/fts.3 | 187 ++++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 165 insertions(+), 22 deletions(-)
diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3
index 04ff2ee0296a..b3e82a7200e4 100644
--- a/lib/libc/gen/fts.3
+++ b/lib/libc/gen/fts.3
@@ -27,7 +27,7 @@
.\"
.\" @(#)fts.3 8.5 (Berkeley) 4/16/94
.\"
-.Dd January 12, 2014
+.Dd October 6, 2025
.Dt FTS 3
.Os
.Sh NAME
@@ -67,14 +67,15 @@ on a file hierarchy, which is then supplied to
the other
.Nm
functions.
-The function
+The
.Fn fts_read
-returns a pointer to a structure describing one of the files in the file
-hierarchy.
-The function
+function returns a pointer to a structure describing one of the files
+in the file hierarchy.
+The
.Fn fts_children
-returns a pointer to a linked list of structures, each of which describes
-one of the files contained in a directory in the hierarchy.
+function returns a pointer to a linked list of structures, each of
+which describes one of the files contained in a directory in the
+hierarchy.
In general, directories are visited two distinguishable times; in pre-order
(before any of their descendants are visited) and in post-order (after all
of their descendants have been visited).
@@ -364,7 +365,40 @@ The
.Fa fts_name
field is always
.Dv NUL Ns -terminated .
-.Sh FTS_OPEN
+.Ss Thread Safety
+The
+.Nm
+functions can safely be used in multi-threaded programs provided no
+two threads access the same
+.Vt FTS
+or
+.Vt FTSENT
+structure simultaneously.
+However, unless the
+.Dv FTS_NOCHDIR
+flag was passed to
+.Fn fts_open ,
+calls to
+.Fn fts_read
+and
+.Fn fts_children
+may change the current working directory, which will affect all
+threads.
+Conversely, changing the current working directory either during or
+between calls to
+.Fn fts_read
+or
+.Fn fts_children
+(even in a single-thread program) may cause
+.Nm
+to malfunction unless the
+.Dv FTS_NOCHDIR
+flag was passed to
+.Fn fts_open
+and all paths in
+.Va path_argv
+were absolute.
+.Ss Fn fts_open
The
.Fn fts_open
function takes a pointer to an array of character pointers naming one
@@ -482,10 +516,10 @@ from descending into directories that have a different device number
than the file from which the descent began.
.El
.Pp
-The argument
-.Fn compar
-specifies a user-defined function which may be used to order the traversal
-of the hierarchy.
+The
+.Fa compar
+argument points to a user-defined function which may be used to order
+the traversal of the hierarchy.
It
takes two pointers to pointers to
.Vt FTSENT
@@ -520,7 +554,7 @@ 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_READ
+.Ss Fn fts_read
The
.Fn fts_read
function returns a pointer to an
@@ -554,6 +588,15 @@ structure is returned, and
.Va errno
may or may not have been set (see
.Fa fts_info ) .
+Note that
+.Fn fts_read
+will not set
+.Va errno
+to 0 if called again with the same
+.Fa ftsp
+argument after the
+.Dv FTS_STOP
+flag has been set or the end of the stream has been reached.
.Pp
The
.Vt FTSENT
@@ -568,10 +611,10 @@ directory, in which case they will not be overwritten until after a call to
.Fn fts_read
after the
.Vt FTSENT
-structure has been returned by the function
+structure has been returned by the
.Fn fts_read
-in post-order.
-.Sh FTS_CHILDREN
+function in post-order.
+.Ss Fn fts_children
The
.Fn fts_children
function returns a pointer to an
@@ -641,11 +684,11 @@ and
.Fa fts_namelen
fields.
.El
-.Sh FTS_SET
-The function
+.Ss Fn fts_set
+The
.Fn fts_set
-allows the user application to determine further processing for the
-file
+function allows the user application to determine further processing
+for the file
.Fa f
of the stream
.Fa ftsp .
@@ -711,7 +754,40 @@ The file may be one of those most recently returned by either
or
.Fn fts_read .
.El
-.Sh FTS_CLOSE
+.Ss Fn fts_set_clientptr , Fn fts_get_clientptr
+The
+.Fn fts_set_clientptr
+function sets the client data pointer for the stream
+.Fa ftsp
+to
+.Fa clientdata .
+The
+.Fn fts_get_clientptr
+function returns the client data pointer associated with
+.Fa ftsp .
+This can be used to pass per-stream data to the comparison function.
+.Pp
+For performance reasons,
+.Fn fts_get_clientptr
+may be shadowed by a preprocessor macro.
+.Ss Fn fts_get_stream
+The
+.Fn fts_get_stream
+function returns the
+.Nm
+stream associated with the file entry
+.Fa f .
+A typical use for this would be for a comparison function to first call
+.Fn fts_get_stream
+on one of its arguments, then call
+.Fn fts_get_clientptr
+to obtain the client data pointer, which in turn points to information
+necessary to correctly order the two entries.
+.Pp
+For performance reasons,
+.Fn fts_get_stream
+may be shadowed by a preprocessor macro.
+.Ss Fn fts_close
The
.Fn fts_close
function closes a file hierarchy stream
@@ -720,6 +796,73 @@ and restores the current directory to the directory from which
.Fn fts_open
was called to open
.Fa ftsp .
+.Sh RETURN VALUES
+The
+.Fn fts_open
+function returns a pointer to the new
+.Nm
+stream on success and
+.Dv NULL
+on failure.
+.Pp
+The
+.Fn fts_read
+function returns a pointer to the next file entry on success, or if an
+error occurs that relates specifically to that file entry.
+On reaching the end of the file hierarchy, it returns
+.Dv NULL
+and sets the external variable
+.Va errno
+to 0.
+On failure, it returns
+.Dv NULL
+and sets
+.Va errno
+to an appropriate non-zero value.
+If called again after the
+.Dv FTS_STOP
+flag has been set or the end of the stream has been reached,
+.Fn fts_read
+returns
+.Dv NULL
+and leaves
+.Va errno
+untouched.
+.Pp
+The
+.Fn fts_children
+function returns a pointer to a linked list of file entries on
+success.
+On reaching the end of the file hierarchy, it returns
+.Dv NULL
+and sets the external variable
+.Va errno
+to 0.
+On failure, it returns
+.Dv NULL
+and sets
+.Va errno
+to an appropriate non-zero value.
+.Pp
+The
+.Fn fts_set
+function returns 0 on success and \-1 if its
+.Fa instr
+argument is invalid.
+.Pp
+The
+.Fn fts_get_clientptr
+function returns the client data pointer associated with its argument,
+or
+.Dv NULL
+if none has been set.
+.Pp
+The
+.Fn fts_get_stream
+function returns a pointer to the
+.Nm
+stream associated with its argument.
+.Pp
The
.Fn fts_close
function
@@ -767,7 +910,7 @@ may fail and set
as follows:
.Bl -tag -width Er
.It Bq Er EINVAL
-The options were invalid, or the list were empty.
+The options were invalid, or the list was empty.
.El
.Sh SEE ALSO
.Xr find 1 ,