# spawn(2)

    NAME
        spawn, waitpid - create and wait for processes

    SYNOPSIS
        int montauk::spawn(const char* path, const char* args = nullptr);
        void montauk::waitpid(int pid);
        int montauk::getargs(char* buf, uint64_t maxLen);

    DESCRIPTION

       spawn
        Loads the ELF64 binary at the given VFS path and creates a new
        process. The path must include the drive prefix, for example:

            int pid = montauk::spawn("0:/os/hello.elf");

        An optional second argument passes a string to the child:

            int pid = montauk::spawn("0:/os/man.elf", "intro");

        The new process gets its own PML4 page table, a 32 KiB stack
        (at 0x7FFFFF7000-0x7FFFFFF000), and begins executing at the
        ELF entry point (_start).

        Returns the new process's PID on success, or -1 on failure.
        Failure occurs when there are no free process slots (max 256),
        the file cannot be found, or the ELF is invalid.

       waitpid
        Blocks the calling process until the process with the given PID
        has exited. Internally, this yields the CPU in a loop:

            montauk::waitpid(pid);

        This is how the shell implements foreground process execution --
        it spawns a child and waits for it to complete before showing
        the next prompt.

    EXAMPLES
        Spawn a program and wait for it:

            int pid = montauk::spawn("0:/os/hello.elf");
            if (pid < 0) {
                montauk::print("spawn failed\n");
            } else {
                montauk::waitpid(pid);
                montauk::print("child exited\n");
            }

       getargs
        Copies the argument string into buf (up to maxLen bytes, always
        null-terminated). Returns the number of characters copied, or
        -1 on error.

            char args[256];
            montauk::getargs(args, sizeof(args));

        The argument string is set by the parent when calling spawn().
        If no arguments were provided, the buffer will be empty.

    NOTES
        The _start() entry point receives no argc/argv. Use getargs()
        to retrieve the argument string passed by the parent process.

        Process exit codes are not yet collected by waitpid.

    SEE ALSO
        syscalls(2), file(2)

Back to Documentation Index