From nobody Thu Oct 9 12:21:31 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4cj8B44yrbz6BqCr; Thu, 09 Oct 2025 12:21:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4cj8B42BVnz3RBC; Thu, 09 Oct 2025 12:21:32 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1760012492; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=/jEAdYHyRudD7NCd8+62w03cIP3Wu8aVWEXIkdbHUhs=; b=HlogbjHQvyO9uUZcezHDQcAECGaMMVJDCDg+Eh1tD7m9cD45SJ35zW4XsEo1u5iuh5q/0N UAXfvt39nDJyddGvO/C1+4vqEjIhvxnit4DUkq5jI1LqD4qNBP4s4Zeap0Qv53N8HMBN1N 6XyxFlDh6xRpdzDYUe83IK9LoGQW8cS55pBcM122knTKeHJuwTE3GNbi0119XJlq5JdUvv Z4/tjZg709oUrbM0+hYpeHws+nxD5ZaFHrtBTKkGrLm/UkAK1szOxejwTiG6X82OcKATdD +3H2eb/A3KuOXLF3n2+Glsh+Z0ZxcIALy7F6AFzRfH3ZVUb4bXcU2l3DIOungw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1760012492; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=/jEAdYHyRudD7NCd8+62w03cIP3Wu8aVWEXIkdbHUhs=; b=Rw5/pAVwk9HZ+l1Q2DJ1y6lzJrbgHMJQ/uzAq9NatQKDsqC1B0oXduoTsnks7ySz3Kaf38 tv0m3mvvl5ZtPPwOYrCjPxzf3XBIkz0XILTVuCWCuqUQOAwzNw9Vd8RRATuXHBA1Id+bIK mRO0ziWqvaYtEx0BNfI/Gk3AgZq75w1XZb+ypgdUQ1NRJPJW+J9hcMZznoCssKh+drgjOW M6ffDq7axOZurwfPafVHPlpmV48L3sX83dUdDndKCTxsYxVyVFTRRcZZQO/C7Tbh0zmWGJ QoRAnvyUWpI/U6ivBxGyfgVW/9c9qpk4V6ro4aGvxwzfJtuncUoBM+mV6clP9w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1760012492; a=rsa-sha256; cv=none; b=hcchUle2qrzCqALQ2p0LEZ+xTQAyljrqSGvEy4uM8vIOP8u7CKXehVIfVUrqMCNfxCC6nA 8ahGuVi07P8fZeRsybp4JP5nQkGkNVm1CeA97YhmAcIJJL6awuX6BDHNZlskI6wYPQjH7f +or6dCMNy19ryeolMmuZCA7fSbqfo5g5U7wO6F/u5SPpPI0KVCdGt+PST3cXPJhT3/sCFL rfhQLIQaFPMoUNzVtCrSj6rePyVqvErVk1HzMed3nAWRV9Sp+BotwYCj6JJaLTG9J6bDbs UHJkDNibv9mUGlBrLwy3WJesb5eabTx3PgY2hy3O93A2Ny+QOfme+/yVShOrZQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4cj8B40ZPZz207; Thu, 09 Oct 2025 12:21:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 599CLV9g046753; Thu, 9 Oct 2025 12:21:31 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 599CLVoN046750; Thu, 9 Oct 2025 12:21:31 GMT (envelope-from git) Date: Thu, 9 Oct 2025 12:21:31 GMT Message-Id: <202510091221.599CLVoN046750@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Dag-Erling =?utf-8?Q?Sm=C3=B8rgrav?= Subject: git: 8c9b3ad2ec2a - stable/14 - fts: Document thread (un)safety List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: des X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: 8c9b3ad2ec2aaff89aa3b106fb827557dc9f941f Auto-Submitted: auto-generated 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 AuthorDate: 2025-10-04 18:35:38 +0000 Commit: Dag-Erling Smørgrav 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 ,