[PATCH v4 2/2] manual: add architecture specific note on clone and clone3 syscalls

[Florian Weimer]

* Yury Khrustalev:

> On Mon, Sep 01, 2025 at 12:46:11PM -0400, Rich Felker wrote:
>> On Mon, Sep 01, 2025 at 06:33:35PM +0200, Florian Weimer wrote:
>> > * Yury Khrustalev:
>> > 
>> > > +@subsection Architecture specific notes on system calls
>> > > +
>> > > +Because @code{syscall} function does not know anything about what a particular
>> > > +system call does or what are the ABI requirements for it, it is important to be
>> > > +aware of any additional requirements that the target kernel might have for
>> > > +certain system calls.
>> > > 
>> > > ...
>
> ** Florian
>
>> > As this is discussing clone, I think you really should mention that
>> > using syscall for clones that are not fork-style (vfork-style, or
>> > thread-style) is NOT supported in general.  Not mentioning this
>> > important restriction implies support.
>
> I agree that we should mention this, however, I've looked through the
> manual and can't find anything that would imply that clones that are
> not fork-style are supported in general. It feels like this important
> bit should've been mentioned somewhere else in the manual, e.g. in a
> section that describes clone() but we don't seem to have any.

You are adding text that says “if you call clone through syscall, you
have to do this extra thing”.  This strongly implies that calling clone
through syscall is valid in some cases.  We can instead say that calling
clone through syscall is never valid.

>> So I fail to see why any documentation is needed here beyond the
>> existing restriction that "calling syscall(SYS_clone) yourself is
>> invalid and will blow up and you get to keep all the pieces".
>
> Is this existing restriction documented anywhere?

Not really.  People work around it, for fork-style clones, by using our
clone wrapper and longjmp out of the callback function.  They then patch
the TID field in the TCB, which our clone wrapper does not reset.  None
of this is great.

The problem with adding a posix_spawn-like functionality for clone is
similar to that of posix_spawn: you end up creating this
mini-interpreter that eventually will be able to perform a large subset
of Linux system calls.  With a much worse programming experience than
the existing system call wrappers.

Thanks,
Florian