From nobody Sat Oct 4 18:42:53 2025 X-Original-To: dev-commits-src-main@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 4cfDtP6scjz69YgH; Sat, 04 Oct 2025 18:42:53 +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 4cfDtP69ZJz3kmv; Sat, 04 Oct 2025 18:42:53 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1759603373; 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=fYLYQkZZEgx5I4y66f7z2mfEcXIAGeDAc5Fs0lgGJaA=; b=hRJVd+BkPVhNjIWgnGIxeH9t6QduT/3VNG+myoepzXqBLUH9LwJzkJ4wmsgTxELT9vj9kj 9zuFPW6TdHiCGzeXmydYRCkThXibtJG3Yjjd/Q6LQApVhCzgjwI+2P7lBhpccNYlpIGgpc kXbc7r4wCAtSImYvaXrHbafyQJiHB1TIBKU1Dh8KDI9Enow5hH//3SbIPhOOsunjJyLkGF pjPYxVuiphPYKKncDacxCnVConDZCCkKj1/2PvwSPwpp1u95pjW0+YEmxlBAgsrUbNM712 Bw5c1exWi/MaNLnMKtSxRU3WmVmKg+OtSFHc6oOE1fD+fi6k3BGo2b3lQKmkuw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1759603373; 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=fYLYQkZZEgx5I4y66f7z2mfEcXIAGeDAc5Fs0lgGJaA=; b=FpAFf3GT39TlHhy0rssRwiWXu+4R+KuaK76Y9qV1RukfJDelqhBN76LU2ZbMjcGfQ4BGcY +PtMfogGs8t/pI5InNijRTHk/wzT8HGJwjT6MI1oc2hOMwbZPHGyl/PY6oy69Km28DK+XA 8a37dyMvhHktDONuF9NbgxENwYGzo2ERifr8XpuXLHSo8twTM3n1KpPWAqkoQZpV/s4e3w oPyWpqBpOXT1dtpJmJaTxUy4JBrTJIMiZWEb+Y4+oP87dkn9DD5sERoJVmzWGp31VLsgLf czDLfUwjFr8rhe1WGxxLFpgLBipqAFm9rciCa9eSbED5mc6Z4fbdjcf4co9W6w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1759603373; a=rsa-sha256; cv=none; b=S778zc02ufdML61TM7FHvPDyoWCnMCzvBtGfj6WI5JqSkblAbxo+h3f9UlNLaycHWne7vM MoiEmxMtkRhVXCIddO6869z/LrkajpFnoJ14k/HIRyUq8/K7LjObDItFRiQ4K3nbofLJtT pMy/cDlfkNoy5dyrlnz+n+q7sV/aLUI7no/7dfLFwXAHVQ65qASADPHWE0O9WPGQwhW6BK YXwP6umEslVZ9rNiW+Qnet6dxnK1mioppbyC4N006oT40aS/Hv4yiPyAw15KMQQXyKXVS3 GFJm73hJ5zAu2S5FZaAS7zdV/QPQUWm6IYO5RoriIXY15z+nT5ZvCAwVc6rY0Q== 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 4cfDtP5b6xztQT; Sat, 04 Oct 2025 18:42:53 +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 594Igrrj084097; Sat, 4 Oct 2025 18:42:53 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 594IgrMu084094; Sat, 4 Oct 2025 18:42:53 GMT (envelope-from git) Date: Sat, 4 Oct 2025 18:42:53 GMT Message-Id: <202510041842.594IgrMu084094@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Dag-Erling =?utf-8?Q?Sm=C3=B8rgrav?= Subject: git: 64f8416afd4c - main - fts: Document thread (un)safety List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@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/main X-Git-Reftype: branch X-Git-Commit: 64f8416afd4cd042b34e3e975f84fb3493397828 Auto-Submitted: auto-generated The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=64f8416afd4cd042b34e3e975f84fb3493397828 commit 64f8416afd4cd042b34e3e975f84fb3493397828 Author: Dag-Erling Smørgrav AuthorDate: 2025-10-04 18:35:38 +0000 Commit: Dag-Erling Smørgrav CommitDate: 2025-10-04 18:42:19 +0000 fts: Document thread (un)safety MFC after: 3 days Sponsored by: Klara, Inc. Reviewed by: markj Differential Revision: https://reviews.freebsd.org/D52828 --- lib/libc/gen/fts.3 | 51 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3 index ee558b892c8c..b937607b48e0 100644 --- a/lib/libc/gen/fts.3 +++ b/lib/libc/gen/fts.3 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 30, 2025 +.Dd October 1, 2025 .Dt FTS 3 .Os .Sh NAME @@ -376,7 +376,44 @@ 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 +or +.Fn fts_open_b , +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 +or +.Fn fts_open_b +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 @@ -545,7 +582,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_OPEN_B +.Ss Fn fts_open_b The .Fn fts_open_b function is identical to @@ -554,7 +591,7 @@ except that it takes a block pointer instead of a function pointer. The block is copied before .Fn fts_open_b returns, so the original can safely go out of scope or be released. -.Sh FTS_READ +.Ss Fn fts_read The .Fn fts_read function returns a pointer to an @@ -605,7 +642,7 @@ after the structure has been returned by the function .Fn fts_read in post-order. -.Sh FTS_CHILDREN +.Ss Fn fts_children The .Fn fts_children function returns a pointer to an @@ -679,7 +716,7 @@ and .Fa fts_namelen fields. .El -.Sh FTS_SET +.Ss Fn fts_set The function .Fn fts_set allows the user application to determine further processing for the @@ -749,7 +786,7 @@ The file may be one of those most recently returned by either or .Fn fts_read . .El -.Sh FTS_CLOSE +.Ss Fn fts_close The .Fn fts_close function closes a file hierarchy stream