One Hat Cyber Team

View File Name : spawn-i.ri

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"$use 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;;	[4I"env: hash
;TI"2  name => 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"+    :close_others => false  : inherit
;TI"  current directory:
;TI"    :chdir => str
;T;
0o;
;	[
I"FThe <code>cmdname, arg1, ...</code> form does not use the shell. ;TI"BHowever, on different OSes, different things are provided as ;TI"Cbuilt-in commands. An example of this is +'echo'+, which is a ;TI"Ibuilt-in on Windows, but is a normal program on Linux and Mac OS X. ;TI"FThis means that <code>Process.spawn 'echo', '%Path%'</code> will ;TI"Fdisplay the contents of the <tt>%Path%</tt> environment variable ;TI"Gon Windows, but <code>Process.spawn 'echo', '$PATH'</code> prints ;TI" the literal <tt>$PATH</tt>.;T@o;
;	[I"5If a hash is given as +env+, the environment is ;TI"Hupdated by +env+ before <code>exec(2)</code> 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 <code>:unsetenv_others</code> 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 <code>:pgroup</code> 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 <code>:new_pgroup</code> key in +options+ specifies to pass ;TI"N+CREATE_NEW_PROCESS_GROUP+ flag to <code>CreateProcessW()</code> 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"@<code>Process.kill(:SIGINT, pid)</code> 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 <code>:rlimit_</code><em>foo</em> key specifies a resource limit. ;TI"M<em>foo</em> should be one of resource types such as <code>core</code>. ;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 <code>:umask</code> 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"DThe hash keys specifies a file descriptor in the child process ;TI"started by #spawn. ;TI"E:err, 2 and STDERR specifies the standard error stream (stderr).;T@o;
;	[I"GThe hash values specifies a file descriptor in the parent process ;TI"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 <code>:chdir</code> 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 false 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",See 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@EFI"Kernel;TcRDoc::NormalModule00