process.h File Reference

(34098b669c0cbc024cd08e686891f1dfe0a10aaf)

Public APIs related to rb_mProcess. More...

#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/noreturn.h"
#include "ruby/internal/config.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"

Include dependency graph for process.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
VALUE	rb_process_status_wait (rb_pid_t pid, int flags)
	Wait for the specified process to terminate, reap it, and return its status.
void	rb_last_status_set (int status, rb_pid_t pid)
	Sets the "last status", or the $?.
VALUE	rb_last_status_get (void)
	Queries the "last status", or the $?.
int	rb_proc_exec (const char *cmd)
	Executes a shell command.
VALUE	rb_f_exec (int argc, const VALUE *argv)
	Replaces the current process by running the given external command.
rb_pid_t	rb_waitpid (rb_pid_t pid, int *status, int flags)
	Waits for a process, with releasing GVL.
void	rb_syswait (rb_pid_t pid)
	This is a shorthand of rb_waitpid without status and flags.
rb_pid_t	rb_spawn (int argc, const VALUE *argv)
	Identical to rb_f_exec(), except it spawns a child process instead of replacing the current one.
rb_pid_t	rb_spawn_err (int argc, const VALUE *argv, char *errbuf, size_t buflen)
	Identical to rb_spawn(), except you can additionally know the detailed situation in case of abnormal parturitions.
VALUE	rb_proc_times (VALUE _)
	Gathers info about resources consumed by the current process.
VALUE	rb_detach_process (rb_pid_t pid)
	"Detaches" a subprocess.

Detailed Description

Public APIs related to rb_mProcess.

Author

Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright

This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning

Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note

To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file process.h.

Function Documentation

rb_detach_process()

VALUE rb_detach_process

(

rb_pid_t

pid

)

"Detaches" a subprocess.

In POSIX systems every child processes that a process creates must be wait(2)-ed. A child process that died yet has not been waited so far is called a "zombie", which more or less consumes resources. This function automates reclamation of such processes. Once after this function successfully returns you can basically forget about the child process.

Parameters

[in]

pid

Process to wait.

Returns

An instance of rb_cThread which is waitpid(2)-ing pid.

Postcondition

You can just forget about the return value. GC reclaims it.

You can know the exit status by querying #value of the return value (which is a blocking operation).

Definition at line 1451 of file process.c.

Referenced by rb_detach_process().

rb_f_exec()

VALUE rb_f_exec	(	int	argc,
		const VALUE *	argv
	)

Replaces the current process by running the given external command.

This is the implementation of Kernel#exec.

Parameters

[in]	argc	Number of objects in argv.
[in]	argv	Command and its options to execute.

Exceptions

rb_eTypeError	Invalid options e.g. non-String argv.
rb_eArgError	Invalid options e.g. redirection cycle.
rb_eNotImpError	Not implemented e.g. no `setuid(2)`.
rb_eRuntimeError	`Process::UID.switch` in operation.
rb_eSystemCallError	`execve(2)` failed.

Warning

This function doesn't return.

On failure it raises. On success the process is replaced.

Definition at line 2916 of file process.c.

rb_last_status_get()

VALUE rb_last_status_get

(

void

)

Queries the "last status", or the $?.

Return values

RUBY_Qnil	The current thread has no dead children.
otherwise	An instance of Process::Status describing the status of the child that was most recently wait-ed.

Definition at line 610 of file process.c.

Referenced by rb_last_status_get().

rb_last_status_set()

void rb_last_status_set	(	int	status,
		rb_pid_t	pid
	)

Sets the "last status", or the $?.

Parameters

[in]	status	The termination status, as defined in waitpid(3posix).
[in]	pid	The last child of the current process.

Postcondition

$? is updated.

Definition at line 681 of file process.c.

Referenced by rb_last_status_set().

rb_proc_exec()

int rb_proc_exec

(

const char *

cmd

)

Executes a shell command.

Warning

THIS FUNCTION RETURNS on error!

Parameters

[in]

cmd

Passed to the shell.

Return values

-1	Something prevented the command execution.

Postcondition

Upon successful execution this function doesn't return.

In case it returns the errno is set properly.

Definition at line 1697 of file process.c.

Referenced by rb_proc_exec().

rb_proc_times()

VALUE rb_proc_times

(

VALUE

_

)

Gathers info about resources consumed by the current process.

Parameters

[in]

_

Not used. Pass anything.

Returns

An instance of Process::Tms.

rb_process_status_wait()

VALUE rb_process_status_wait	(	rb_pid_t	pid,
		int	flags
	)

Wait for the specified process to terminate, reap it, and return its status.

Parameters

[in]	pid	The process ID to wait for.
[in]	flags	The flags to pass to waitpid(2).

Returns

VALUE An instance of Process::Status.

Definition at line 1094 of file process.c.

Referenced by rb_process_status_wait(), and rb_waitpid().

rb_spawn()

rb_pid_t rb_spawn	(	int	argc,
		const VALUE *	argv
	)

Identical to rb_f_exec(), except it spawns a child process instead of replacing the current one.

Parameters

[in]	argc	Number of objects in argv.
[in]	argv	Command and its options to execute.

Exceptions

rb_eTypeError	Invalid options e.g. non-String argv.
rb_eArgError	Invalid options e.g. redirection cycle.
rb_eNotImpError	Not implemented e.g. no `setuid(2)`.
rb_eRuntimeError	`Process::UID.switch` in operation.

Return values

-1	Child process died for some reason.
otherwise	The ID of the born child.

Definition at line 4618 of file process.c.

Referenced by rb_spawn().

rb_spawn_err()

rb_pid_t rb_spawn_err	(	int	argc,
		const VALUE *	argv,
		char *	errbuf,
		size_t	buflen
	)

Identical to rb_spawn(), except you can additionally know the detailed situation in case of abnormal parturitions.

Parameters

[in]	argc	Number of objects in argv.
[in]	argv	Command and its options to execute.
[out]	errbuf	Error description write-back buffer.
[in]	buflen	Number of bytes of errbuf, including NUL.

Exceptions

rb_eTypeError	Invalid options e.g. non-String argv.
rb_eArgError	Invalid options e.g. redirection cycle.
rb_eNotImpError	Not implemented e.g. no `setuid(2)`.
rb_eRuntimeError	`Process::UID.switch` in operation.

Return values

-1	Child process died for some reason.
otherwise	The ID of the born child.

Postcondition

In case of -1, at most buflen bytes of the reason why is written back to errbuf.

Definition at line 4612 of file process.c.

Referenced by rb_spawn_err().

rb_syswait()

void rb_syswait

(

rb_pid_t

pid

)

This is a shorthand of rb_waitpid without status and flags.

It has been like this since the very beginning. The initial revision already did the same thing. Not sure why, then, it has been named syswait. AFAIK this is different from how wait(3posix) works.

Parameters

[in]

pid

Passed to rb_waitpid().

Definition at line 4483 of file process.c.

rb_waitpid()

rb_pid_t rb_waitpid	(	rb_pid_t	pid,
		int *	status,
		int	flags
	)

Waits for a process, with releasing GVL.

Parameters

[in]	pid	Process ID.
[out]	status	The wait status is filled back.
[in]	flags	Wait options.

Return values

-1	System call failed, errno set.
0	WNOHANG but no waitable children.
otherwise	A process ID that was wait()-ed.

Postcondition

Upon successful return status is updated to have the process' status.

Note

status can be NULL.

The arguments are passed through to underlying system call(s). Can have special meanings. For instance passing (rb_pid_t)-1 to pid means it waits for any processes, under POSIX-compliant situations.

Definition at line 1167 of file process.c.

Referenced by rb_syswait(), and rb_waitpid().