[PATCH] clone.2: note EINVAL when exit_signal + bad flags

[PATCH] clone.2: note EINVAL when exit_signal + bad flags

[Jack Pearson]

Document that Linux will report EINVAL when exit_signal is specified and
either CLONE_THREAD or CLONE_PARENT is specified.

From clone3_args_valid in Linux:
```
	if ((kargs->flags & (CLONE_THREAD | CLONE_PARENT)) &&
	    kargs->exit_signal)
		return false;
```

I have verified that this happens on my kernel with a small program:

```
#include <stdio.h>
#include <linux/sched.h>
#include <signal.h>
#include <sys/syscall.h>
#include <unistd.h>

int main() {
	struct clone_args ca = {
		.flags = CLONE_THREAD | CLONE_SIGHAND | CLONE_VM,
		.exit_signal = SIGCHLD, // comment me out to fix error
		.set_tid_size = 0,
	};
	syscall(SYS_clone3, &ca, sizeof(struct clone_args));
	perror("");
}
```

And I have verified that this doesn't happen with normal `clone` through
the glibc helper:

```
#define _GNU_SOURCE

#include <sched.h>
#include <signal.h>
#include <stdio.h>
#include <sys/mman.h>

int do_nothing(void *_) { return 0; }

int main() {
        void *map = mmap(NULL, 0x10000, PROT_READ | PROT_WRITE,
	                 MAP_ANONYMOUS | MAP_PRIVATE, 0, 0);
	void *stack_top = map + 0x10000 - 1;
	clone(do_nothing, stack_top,
	      CLONE_THREAD | CLONE_VM | CLONE_SIGHAND | SIGCHLD, NULL);
	perror("");
}
```

Signed-off-by: Jack Pearson <jack@pearson.onl>
---
 man2/clone.2 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man2/clone.2 b/man2/clone.2
index d63895189..be802a280 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -1436,6 +1436,16 @@ One of the PIDs specified in
 .I set_tid
 was an invalid.
 .TP
+.BR EINVAL " (" clone3 "() only)"
+.\" commit 7f192e3cd316ba58c88dfa26796cf77789dd9872
+.B CLONE_THREAD
+or
+.B CLONE_PARENT
+was specified in the
+.I flags
+mask, but a signal was specified in
+.I exit_signal.
+.TP
 .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)"
 .I stack
 was not aligned to a 128-bit boundary.
-- 
2.39.1

Re: [PATCH] clone.2: note EINVAL when exit_signal + bad flags

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2279 bytes --]

Hi Jack,

On 3/1/23 00:42, Jack Pearson wrote:
> Document that Linux will report EINVAL when exit_signal is specified and
> either CLONE_THREAD or CLONE_PARENT is specified.
> 
> From clone3_args_valid in Linux:
> ```
> 	if ((kargs->flags & (CLONE_THREAD | CLONE_PARENT)) &&
> 	    kargs->exit_signal)
> 		return false;
> ```
> 
> I have verified that this happens on my kernel with a small program:
> 
> ```
> #include <stdio.h>
> #include <linux/sched.h>
> #include <signal.h>
> #include <sys/syscall.h>
> #include <unistd.h>
> 
> int main() {
> 	struct clone_args ca = {
> 		.flags = CLONE_THREAD | CLONE_SIGHAND | CLONE_VM,
> 		.exit_signal = SIGCHLD, // comment me out to fix error
> 		.set_tid_size = 0,
> 	};
> 	syscall(SYS_clone3, &ca, sizeof(struct clone_args));
> 	perror("");
> }
> ```
> 
> And I have verified that this doesn't happen with normal `clone` through
> the glibc helper:
> 
> ```
> #define _GNU_SOURCE
> 
> #include <sched.h>
> #include <signal.h>
> #include <stdio.h>
> #include <sys/mman.h>
> 
> int do_nothing(void *_) { return 0; }
> 
> int main() {
>         void *map = mmap(NULL, 0x10000, PROT_READ | PROT_WRITE,
> 	                 MAP_ANONYMOUS | MAP_PRIVATE, 0, 0);
> 	void *stack_top = map + 0x10000 - 1;
> 	clone(do_nothing, stack_top,
> 	      CLONE_THREAD | CLONE_VM | CLONE_SIGHAND | SIGCHLD, NULL);
> 	perror("");
> }
> ```
> 
> Signed-off-by: Jack Pearson <jack@pearson.onl>
> ---
>  man2/clone.2 | 10 ++++++++++
>  1 file changed, 10 insertions(+)

Patch applied.  Thanks!

Alex

> 
> diff --git a/man2/clone.2 b/man2/clone.2
> index d63895189..be802a280 100644
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -1436,6 +1436,16 @@ One of the PIDs specified in
>  .I set_tid
>  was an invalid.
>  .TP
> +.BR EINVAL " (" clone3 "() only)"
> +.\" commit 7f192e3cd316ba58c88dfa26796cf77789dd9872
> +.B CLONE_THREAD
> +or
> +.B CLONE_PARENT
> +was specified in the
> +.I flags
> +mask, but a signal was specified in
> +.I exit_signal.
> +.TP
>  .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)"
>  .I stack
>  was not aligned to a 128-bit boundary.

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] clone.2: note EINVAL when exit_signal + bad flags

[Jack Pearson]

Will do. I'm still learning the etiquette for developing over mailing 
list. Trying not to fill up peoples' inboxes with junk y'know.

Thanks,

Jack

On 12/14/22 13:02, Alejandro Colomar wrote:
> Hi Jack,
> 
> Please keep glibc and Carlos in the loop.
> 
> Thanks,
> 
> Alex
> 
> On 12/14/22 22:00, Jack Pearson wrote:
>> On 12/12/22 18:53, Carlos O'Donell wrote:
>>> On 12/9/22 14:49, Alejandro Colomar wrote:
>>>> Hi Jack,
>>>>
>>>> On 12/2/22 23:44, Jack Pearson wrote:
>>>>> Document that Linux will report EINVAL when exit_signal is 
>>>>> specified and
>>>>> either CLONE_THREAD or CLONE_PARENT is specified.
>>>>>
>>>>>   From clone3_args_valid in Linux:
>>>>> ```
>>>>>      if ((kargs->flags & (CLONE_THREAD | CLONE_PARENT)) &&
>>>>>          kargs->exit_signal)
>>>>>          return false;
>>>>> ```
>>>>>
>>>>> I have verified that this happens on my kernel with a small 
>>>>> program, and
>>>>> that this doesn't happen with normal `clone` through the glibc helper.
>>>>
>>>> Could you please also send a test program with the glibc wrapper?
>>>>
>>>> BTW, glibc has a clone3(2) wrapper since last year.  It would be 
>>>> interesting to document it instead of the raw syscall.
>>>
>>> glibc does not have a clone3 wrapper.
>>>
>>> glibc has an internal non-exported __clone3 interface that we use for 
>>> pthreads,
>>> and likely soon for posix_spawn.
>>>
>>> We have not yet chosen to export clone3 as a public global symbol 
>>> that developers
>>> can use.
>>>
>>
>> Ahhh, that's why I couldn't find it in the headers.
>>
>> Incoming patch with the glibc clone wrapper test program.
>>
>>
>> Jack
> 

Re: [PATCH] clone.2: note EINVAL when exit_signal + bad flags

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1460 bytes --]

Hi Jack,

Please keep glibc and Carlos in the loop.

Thanks,

Alex

On 12/14/22 22:00, Jack Pearson wrote:
> On 12/12/22 18:53, Carlos O'Donell wrote:
>> On 12/9/22 14:49, Alejandro Colomar wrote:
>>> Hi Jack,
>>>
>>> On 12/2/22 23:44, Jack Pearson wrote:
>>>> Document that Linux will report EINVAL when exit_signal is specified and
>>>> either CLONE_THREAD or CLONE_PARENT is specified.
>>>>
>>>>   From clone3_args_valid in Linux:
>>>> ```
>>>>      if ((kargs->flags & (CLONE_THREAD | CLONE_PARENT)) &&
>>>>          kargs->exit_signal)
>>>>          return false;
>>>> ```
>>>>
>>>> I have verified that this happens on my kernel with a small program, and
>>>> that this doesn't happen with normal `clone` through the glibc helper.
>>>
>>> Could you please also send a test program with the glibc wrapper?
>>>
>>> BTW, glibc has a clone3(2) wrapper since last year.  It would be interesting 
>>> to document it instead of the raw syscall.
>>
>> glibc does not have a clone3 wrapper.
>>
>> glibc has an internal non-exported __clone3 interface that we use for pthreads,
>> and likely soon for posix_spawn.
>>
>> We have not yet chosen to export clone3 as a public global symbol that developers
>> can use.
>>
> 
> Ahhh, that's why I couldn't find it in the headers.
> 
> Incoming patch with the glibc clone wrapper test program.
> 
> 
> Jack

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]