async-signal-safety of chroot

async-signal-safety of chroot

[tg]

Hi everyone,

Is `chroot` async-signal-safe?

It is a somewhat popular pattern to `fork`, `chroot`, then `exec`.
However, only AS-safe functions may be called between `fork` and `exec`
(stated at [1]) but the manual entry for `chroot` makes no such mention
[2]. signal-safety(7) [3] only covers POSIX, so it is also not listed
there.

The rather old POSIX edition that last specified chroot also does not
mark it AS-safe [4], [5].

Is code using this pattern buggy, or is it just missing documentation?
I expect it's the latter but it would be nice to confirm either way.

Thanks,
Trevor

[1]: https://man7.org/linux/man-pages/man2/fork.2.html
[2]: https://man7.org/linux/man-pages/man2/chroot.2.html
[3]: https://man7.org/linux/man-pages/man7/signal-safety.7.html
[4]: https://pubs.opengroup.org/onlinepubs/7908799/xsh/chroot.html
[5]: https://pubs.opengroup.org/onlinepubs/7908799/xsh/sigaction.html

Re: [musl] async-signal-safety of chroot

[Rich Felker]

On Wed, Sep 23, 2026 at 12:53:16AM +0000, tg@trevorgross.com wrote:
> Hi everyone,
> 
> Is `chroot` async-signal-safe?
> 
> It is a somewhat popular pattern to `fork`, `chroot`, then `exec`.
> However, only AS-safe functions may be called between `fork` and `exec`
> (stated at [1]) but the manual entry for `chroot` makes no such mention
> [2]. signal-safety(7) [3] only covers POSIX, so it is also not listed
> there.
> 
> The rather old POSIX edition that last specified chroot also does not
> mark it AS-safe [4], [5].
> 
> Is code using this pattern buggy, or is it just missing documentation?
> I expect it's the latter but it would be nice to confirm either way.

The restriction to only using AS-safe functions after fork only
applies in multi-threaded processes. So unless your process is
multi-threaded, that's a non-issue.

Since it's no longer standard, there is no standard governing chroot,
but in practice on most systems, including Linux/musl, chroot is going
to be AS-safe because it's just a single syscall.

Also, both glibc and musl relax the restriction on only calling
AS-safe functions in the child after a multi-threaded parent forks. In
glibc this is sort of a best-effort thing, but in musl we went through
a detailed process of ensuring that everything is made consistent for
the child. The only thing that might not be consistent is dynamic
linker state, which might make it impossible to dlopen in the child,
but this is treated as a reportable error condition not a crash or
deadlock or anything.

The changes to lift the restrictions on the child happened in commit
167390f05564e0a4d3fcb4329377fd7743267560

Rich

Re: async-signal-safety of chroot

[John Scott]

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

On Tue, 2026-09-22 at 21:34 -0400, Rich Felker wrote:
> Since it's no longer standard, there is no standard governing chroot,

On this claim only, I believe you're technically mistaken: ISO/IEC 23360-1-2:2021 (Linux Standard Base: Core specification generic part) is a current International Standard. It incorporates the definition of chroot() from SUSv2 by reference without amendment, so the same async-signal-safety limitations apply.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 411 bytes --]

Re: [musl] Re: async-signal-safety of chroot

[Rich Felker]

On Wed, Sep 23, 2026 at 04:17:03AM +0000, John Scott wrote:
> On Tue, 2026-09-22 at 21:34 -0400, Rich Felker wrote:
> > Since it's no longer standard, there is no standard governing chroot,
> 
> On this claim only, I believe you're technically mistaken: ISO/IEC
> 23360-1-2:2021 (Linux Standard Base: Core specification generic
> part) is a current International Standard. It incorporates the
> definition of chroot() from SUSv2 by reference without amendment, so
> the same async-signal-safety limitations apply.

Linux Standard Base is not relevant. It is not a standard musl aims to
conform to, and it is largely an ad hoc third party description of a
very old version of the glibc ABI and its integration into Red Hat
Linux.

Re: [musl] Re: async-signal-safety of chroot

[Florian Weimer]

* Rich Felker:

> On Wed, Sep 23, 2026 at 04:17:03AM +0000, John Scott wrote:
>> On Tue, 2026-09-22 at 21:34 -0400, Rich Felker wrote:
>> > Since it's no longer standard, there is no standard governing chroot,
>> 
>> On this claim only, I believe you're technically mistaken: ISO/IEC
>> 23360-1-2:2021 (Linux Standard Base: Core specification generic
>> part) is a current International Standard. It incorporates the
>> definition of chroot() from SUSv2 by reference without amendment, so
>> the same async-signal-safety limitations apply.
>
> Linux Standard Base is not relevant. It is not a standard musl aims to
> conform to, and it is largely an ad hoc third party description of a
> very old version of the glibc ABI and its integration into Red Hat
> Linux.

And glibc does not aim to conform to Linux Standard Base, either.  Only
very few architectures meet the symbol version requirements in ISO/IEC
23360-1-2:2021.  Any architecture that was added after glibc 2.3 is not
compliant (not even with the generic part).  This is a defect in the
standard.

Thanks,
Florian

Re: async-signal-safety of chroot

[Trevor Gross]

On Tue Sep 22, 2026 at 8:34 PM CDT, Rich Felker wrote:
> On Wed, Sep 23, 2026 at 12:53:16AM +0000, tg@trevorgross.com wrote:
>
> Since it's no longer standard, there is no standard governing chroot,
> but in practice on most systems, including Linux/musl, chroot is going
> to be AS-safe because it's just a single syscall.

Thanks Rich and others, that aligns with what I would have expected. In
that case this is a documentation request: I have a patch to the manual,
will send it in reply to this thread for any feedback.

> Also, both glibc and musl relax the restriction on only calling
> AS-safe functions in the child after a multi-threaded parent forks. In
> glibc this is sort of a best-effort thing, but in musl we went through
> a detailed process of ensuring that everything is made consistent for
> the child. The only thing that might not be consistent is dynamic
> linker state, which might make it impossible to dlopen in the child,
> but this is treated as a reportable error condition not a crash or
> deadlock or anything.
>
> The changes to lift the restrictions on the child happened in commit
> 167390f05564e0a4d3fcb4329377fd7743267560

That's great to learn about. I'll include a patch to document this as
well.

- Trevor

[PATCH 1/2] man/man2/chroot.2: Document that chroot is AS-safe

[Trevor Gross]

As discussed at [1], this is an async-signal-safe syscall wrapper.

Link: https://lore.kernel.org/linux-man/5db76d666377410fc105b9d527cbcd9f9ef3b332.camel@posteo.net/T/#t [1]
Signed-off-by: Trevor Gross <tg@trevorgross.com>
---
 man/man2/chroot.2        |  4 ++++
 man/man7/signal-safety.7 | 10 ++++++++++
 2 files changed, 14 insertions(+)

diff --git a/man/man2/chroot.2 b/man/man2/chroot.2
index fa579eb83..4372ab9c7 100644
--- a/man/man2/chroot.2
+++ b/man/man2/chroot.2
@@ -150,6 +150,10 @@ inherits its parent's root directory.
 The root directory is left unchanged by
 .BR execve (2).
 .P
+.BR chroot()
+is async-signal-safe:
+it may be safely called within a signal handler.
+.P
 The magic symbolic link,
 .IR /proc/ pid /root ,
 can be used to discover a process's root directory;
diff --git a/man/man7/signal-safety.7 b/man/man7/signal-safety.7
index f63d37f75..73d716751 100644
--- a/man/man7/signal-safety.7
+++ b/man/man7/signal-safety.7
@@ -280,6 +280,16 @@ T}
 \f[B]write\f[](2)
 .TE
 .P
+Functions listed in the following table are not required to be
+async-signal-safe by POSIX, but are safe on Linux:
+.P
+.TS
+lb
+lw(24n) l.
+Function
+\f[B]chroot\f[](2)
+.TE
+.P
 Notes:
 .IP \[bu] 3
 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions
-- 
2.50.1 (Apple Git-155)

[PATCH 2/2] man/man2/fork.2: Document glibc and musl relaxed fork->exec AS requirements

[Trevor Gross]

Link: https://lore.kernel.org/linux-man/20260923013428.GT23438@brightrain.aerifal.cx/ [1]
Link: https://git.musl-libc.org/cgit/musl/commit/?id=167390f05564e0a4d3fcb4329377fd7743267560
Signed-off-by: Trevor Gross <tg@trevorgross.com>
---
 man/man2/fork.2 | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/man/man2/fork.2 b/man/man2/fork.2
index fc78f786b..336c17448 100644
--- a/man/man2/fork.2
+++ b/man/man2/fork.2
@@ -147,10 +147,17 @@ may be helpful for dealing with problems that this can cause.
 After a
 .BR fork ()
 in a multithreaded program,
-the child can safely call only async-signal-safe functions (see
+POSIX specifies that the child can safely call only async-signal-safe
+functions (see
 .BR signal\-safety (7))
-until such time as it calls
+until it calls
 .BR execve (2).
+On glibc and musl libc, this is relaxed;
+it is safe to call non-async-signal-safe functions in the time between
+.BR fork ()
+and
+.BR exec ()
+\&.
 .IP \[bu]
 The child inherits copies of the parent's set of open file descriptors.
 Each file descriptor in the child refers to the same
-- 
2.50.1 (Apple Git-155)

Re: [musl] [PATCH 2/2] man/man2/fork.2: Document glibc and musl relaxed fork->exec AS requirements

[Rich Felker]

On Wed, Sep 23, 2026 at 11:38:19PM +0000, Trevor Gross wrote:
> Link: https://lore.kernel.org/linux-man/20260923013428.GT23438@brightrain.aerifal.cx/ [1]
> Link: https://git.musl-libc.org/cgit/musl/commit/?id=167390f05564e0a4d3fcb4329377fd7743267560
> Signed-off-by: Trevor Gross <tg@trevorgross.com>
> ---
>  man/man2/fork.2 | 11 +++++++++--
>  1 file changed, 9 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/fork.2 b/man/man2/fork.2
> index fc78f786b..336c17448 100644
> --- a/man/man2/fork.2
> +++ b/man/man2/fork.2
> @@ -147,10 +147,17 @@ may be helpful for dealing with problems that this can cause.
>  After a
>  .BR fork ()
>  in a multithreaded program,
> -the child can safely call only async-signal-safe functions (see
> +POSIX specifies that the child can safely call only async-signal-safe
> +functions (see
>  .BR signal\-safety (7))
> -until such time as it calls
> +until it calls
>  .BR execve (2).
> +On glibc and musl libc, this is relaxed;
> +it is safe to call non-async-signal-safe functions in the time between
> +.BR fork ()
> +and
> +.BR exec ()
> +\&.
>  .IP \[bu]
>  The child inherits copies of the parent's set of open file descriptors.
>  Each file descriptor in the child refers to the same
> -- 
> 2.50.1 (Apple Git-155)

While glibc has taken measures to make this mostly work, especially
malloc-after-fork, I don't think glibc has an intentional model for
ensuring that arbitrary libc functions work right in the child of a
multithreaded fork. Before accepting such a man page patch, we should
at least get an official position from glibc on whether they claim
this property or at least aim for it.

Rich

Re: async-signal-safety of chroot

[Trevor Gross]

On Tue Sep 22, 2026 at 8:34 PM CDT, Rich Felker wrote:
>
> Also, both glibc and musl relax the restriction on only calling
> AS-safe functions in the child after a multi-threaded parent forks. In
> glibc this is sort of a best-effort thing, but in musl we went through
> a detailed process of ensuring that everything is made consistent for
> the child. The only thing that might not be consistent is dynamic
> linker state, which might make it impossible to dlopen in the child,
> but this is treated as a reportable error condition not a crash or
> deadlock or anything.
>
> The changes to lift the restrictions on the child happened in commit
> 167390f05564e0a4d3fcb4329377fd7743267560
>
> Rich

A followup question: the usual wisdom has been that `fork` must always
be followed by an `exec`, and not doing so is somewhere between
error-prone and completely unsound. Based per the commit it sounds like
there are no more deadlocks, and without the POSIX AS-safe requirement,
the soundness question goes away. Does this mean that it is now
considered correct and reasonable code to `fork` without `exec` for the
purpose of e.g. invoking a function in a separate process? Similar to
what can be done with `clone`.

Of course that case may be better served by a way to re-`exec` the same
process for clean state without relying on the exact same hacks, but
that unfortunately doesn't exist.

- Trevor

Re: [musl] Re: async-signal-safety of chroot

[Rich Felker]

On Wed, Sep 23, 2026 at 07:34:35PM -0500, Trevor Gross wrote:
> On Tue Sep 22, 2026 at 8:34 PM CDT, Rich Felker wrote:
> >
> > Also, both glibc and musl relax the restriction on only calling
> > AS-safe functions in the child after a multi-threaded parent forks. In
> > glibc this is sort of a best-effort thing, but in musl we went through
> > a detailed process of ensuring that everything is made consistent for
> > the child. The only thing that might not be consistent is dynamic
> > linker state, which might make it impossible to dlopen in the child,
> > but this is treated as a reportable error condition not a crash or
> > deadlock or anything.
> >
> > The changes to lift the restrictions on the child happened in commit
> > 167390f05564e0a4d3fcb4329377fd7743267560
> 
> A followup question: the usual wisdom has been that `fork` must always
> be followed by an `exec`, and not doing so is somewhere between
> error-prone and completely unsound.

I would not say that is "usual wisdom" at all. Traditional unix
practice was very much to take maximal advantage of fork. Lots of
daemons run connections/sessions this way, shells implement subshells
this way, etc.

I would say, however, that it's good practice not to fork except to
exec, and to avoid that too (use posix_spawn instead) when possible.
There are lots of pitfalls with keeping around a forked child, ranging
from leaking potentially sensitive data you didn't intent to copy from
the parent -- especially if dropping privileges in the child -- to
logic bugs around sole ownership of a resource potentially becoming
shared/multiple ownership. Plus there are the portability issues if
anything in the parent is using threads, or if you want to port to
systems where fork is slow, poorly emulated, or unavailable (Windows,
MMU-less microcontrollers, etc.)

> Based per the commit it sounds like
> there are no more deadlocks, and without the POSIX AS-safe requirement,
> the soundness question goes away. Does this mean that it is now
> considered correct and reasonable code to `fork` without `exec` for the
> purpose of e.g. invoking a function in a separate process?

This works on musl and maybe mostly on glibc, but unless you know the
parent is single-threaded, it's not portable. If you look back at the
reason we made it work, it's because one or more interpreted languages
(sorry I don't remember which one(s) at the moment) *wrongly assumed
it works* and built their own language constructs (exposed to
applications written in those languages) around the assumption that it
works.

> Similar to
> what can be done with `clone`.

Generally clone is far more dangerous than fork in this regard. There
is no formal spec for how it behaves, and you are likely stuck with
the same or tighter AS-safety restrictions than fork would have.

musl makes clone roughly as safe as fork (see commit fa4a8abd06a4),
and disallows flags that are not compatible with executing any part of
libc in the child, but afaik glibc still has an anything-goes
approach.

Rich

Re: [musl] Re: async-signal-safety of chroot

[Florian Weimer]

* Rich Felker:

> musl makes clone roughly as safe as fork (see commit fa4a8abd06a4),
> and disallows flags that are not compatible with executing any part of
> libc in the child, but afaik glibc still has an anything-goes
> approach.

Yes, there is no filtering in glibc, and no update of the (shared) TCB.
Several web browsers longjmp out of the clone callback and patch the TCB
with the new TID, so that mutexes work as expected.

Thanks,
Florian

Re: [musl] [PATCH 2/2] man/man2/fork.2: Document glibc and musl relaxed fork->exec AS requirements

[Florian Weimer]

* Rich Felker:

>> +On glibc and musl libc, this is relaxed;
>> +it is safe to call non-async-signal-safe functions in the time between
>> +.BR fork ()
>> +and
>> +.BR exec ()
>> +\&.

> While glibc has taken measures to make this mostly work, especially
> malloc-after-fork, I don't think glibc has an intentional model for
> ensuring that arbitrary libc functions work right in the child of a
> multithreaded fork. Before accepting such a man page patch, we should
> at least get an official position from glibc on whether they claim
> this property or at least aim for it.

Far from everything in glibc is fork-protected, so the statement is not
true today as far as glibc is concerned.  We try to maintain
compatibility with existing application requirements, but the precise
goals have not been written down.

Thanks,
Florian

Re: [musl] [PATCH 2/2] man/man2/fork.2: Document glibc and musl relaxed fork->exec AS requirements

[Trevor Gross]

On Fri Sep 25, 2026 at 2:54 PM CDT, Florian Weimer wrote:
> * Rich Felker:
>
>>> +On glibc and musl libc, this is relaxed;
>>> +it is safe to call non-async-signal-safe functions in the time between
>>> +.BR fork ()
>>> +and
>>> +.BR exec ()
>>> +\&.
>
>> While glibc has taken measures to make this mostly work, especially
>> malloc-after-fork, I don't think glibc has an intentional model for
>> ensuring that arbitrary libc functions work right in the child of a
>> multithreaded fork. Before accepting such a man page patch, we should
>> at least get an official position from glibc on whether they claim
>> this property or at least aim for it.
>
> Far from everything in glibc is fork-protected, so the statement is not
> true today as far as glibc is concerned.  We try to maintain
> compatibility with existing application requirements, but the precise
> goals have not been written down.

Would the following be more accurate? 

    On glibc and musl libc, this is relaxed. With musl environments, it
    is safe to call non-async-signal-safe functions in the time between
    fork() and exec(). With glibc environments, some functions that are
    not AS-safe may be called between fork() and exec() may be safe to
    call; however, there is no exact list maintained.

Open to better wording as well, I'm not sure sure how best to express
the glibc case - if that's worth it at all.

Rich, is this reasonable to document for musl? It is a rather helpful
property even if not portable, but I'm not sure whether it is more of an
implementation detail for improved compatibility vs. something musl is
comfortable with users relying on.

- Trevor

Re: [musl] [PATCH 2/2] man/man2/fork.2: Document glibc and musl relaxed fork->exec AS requirements

[Gabriel Ravier]

On 10/2/26 8:50 AM, Trevor Gross wrote:
> On Fri Sep 25, 2026 at 2:54 PM CDT, Florian Weimer wrote:
>> * Rich Felker:
>>
>>>> +On glibc and musl libc, this is relaxed;
>>>> +it is safe to call non-async-signal-safe functions in the time between
>>>> +.BR fork ()
>>>> +and
>>>> +.BR exec ()
>>>> +\&.
>>> While glibc has taken measures to make this mostly work, especially
>>> malloc-after-fork, I don't think glibc has an intentional model for
>>> ensuring that arbitrary libc functions work right in the child of a
>>> multithreaded fork. Before accepting such a man page patch, we should
>>> at least get an official position from glibc on whether they claim
>>> this property or at least aim for it.
>> Far from everything in glibc is fork-protected, so the statement is not
>> true today as far as glibc is concerned.  We try to maintain
>> compatibility with existing application requirements, but the precise
>> goals have not been written down.
> Would the following be more accurate?
>
>      On glibc and musl libc, this is relaxed. With musl environments, it
>      is safe to call non-async-signal-safe functions in the time between
>      fork() and exec(). With glibc environments, some functions that are
>      not AS-safe may be called between fork() and exec() may be safe to
>      call; however, there is no exact list maintained.

At the very least, it shouldn't duplicate the "may be safe to call" 
clause :p

>
> Open to better wording as well, I'm not sure sure how best to express
> the glibc case - if that's worth it at all.
>
> Rich, is this reasonable to document for musl? It is a rather helpful
> property even if not portable, but I'm not sure whether it is more of an
> implementation detail for improved compatibility vs. something musl is
> comfortable with users relying on.
>
> - Trevor