Ruby: include/ruby/internal/intern/process.h File Reference

Ruby 3.4.1p0 (2024-12-25 revision 48d4efcb85000e1ebae42004e963b5d0cedddcf2)

Functions
process.h File Reference

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"`

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 1555 of file process.c.

Referenced by rb_detach_process(), and rb_proc_times().

## ◆ 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 3020 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 611 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 682 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 1801 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 1198 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 4722 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 4716 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 4587 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 1271 of file process.c.

Referenced by rb_syswait(), and rb_waitpid().