diff options
Diffstat (limited to 'include/ruby/internal/intern/process.h')
| -rw-r--r-- | include/ruby/internal/intern/process.h | 282 |
1 files changed, 0 insertions, 282 deletions
diff --git a/include/ruby/internal/intern/process.h b/include/ruby/internal/intern/process.h deleted file mode 100644 index cfa5e13162..0000000000 --- a/include/ruby/internal/intern/process.h +++ /dev/null @@ -1,282 +0,0 @@ -#ifndef RBIMPL_INTERN_PROCESS_H /*-*-C++-*-vi:se ft=cpp:*/ -#define RBIMPL_INTERN_PROCESS_H -/** - * @file - * @author Ruby developers <ruby-core@ruby-lang.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. - * @brief Public APIs related to ::rb_mProcess. - */ -#include "ruby/internal/attr/nonnull.h" -#include "ruby/internal/attr/noreturn.h" -#include "ruby/internal/config.h" /* rb_pid_t is defined here. */ -#include "ruby/internal/dllexport.h" -#include "ruby/internal/value.h" - -RBIMPL_SYMBOL_EXPORT_BEGIN() - -/* process.c */ - -/** - * Wait for the specified process to terminate, reap it, and return its status. - * - * @param[in] pid The process ID to wait for. - * @param[in] flags The flags to pass to waitpid(2). - * @return VALUE An instance of Process::Status. - */ -VALUE rb_process_status_wait(rb_pid_t pid, int flags); - -/** - * Sets the "last status", or the `$?`. - * - * @param[in] status The termination status, as defined in `waitpid(3posix)`. - * @param[in] pid The last child of the current process. - * @post `$?` is updated. - */ -void rb_last_status_set(int status, rb_pid_t pid); - -/** - * Queries the "last status", or the `$?`. - * - * @retval RUBY_Qnil The current thread has no dead children. - * @retval otherwise An instance of Process::Status describing the status of - * the child that was most recently `wait`-ed. - */ -VALUE rb_last_status_get(void); - -RBIMPL_ATTR_NONNULL(()) -/** - * Executes a shell command. - * - * @warning THIS FUNCTION RETURNS on error! - * @param[in] cmd Passed to the shell. - * @retval -1 Something prevented the command execution. - * @post Upon successful execution this function doesn't return. - * @post In case it returns the `errno` is set properly. - */ -int rb_proc_exec(const char *cmd); - -RBIMPL_ATTR_NORETURN() -/** - * Replaces the current process by running the given external command. This is - * the implementation of `Kernel#exec`. - * - * @param[in] argc Number of objects in `argv`. - * @param[in] argv Command and its options to execute. - * @exception rb_eTypeError Invalid options e.g. non-String argv. - * @exception rb_eArgError Invalid options e.g. redirection cycle. - * @exception rb_eNotImpError Not implemented e.g. no `setuid(2)`. - * @exception rb_eRuntimeError `Process::UID.switch` in operation. - * @exception rb_eSystemCallError `execve(2)` failed. - * @warning This function doesn't return. - * @warning On failure it raises. On success the process is replaced. - * - * @internal - * - * @shyouhei have to say that the rdoc for `Kernel#exec` is fairly incomplete. - * AFAIK this function ultimately takes the following signature: - * - * ```rbs - * type boolx = bool | nil # != `boolish` - * - * type rlim_t = Integer # rlim_cur - * | [ Integer, Integer ] # rlim_cur, rlim_max - * - * type uid_t = String # e.g. "root" - * | Integer # e.g. 0 - * - * type gid_t = String # e.g. "wheel" - * | Integer # e.g. 0 - * - * type fmode = String # e.g. "rb" - * | Integer # e.g. O_RDONLY | O_BINARY - * - * type mode_t = Integer # e.g. 0644 - * - * type pgrp = true # Creates a dedicated pgroup - * | 0 # ditto - * | nil # Uses the current one - * | Integer # Uses this specific pgroup - * - * type fd = :in # STDIN - * | :out # STDOUT - * | :err # STDERR - * | IO # This specific IO - * | Integer # A file descriptor of this # - * - * type src = fd | [ fd ] - * type dst = :close # Intuitive - * | fd # Intuitive - * | String # Open a file at this path - * | [ String ] # ... using O_RDONLY - * | [ String, fmode ] # ... using this mode - * | [ String, fmode, mode_t ] # ... with a permission - * | [ :child, fd ] # fd of child side - * - * type redir = Hash[ src, dst ] - * - * # ---- - * - * # Key-value pair of environment variables - * type envp = Hash[ String, String ] - * - * # Actual name (and the name passed to the subprocess if any) - * type arg0 = String | [ String, String ] - * - * # Arbitrary string parameters - * type argv = String - * - * # Exec options: - * type argh = redir | { - * chdir: String, # Working directory - * close_others: boolx, # O_CLOEXEC like behaviour - * gid: gid_t, # setegid(2) - * pgrooup: pgrp, # setpgrp(2) - * rlimit_as: rlim_t, # setrlimit(2) - * rlimit_core: rlim_t, # ditto - * rlimit_cpu: rlim_t, # ditto - * rlimit_data: rlim_t, # ditto - * rlimit_fsize: rlim_t, # ditto - * rlimit_memlock: rlim_t, # ditto - * rlimit_msgqueue: rlim_t, # ditto - * rlimit_nice: rlim_t, # ditto - * rlimit_nofile: rlim_t, # ditto - * rlimit_nproc: rlim_t, # ditto - * rlimit_rss: rlim_t, # ditto - * rlimit_rtprio: rlim_t, # ditto - * rlimit_rttime: rlim_t, # ditto - * rlimit_sbsize: rlim_t, # ditto - * rlimit_sigpending: rlim_t, # ditto - * rlimit_stack: rlim_t, # ditto - * uid: uid_t, # seteuid(2) - * umask: mode_t, # umask(2) - * unsetenv_others: boolx # Unset everything except the passed envp - * } - * - * # ==== - * - * class Kernel - * def self?.exec - * : ( arg0 cmd, *argv args ) -> void - * | ( arg0 cmd, *argv args, argh opts) -> void - * | (envp env, arg0 cmd, *argv args ) -> void - * | (envp env, arg0 cmd, *argv args, argh opts) -> void - * end - * ``` - */ -VALUE rb_f_exec(int argc, const VALUE *argv); - -/** - * Waits for a process, with releasing GVL. - * - * @param[in] pid Process ID. - * @param[out] status The wait status is filled back. - * @param[in] flags Wait options. - * @retval -1 System call failed, errno set. - * @retval 0 WNOHANG but no waitable children. - * @retval otherwise A process ID that was `wait()`-ed. - * @post Upon successful return `status` is updated to have the process' - * status. - * @note `status` can be NULL. - * @note 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. - */ -rb_pid_t rb_waitpid(rb_pid_t pid, int *status, int flags); - -/** - * 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. - * - * @param[in] pid Passed to rb_waitpid(). - */ -void rb_syswait(rb_pid_t pid); - -/** - * Identical to rb_f_exec(), except it spawns a child process instead of - * replacing the current one. - * - * @param[in] argc Number of objects in `argv`. - * @param[in] argv Command and its options to execute. - * @exception rb_eTypeError Invalid options e.g. non-String argv. - * @exception rb_eArgError Invalid options e.g. redirection cycle. - * @exception rb_eNotImpError Not implemented e.g. no `setuid(2)`. - * @exception rb_eRuntimeError `Process::UID.switch` in operation. - * @retval -1 Child process died for some reason. - * @retval otherwise The ID of the born child. - * - * @internal - * - * This is _really_ identical to rb_f_exec() until ultimately calling the - * system call. Almost everything are shared among these two (and - * rb_f_system()). - */ -rb_pid_t rb_spawn(int argc, const VALUE *argv); - -/** - * Identical to rb_spawn(), except you can additionally know the detailed - * situation in case of abnormal parturitions. - * - * @param[in] argc Number of objects in `argv`. - * @param[in] argv Command and its options to execute. - * @param[out] errbuf Error description write-back buffer. - * @param[in] buflen Number of bytes of `errbuf`, including NUL. - * @exception rb_eTypeError Invalid options e.g. non-String argv. - * @exception rb_eArgError Invalid options e.g. redirection cycle. - * @exception rb_eNotImpError Not implemented e.g. no `setuid(2)`. - * @exception rb_eRuntimeError `Process::UID.switch` in operation. - * @retval -1 Child process died for some reason. - * @retval otherwise The ID of the born child. - * @post In case of `-1`, at most `buflen` bytes of the reason why is - * written back to `errbuf`. - */ -rb_pid_t rb_spawn_err(int argc, const VALUE *argv, char *errbuf, size_t buflen); - -/** - * Gathers info about resources consumed by the current process. - * - * @param[in] _ Not used. Pass anything. - * @return An instance of `Process::Tms`. - * - * @internal - * - * This function might or might not exist depending on `./configure` result. - * It must be a portability hell. Better not use. - */ -VALUE rb_proc_times(VALUE _); - -/** - * "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. - * - * @param[in] pid Process to wait. - * @return An instance of ::rb_cThread which is `waitpid(2)`-ing `pid`. - * @post You can just forget about the return value. GC reclaims it. - * @post You can know the exit status by querying `#value` of the - * return value (which is a blocking operation). - */ -VALUE rb_detach_process(rb_pid_t pid); - -RBIMPL_SYMBOL_EXPORT_END() - -#endif /* RBIMPL_INTERN_PROCESS_H */ |