Re: [RFC 08/19] exec: add API specification for execve

[Sasha Levin]

On Tue, Jun 17, 2025 at 09:13:44AM +0200, Florian Weimer wrote:
> * Sasha Levin:
>
> > On Mon, Jun 16, 2025 at 11:39:31PM +0200, Florian Weimer wrote:
> > > * Sasha Levin:
> > >
> > > > +	KAPI_RETURN("long", "Does not return on success; returns -1 on error")
> > > > +		.type = KAPI_TYPE_INT,
> > > > +		.check_type = KAPI_RETURN_ERROR_CHECK,
> > > > +	KAPI_RETURN_END
> > >
> > > Is the -1 part correct?
> >
> > Maybe :) That's one of the things I wasn't sure about: we're documenting
> > the execve syscall rather than the function itself. A user calling
> > execve() will end up with -1 on failure, and errno set with the error
> > code.
>
> Well, it doesn't say execve, it says sys_execve.
>
> > You could argue that it's libc that sets errno and we're trying to spec
> > the kernel here, not the userspace interface to it.
>
> And I think this would be appropriate.
>
> Note that in the future, the glibc version of execve will not be a
> straightforward system call wrapper because we need to obtain a
> consistent snapshot of the environment array.  That is actually pretty
> hard because we cannot atomically replace the process image, unblock
> signals, and unmap a copy of the environment.
>
> So I think it's best for the kernel to stick with the system call
> interface and not try to document what libcs are doing.

I hear you - it sounds like the "right" solution technically.


Switching back to signals, how does something like the below look as far
as expanding the execve() spec:

+       /* SIGSEGV sent on point of no return failure */
+       KAPI_SIGNAL(9, SIGSEGV, "SIGSEGV", KAPI_SIGNAL_SEND, KAPI_SIGNAL_ACTION_COREDUMP)
+               KAPI_SIGNAL_TARGET("Current process")
+               KAPI_SIGNAL_CONDITION("Exec fails after point of no return")
+               KAPI_SIGNAL_DESC("If exec fails after the point of no return (when the old "
+                                "process image has been destroyed), force_fatal_sig(SIGSEGV) "
+                                "is called to terminate the process since it cannot continue.")
+               KAPI_SIGNAL_TIMING(KAPI_SIGNAL_TIME_EXIT)
+               KAPI_SIGNAL_PRIORITY(0)
+               KAPI_SIGNAL_STATE_FORBID(KAPI_SIGNAL_STATE_ZOMBIE | KAPI_SIGNAL_STATE_DEAD)
+       KAPI_SIGNAL_END
+
+       /* Signal mask preserved */
+       KAPI_SIGNAL(10, 0, "SIGNAL_MASK", KAPI_SIGNAL_HANDLE, KAPI_SIGNAL_ACTION_CUSTOM)
+               KAPI_SIGNAL_CONDITION("Process has blocked signals")
+               KAPI_SIGNAL_DESC("The signal mask (blocked signals) is preserved across exec. "
+                                "This allows processes to block signals before exec and have "
+                                "them remain blocked in the new program.")
+               KAPI_SIGNAL_TIMING(KAPI_SIGNAL_TIME_DURING)
+       KAPI_SIGNAL_END
+
+       /* Realtime signal queues cleared */
+       KAPI_SIGNAL(11, 0, "REALTIME_SIGNALS", KAPI_SIGNAL_HANDLE, KAPI_SIGNAL_ACTION_DISCARD)
+               KAPI_SIGNAL_CONDITION("Realtime signals queued")
+               KAPI_SIGNAL_DESC("All queued realtime signals (SIGRTMIN to SIGRTMAX) are "
+                                "discarded during exec. The realtime signal queue is cleared.")
+               KAPI_SIGNAL_TIMING(KAPI_SIGNAL_TIME_DURING)
+               KAPI_SIGNAL_QUEUE(KAPI_SIGNAL_QUEUE_REALTIME)
+       KAPI_SIGNAL_END

What's missing for me is that while we now go into more detail, we
should also check this during runtime, but I'm still trying to come up
with something that is not ugly.

--
Thanks,
Sasha