Module `system.process`¶

The process module allows querying various properties about the current process, as well as creating, modifying, and searching other processes.

Index¶

Data

debug

Debugging subsystem @section system.process.debug

Function

`acceptchild()`	Accepts a new child process which was previously released to this one.
`atexit()`	Runs a function when the program exists.
`chdir()`	Sets the working directory of the current process.
`clock()`	Returns the amount of time this process has executed.
`exec()`	Replaces the current process with the contents of the specified file.
`execp()`	Replaces the current process with the contents of the specified file or command, searching the PATH environment variable if necessary.
`exit()`	Ends the current process immediately, stopping all threads and sending the specified return value to the parent.
`fork()`	Creates a new process running the specified function with arguments.
`forkbg()`	Creates a new process running the specified function with arguments. This process will be placed in the background, meaning it has no stdin/out.
`getcwd()`	Returns the working directory of the current process.
`getenv()`	Returns the environment variable table for the current process.
`getfenv()`	Returns the environment table for the current process.
`getname()`	Returns the name of the current process.
`getpid()`	Returns the process ID of the current process.
`getpinfo()`	Returns a table with various information about the specified process.
`getplist()`	Returns a list of all valid PIDs.
`getppid()`	Returns the process ID of the parent process, if available.
`getuser()`	Returns the username the process is running under.
`newthread()`	Creates a new thread running the specified function with arguments.
`nice()`	Sets the niceness level of the specified process, or the current one if left unspecified.
`releasechild()`	Releases a process to be accepted by another process.
`run()`	Runs a program from the specified path in a new process, waiting until it completes.
`setuser()`	Sets the user of the current process. This can only be run by root.
`start()`	Starts a new process from the specified path.
`startbg()`	Starts a new process from the specified path. This process will be placed in the background, meaning it has no stdin/out.

API Reference¶

system.process.getpid(): (result: number)¶

Returns the process ID of the current process.

Returns:: result (number) – The process ID of the current process

system.process.getppid(): (result: number)¶

Returns the process ID of the parent process, if available.

Returns:: result (number) – The process ID of the parent process, if available

system.process.getuser(): (result: string)¶

Returns the username the process is running under.

Returns:: result (string) – The username the process is running under

system.process.setuser(user: string): unknown¶

Sets the user of the current process. This can only be run by root.

Parameters:: user (string) – The user to switch to

system.process.clock(): (result: number)¶

Returns the amount of time this process has executed.

This may not be entirely accurate due to a lack of precision in the system clock.

Returns:: result (number) – The amount of time this process has executed

system.process.getenv(): (result: table)¶

Returns the environment variable table for the current process.

Returns:: result (table) – The environment variable table for the current process

system.process.getfenv(): (result: table)¶

Returns the environment table for the current process.

Returns:: result (table) – The environment table for the current process

system.process.getname(): (result: string)¶

Returns the name of the current process.

Returns:: result (string) – The name of the current process

system.process.getcwd(): (result: string)¶

Returns the working directory of the current process.

Returns:: result (string) – The working directory of the current process

system.process.chdir(dir: string): unknown¶

Sets the working directory of the current process.

Parameters:: dir (string) – The new working directory, which must be absolute and existent.

system.process.fork(func: function, name?: string, ...: any): (result: number)¶

Creates a new process running the specified function with arguments.

main function of the first thread, and will have its environment set to the new process’s environment.

Parameters:

func (function) – The function to run in the new process. This will be the
name? (string) – The name of the new process.
... (any) – Any arguments to pass to the function.

Returns:

result (number) – The PID of the new process.

system.process.forkbg(func: function, name?: string, ...: any): (result: number)¶

Creates a new process running the specified function with arguments. This process will be placed in the background, meaning it has no stdin/out.

main function of the first thread, and will have its environment set to the new process’s environment.

Parameters:

func (function) – The function to run in the new process. This will be the
name? (string) – The name of the new process.
... (any) – Any arguments to pass to the function.

Returns:

result (number) – The PID of the new process.

system.process.exec(path: string, ...: any): unknown¶

Replaces the current process with the contents of the specified file.

This function does not return - it can only throw an error.

Parameters:

path (string) – The path to the file to execute.
... (any) – Any arguments to pass to the file.

system.process.execp(command: string, ...: any): unknown¶

Replaces the current process with the contents of the specified file or command, searching the PATH environment variable if necessary.

This function does not return - it can only throw an error.

Parameters:

command (string) – The command or file to execute.
... (any) – Any arguments to pass to the file.

system.process.start(path: string, ...: any): (result: number)¶

Starts a new process from the specified path.

Parameters:

path (string) – The path to the file to execute.
... (any) – Any arguments to pass to the file.

Returns:

result (number) – The PID of the new process.

system.process.startbg(path: string, ...: any): (result: number)¶

Starts a new process from the specified path. This process will be placed in the background, meaning it has no stdin/out.

Parameters:

path (string) – The path to the file to execute.
... (any) – Any arguments to pass to the file.

Returns:

result (number) – The PID of the new process.

system.process.run(command: string, ...: any): (ok: boolean, res: any)¶

Runs a program from the specified path in a new process, waiting until it completes.

Parameters:

command (string) – The command or file to execute
... (any) – Any arguments to pass to the file

Returns:

ok (boolean) – Whether the process succeeded
res (any) – The return value from the process, or an error

system.process.newthread(func: function, ...: any): (result: number)¶

Creates a new thread running the specified function with arguments.

Threads in the same process share the same environment, event queue, and other properties.

Parameters:

func (function) – The function to start
... (any) – Any arguments to pass to the function

Returns:

result (number) – The ID of the new thread

system.process.exit(code?: number): unknown¶

Ends the current process immediately, stopping all threads and sending the specified return value to the parent.

This function does not return.

Parameters:: code? (number) – The value to return.

system.process.atexit(fn: function): unknown¶

Runs a function when the program exists.

This function will never get any events, and is time-limited to 100 syscalls due to running in a different context than normal threads - avoid passing long-running functions. Functions added here cannot be removed later, so if the function may not be needed after being added, use a variable check to disable it instead.

Parameters:: fn (function) – The function to call at exit

system.process.getplist(): (result: table)¶

Returns a list of all valid PIDs.

Returns:: result (table) – A list of all valid PIDs

system.process.getpinfo(pid: number): ( result: {id: number, name: string, user: string, parent: number, dir: string, stdin: number, stdout: number, stderr: number, cputime: number, systime: number, threads: {[number]: {id: number, name: string, status: string}}} | nil )¶

Returns a table with various information about the specified process.

Parameters:: pid (number) – The process ID to query.
Returns:: result ({id: number, name: string, user: string, parent: number, dir: string, stdin: number, stdout: number, stderr: number, cputime: number, systime: number, threads: {[number]: {id: number, name: string, status: string}}} | nil) – The process information, or nil if the process doesn’t exist.

system.process.nice(level: number, pid?: number): unknown¶

Sets the niceness level of the specified process, or the current one if left unspecified.

Nice values cause the process to run longer with a lower number (requires root), or shorter with a higher number. Values range from -20 to 20.

Parameters:

level (number) – The nice level to set to
pid? (number) – The process ID to modify (must be root or same user)

system.process.releasechild(pid: number, newparent: number): unknown¶

Releases a process to be accepted by another process.

This sets up a change in process parent - the designated new parent will be able to accept the process after releasing, which will cause all child-related events (such as process_complete) to be sent to the new parent.

This function does not change the parent immediately - the new parent has to accept the transfer after releasing.

Parameters:

pid (number) – The ID of the process to release, which must be a child of this process
newparent (number) – The process ID which may accept this process as a child

system.process.acceptchild(pid: number, takestdio?: boolean): unknown¶

Accepts a new child process which was previously released to this one.

This changes the process’s parent after calling. Process events such as process_complete will now be sent to the current process instead of the former parent.

been released to this process by its old parent

Parameters:

pid (number) – The ID of the process to accept, which must have previously
takestdio? (boolean) – If set, the child process will take the stdio handles of the current process

system.process.debug: table¶: Debugging subsystem @section system.process.debug

Module system.process¶

Index¶

API Reference¶

Module `system.process`¶