U:RDoc::AnyMethod[iI"
spawn:ETI"Kernel#spawn;TF: publico:RDoc::Markup::Document: @parts[\o: RDoc::Markup::Paragraph; [I"9spawn executes specified command and return its pid.;To: RDoc::Markup::BlankLine o:RDoc::Markup::Verbatim; [
I"3pid = spawn("tar xf ruby-2.0.0-p195.tar.bz2")
;TI"Process.wait pid
;TI"
;TI"9pid = spawn(RbConfig.ruby, "-eputs'Hello, world!'")
;TI"Process.wait pid
;T: @format0o;
; [I"QThis method is similar to Kernel#system but it doesn't wait for the command ;TI"to finish.;T@o;
; [ I" The parent process should ;TI".use Process.wait to collect ;TI",the termination status of its child or ;TI"1use Process.detach to register ;TI""disinterest in their status; ;TI"Eotherwise, the operating system may accumulate zombie processes.;T@o;
; [I">spawn has bunch of options to specify process attributes:;T@o; ; [ val : set the environment variable
;TI"4 name => nil : unset the environment variable
;TI"
;TI"A the keys and the values except for +nil+ must be strings.
;TI"command...:
;TI"_ commandline : command line string which is passed to the standard shell
;TI"‚ cmdname, arg1, ... : command name and one or more arguments (This form does not use the shell. See below for caveats.)
;TI"a [cmdname, argv0], arg1, ... : command name, argv[0] and zero or more arguments (no shell)
;TI"options: hash
;TI"' clearing environment variables:
;TI"Z :unsetenv_others => true : clear environment variables except specified by env
;TI"< :unsetenv_others => false : don't clear (default)
;TI" process group:
;TI"9 :pgroup => true or 0 : make a new process group
;TI"A :pgroup => pgid : join the specified process group
;TI"I :pgroup => nil : don't change the process group (default)
;TI". create new process group: Windows only
;TI"[ :new_pgroup => true : the new process is the root process of a new process group
;TI"K :new_pgroup => false : don't create a new process group (default)
;TI"U resource limit: resourcename is core, cpu, data, etc. See Process.setrlimit.
;TI"' :rlimit_resourcename => limit
;TI"8 :rlimit_resourcename => [cur_limit, max_limit]
;TI" umask:
;TI" :umask => int
;TI" redirection:
;TI" key:
;TI"E FD : single file descriptor in child process
;TI"G [FD, FD, ...] : multiple file descriptor in child process
;TI" value:
;TI"Y FD : redirect to the file descriptor in parent process
;TI"V string : redirect to file with open(string, "r" or "w")
;TI"X [string] : redirect to file with open(string, File::RDONLY)
;TI"[ [string, open_mode] : redirect to file with open(string, open_mode, 0644)
;TI"[ [string, open_mode, perm] : redirect to file with open(string, open_mode, perm)
;TI"R [:child, FD] : redirect to the redirected file descriptor
;TI"R :close : close the file descriptor in child process
;TI" FD is one of follows
;TI"G :in : the file descriptor 0 which is the standard input
;TI"H :out : the file descriptor 1 which is the standard output
;TI"G :err : the file descriptor 2 which is the standard error
;TI"B integer : the file descriptor of specified the integer
;TI"@ io : the file descriptor specified as io.fileno
;TI"` file descriptor inheritance: close non-redirected non-standard fds (3, 4, 5, ...) or not
;TI"0 :close_others => true : don't inherit
;TI" current directory:
;TI" :chdir => str
;TI"
;TI"F The 'cmdname, arg1, ...' form does not use the shell. However,
;TI"D on different OSes, different things are provided as built-in
;TI"C commands. An example of this is 'echo', which is a built-in
;TI"B on Windows, but is a normal program on Linux and Mac OS X.
;TI"E This means that `Process.spawn 'echo', '%Path%'` will display
;TI"E the contents of the `%Path%` environment variable on Windows,
;TI"G but `Process.spawn 'echo', '$PATH'` prints the literal '$PATH'.
;T;
0o;
; [I"5If a hash is given as +env+, the environment is ;TI"Hupdated by +env+ before exec(2) in the child process. ;TI"FIf a pair in +env+ has nil as the value, the variable is deleted.;T@o; ; [I"%# set FOO as BAR and unset BAZ.
;TI"6pid = spawn({"FOO"=>"BAR", "BAZ"=>nil}, command)
;T;
0o;
; [I"&If a hash is given as +options+, ;TI"it specifies ;TI"process group, ;TI" create new process group, ;TI"resource limit, ;TI"current directory, ;TI"umask and ;TI"&redirects for the child process. ;TI">Also, it can be specified to clear environment variables.;T@o;
; [I"BThe :unsetenv_others key in +options+ specifies ;TI"Cto clear environment variables, other than specified by +env+.;T@o; ; [I"Lpid = spawn(command, :unsetenv_others=>true) # no environment variable
;TI"Mpid = spawn({"FOO"=>"BAR"}, command, :unsetenv_others=>true) # FOO only
;T;
0o;
; [
I"JThe :pgroup key in +options+ specifies a process group. ;TI"OThe corresponding value should be true, zero, a positive integer, or nil. ;TI"Ttrue and zero cause the process to be a process leader of a new process group. ;TI"XA non-zero positive integer causes the process to join the provided process group. ;TI"TThe default value, nil, causes the process to remain in the same process group.;T@o; ; [I":pid = spawn(command, :pgroup=>true) # process leader
;TI"Ipid = spawn(command, :pgroup=>10) # belongs to the process group 10
;T;
0o;
; [ I"EThe :new_pgroup key in +options+ specifies to pass ;TI"N+CREATE_NEW_PROCESS_GROUP+ flag to CreateProcessW() that is ;TI"3Windows API. This option is only for Windows. ;TI"Ntrue means the new process is the root process of the new process group. ;TI"EThe new process has CTRL+C disabled. This flag is necessary for ;TI"@Process.kill(:SIGINT, pid) on the subprocess. ;TI"%:new_pgroup is false by default.;T@o; ; [I"Bpid = spawn(command, :new_pgroup=>true) # new process group
;TI"Cpid = spawn(command, :new_pgroup=>false) # same process group
;T;
0o;
; [
I"KThe :rlimit_foo key specifies a resource limit. ;TI"Mfoo should be one of resource types such as core. ;TI"PThe corresponding value should be an integer or an array which have one or ;TI"Atwo integers: same as cur_limit and max_limit arguments for ;TI"Process.setrlimit.;T@o; ; [ I")cur, max = Process.getrlimit(:CORE)
;TI"Kpid = spawn(command, :rlimit_core=>[0,max]) # disable core temporary.
;TI"@pid = spawn(command, :rlimit_core=>max) # enable core dump
;TI">pid = spawn(command, :rlimit_core=>0) # never dump core.
;T;
0o;
; [I"BThe :umask key in +options+ specifies the umask.;T@o; ; [I"'pid = spawn(command, :umask=>077)
;T;
0o;
; [I"VThe :in, :out, :err, an integer, an IO and an array key specifies a redirection. ;TI"AThe redirection maps a file descriptor in the child process.;T@o;
; [I">For example, stderr can be merged into stdout as follows:;T@o; ; [ I"&pid = spawn(command, :err=>:out)
;TI" pid = spawn(command, 2=>1)
;TI"(pid = spawn(command, STDERR=>:out)
;TI"*pid = spawn(command, STDERR=>STDOUT)
;T;
0o;
; [I"/The hash keys specifies a file descriptor ;TI"9in the child process started by spawn. ;TI"E:err, 2 and STDERR specifies the standard error stream (stderr).;T@o;
; [I"1The hash values specifies a file descriptor ;TI"=in the parent process which invokes spawn. ;TI"F:out, 1 and STDOUT specifies the standard output stream (stdout).;T@o;
; [I"In the above example, ;TI"@the standard output in the child process is not specified. ;TI"0So it is inherited from the parent process.;T@o;
; [I"LThe standard input stream (stdin) can be specified by :in, 0 and STDIN.;T@o;
; [I"1A filename can be specified as a hash value.;T@o; ; [
I"8pid = spawn(command, :in=>"/dev/null") # read mode
;TI":pid = spawn(command, :out=>"/dev/null") # write mode
;TI"4pid = spawn(command, :err=>"log") # write mode
;TI"Bpid = spawn(command, [:out, :err]=>"/dev/null") # write mode
;TI"6pid = spawn(command, 3=>"/dev/null") # read mode
;T;
0o;
; [I"6For stdout and stderr (and combination of them), ;TI"!it is opened in write mode. ;TI"!Otherwise read mode is used.;T@o;
; [I"FFor specifying flags and permission of file creation explicitly, ;TI" an array is used instead.;T@o; ; [
I"@pid = spawn(command, :in=>["file"]) # read mode is assumed
;TI".pid = spawn(command, :in=>["file", "r"])
;TI"=pid = spawn(command, :out=>["log", "w"]) # 0644 assumed
;TI"4pid = spawn(command, :out=>["log", "w", 0600])
;TI"Tpid = spawn(command, :out=>["log", File::WRONLY|File::EXCL|File::CREAT, 0600])
;T;
0o;
; [
I";The array specifies a filename, flags and permission. ;TI".The flags can be a string or an integer. ;TI">If the flags is omitted or nil, File::RDONLY is assumed. ;TI"*The permission should be an integer. ;TI":If the permission is omitted or nil, 0644 is assumed.;T@o;
; [I"BIf an array of IOs and integers are specified as a hash key, ;TI"%all the elements are redirected.;T@o; ; [I"4# stdout and stderr is redirected to log file.
;TI"+# The file "log" is opened just once.
;TI"6pid = spawn(command, [:out, :err]=>["log", "w"])
;T;
0o;
; [ I"EAnother way to merge multiple file descriptors is [:child, fd]. ;TI"C\[:child, fd] means the file descriptor in the child process. ;TI" This is different from fd. ;TI"NFor example, :err=>:out means redirecting child stderr to parent stdout. ;TI"NBut :err=>[:child, :out] means redirecting child stderr to child stdout. ;TI"IThey differ if stdout is redirected in the child process as follows.;T@o; ; [I"4# stdout and stderr is redirected to log file.
;TI"+# The file "log" is opened just once.
;TI"Dpid = spawn(command, :out=>["log", "w"], :err=>[:child, :out])
;T;
0o;
; [I"J\[:child, :out] can be used to merge stderr into stdout in IO.popen. ;TI"LIn this case, IO.popen redirects stdout to a pipe in the child process ;TI"5and [:child, :out] refers the redirected stdout.;T@o; ; [I"Qio = IO.popen(["sh", "-c", "echo out; echo err >&2", :err=>[:child, :out]])
;TI" p io.read #=> "out\nerr\n"
;T;
0o;
; [I"NThe :chdir key in +options+ specifies the current directory.;T@o; ; [I".pid = spawn(command, :chdir=>"/var/tmp")
;T;
0o;
; [
I"Gspawn closes all non-standard unspecified descriptors by default. ;TI"0The "standard" descriptors are 0, 1 and 2. ;TI"9This behavior is specified by :close_others option. ;TI"E:close_others doesn't affect the standard descriptors which are ;TI"3closed only if :close is specified explicitly.;T@o; ; [I"Lpid = spawn(command, :close_others=>true) # close 3,4,5,... (default)
;TI"Hpid = spawn(command, :close_others=>false) # don't close 3,4,5,...
;T;
0o;
; [I"=:close_others is true by default for spawn and IO.popen.;T@o;
; [I"FNote that fds which close-on-exec flag is already set are closed ;TI"(regardless of :close_others option.;T@o;
; [I"2So IO.pipe and spawn can be used as IO.popen.;T@o; ; [ I"(# similar to r = IO.popen(command)
;TI"r, w = IO.pipe
;TI"Lpid = spawn(command, :out=>w) # r, w is closed in the child process.
;TI"
w.close
;T;
0o;
; [I"D:close is specified as a hash value to close a fd individually.;T@o; ; [I"f = open(foo)
;TI":system(command, f=>:close) # don't inherit f.
;T;
0o;
; [I"0If a file descriptor need to be inherited, ;TI"io=>io can be used.;T@o; ; [ I"9# valgrind has --log-fd option for log destination.
;TI"F# log_w=>log_w indicates log_w.fileno inherits to child process.
;TI" log_r, log_w = IO.pipe
;TI"Tpid = spawn("valgrind", "--log-fd=#{log_w.fileno}", "echo", "a", log_w=>log_w)
;TI"log_w.close
;TI"p log_r.read
;T;
0o;
; [I"6It is also possible to exchange file descriptors.;T@o; ; [I"2pid = spawn(command, :out=>:err, :err=>:out)
;T;
0o;
; [
I"BThe hash keys specify file descriptors in the child process. ;TI"GThe hash values specifies file descriptors in the parent process. ;TI":So the above specifies exchanging stdout and stderr. ;TI"NInternally, +spawn+ uses an extra file descriptor to resolve such cyclic ;TI" file descriptor mapping.;T@o;
; [I"9See Kernel.exec for the standard shell.;T:
@fileI"process.c;T:0@omit_headings_from_table_of_contents_below0I"kspawn([env,] command... [,options]) -> pid
Process.spawn([env,] command... [,options]) -> pid
;T0[ I" (*args);T@CFI" Kernel;TcRDoc::NormalModule00