diff options
-rw-r--r-- | io.c | 426 | ||||
-rw-r--r-- | process.c | 320 |
2 files changed, 378 insertions, 368 deletions
@@ -431,17 +431,17 @@ rb_io_fwrite(ptr, len, f) /* * call-seq: * ios.write(string) => integer - * + * * Writes the given string to <em>ios</em>. The stream must be opened * for writing. If the argument is not a string, it will be converted * to a string using <code>to_s</code>. Returns the number of bytes * written. - * + * * count = $stdout.write( "This is a test\n" ) * puts "That was #{count} bytes of data" - * + * * <em>produces:</em> - * + * * This is a test * That was 15 bytes of data */ @@ -491,15 +491,15 @@ rb_io_write(io, str) /* * call-seq: * ios << obj => ios - * + * * String Output---Writes <i>obj</i> to <em>ios</em>. * <i>obj</i> will be converted to a string using * <code>to_s</code>. - * + * * $stdout << "Hello " << "world!\n" - * + * * <em>produces:</em> - * + * * Hello world! */ @@ -515,16 +515,16 @@ rb_io_addstr(io, str) /* * call-seq: * ios.flush => ios - * + * * Flushes any buffered data within <em>ios</em> to the underlying * operating system (note that this is Ruby internal buffering only; * the OS may buffer the data as well). - * + * * $stdout.print "no newline" * $stdout.flush - * + * * <em>produces:</em> - * + * * no newline */ @@ -549,9 +549,9 @@ rb_io_flush(io) * call-seq: * ios.pos => integer * ios.tell => integer - * + * * Returns the current offset (in bytes) of <em>ios</em>. - * + * * f = File.new("testfile") * f.pos #=> 0 * f.gets #=> "This is line one\n" @@ -590,19 +590,19 @@ rb_io_seek(io, offset, whence) /* * call-seq: * ios.seek(amount, whence=SEEK_SET) -> 0 - * + * * Seeks to a given offset <i>anInteger</i> in the stream according to * the value of <i>whence</i>: * * IO::SEEK_CUR | Seeks to _amount_ plus current position * --------------+---------------------------------------------------- - * IO::SEEK_END | Seeks to _amount_ plus end of stream (you probably + * IO::SEEK_END | Seeks to _amount_ plus end of stream (you probably * | want a negative value for _amount_) * --------------+---------------------------------------------------- * IO::SEEK_SET | Seeks to the absolute location given by _amount_ * * Example: - * + * * f = File.new("testfile") * f.seek(-13, IO::SEEK_END) #=> 0 * f.readline #=> "And so on...\n" @@ -627,9 +627,9 @@ rb_io_seek_m(argc, argv, io) /* * call-seq: * ios.pos = integer => 0 - * + * * Seeks to the given position (in bytes) in <em>ios</em>. - * + * * f = File.new("testfile") * f.pos = 17 * f.gets #=> "This is line two\n" @@ -653,10 +653,10 @@ rb_io_set_pos(io, offset) /* * call-seq: * ios.rewind => 0 - * + * * Positions <em>ios</em> to the beginning of input, resetting * <code>lineno</code> to zero. - * + * * f = File.new("testfile") * f.readline #=> "This is line one\n" * f.rewind #=> 0 @@ -685,10 +685,10 @@ rb_io_rewind(io) * call-seq: * ios.eof => true or false * ios.eof? => true or false - * + * * Returns true if <em>ios</em> is at end of file. The stream must be * opened for reading or an <code>IOError</code> will be raised. - * + * * f = File.new("testfile") * dummy = f.readlines * f.eof #=> true @@ -722,12 +722,12 @@ rb_io_eof(io) /* * call-seq: * ios.sync => true or false - * + * * Returns the current ``sync mode'' of <em>ios</em>. When sync mode is * true, all output is immediately flushed to the underlying operating * system and is not buffered by Ruby internally. See also * <code>IO#fsync</code>. - * + * * f = File.new("testfile") * f.sync #=> false */ @@ -745,15 +745,15 @@ rb_io_sync(io) /* * call-seq: * ios.sync = boolean => boolean - * + * * Sets the ``sync mode'' to <code>true</code> or <code>false</code>. * When sync mode is true, all output is immediately flushed to the * underlying operating system and is not buffered internally. Returns * the new state. See also <code>IO#fsync</code>. - * + * * f = File.new("testfile") * f.sync = true - * + * * <em>(produces no output)</em> */ @@ -776,7 +776,7 @@ rb_io_set_sync(io, mode) /* * call-seq: * ios.fsync => 0 or nil - * + * * Immediately writes all buffered data in <em>ios</em> to disk. * Returns <code>nil</code> if the underlying operating system does not * support <em>fsync(2)</em>. Note that <code>fsync</code> differs from @@ -810,10 +810,10 @@ rb_io_fsync(io) * call-seq: * ios.fileno => fixnum * ios.to_i => fixnum - * + * * Returns an integer representing the numeric file descriptor for * <em>ios</em>. - * + * * $stdin.fileno #=> 0 * $stdout.fileno #=> 1 */ @@ -834,19 +834,19 @@ rb_io_fileno(io) /* * call-seq: * ios.pid => fixnum - * + * * Returns the process ID of a child process associated with * <em>ios</em>. This will be set by <code>IO::popen</code>. - * + * * pipe = IO.popen("-") * if pipe * $stderr.puts "In parent, child pid is #{pipe.pid}" * else * $stderr.puts "In child, pid is #{$$}" * end - * + * * <em>produces:</em> - * + * * In child, pid is 26209 * In parent, child pid is 26209 */ @@ -895,7 +895,7 @@ rb_io_inspect(obj) /* * call-seq: * ios.to_io -> ios - * + * * Returns <em>ios</em>. */ @@ -1043,13 +1043,13 @@ read_all(fptr, siz, str) /* * call-seq: * ios.read([integer [, buffer]]) => string, buffer, or nil - * + * * Reads at most <i>integer</i> bytes from the I/O stream, or to the * end of file if <i>integer</i> is omitted or is <code>nil</code>. * If the optional <i>buffer</i> argument is present, it must reference * a String, which will receive the data. Returns <code>nil</code> * if called at end of file. - * + * * f = File.new("testfile") * f.read(16) #=> "This is line one" */ @@ -1335,7 +1335,7 @@ rb_io_gets(io) /* * call-seq: * ios.gets(sep_string=$/) => string or nil - * + * * Reads the next ``line'' from the I/O stream; lines are separated by * <i>sep_string</i>. A separator of <code>nil</code> reads the entire * contents, and a zero-length separator reads the input a paragraph at @@ -1344,7 +1344,7 @@ rb_io_gets(io) * will be raised. The line read in will be returned and also assigned * to <code>$_</code>. Returns <code>nil</code> if called at end of * file. - * + * * File.new("testfile").gets #=> "This is line one\n" * $_ #=> "This is line one\n" */ @@ -1374,14 +1374,14 @@ rb_io_gets_m(argc, argv, io) /* * call-seq: * ios.lineno => integer - * + * * Returns the current line number in <em>ios</em>. The stream must be * opened for reading. <code>lineno</code> counts the number of times * <code>gets</code> is called, rather than the number of newlines * encountered. The two values will differ if <code>gets</code> is * called with a separator other than newline. See also the * <code>$.</code> variable. - * + * * f = File.new("testfile") * f.lineno #=> 0 * f.gets #=> "This is line one\n" @@ -1404,10 +1404,10 @@ rb_io_lineno(io) /* * call-seq: * ios.lineno = integer => integer - * + * * Manually sets the current line number to the given value. * <code>$.</code> is updated only on the next read. - * + * * f = File.new("testfile") * f.gets #=> "This is line one\n" * $. #=> 1 @@ -1458,7 +1458,7 @@ argf_lineno() /* * call-seq: * ios.readline(sep_string=$/) => string - * + * * Reads a line as with <code>IO#gets</code>, but raises an * <code>EOFError</code> on end of file. */ @@ -1480,14 +1480,14 @@ rb_io_readline(argc, argv, io) /* * call-seq: * ios.readlines(sep_string=$/) => array - * + * * Reads all of the lines in <em>ios</em>, and returns them in * <i>anArray</i>. Lines are separated by the optional * <i>sep_string</i>. If <i>set_string</i> is <code>nil</code>, the * rest of the stream is returned as a single record. * The stream must be opened for reading or an * <code>IOError</code> will be raised. - * + * * f = File.new("testfile") * f.readlines[0] #=> "This is line one\n" */ @@ -1520,16 +1520,16 @@ rb_io_readlines(argc, argv, io) * call-seq: * ios.each(sep_string=$/) {|line| block } => ios * ios.each_line(sep_string=$/) {|line| block } => ios - * + * * Executes the block for every line in <em>ios</em>, where lines are * separated by <i>sep_string</i>. <em>ios</em> must be opened for * reading or an <code>IOError</code> will be raised. - * + * * f = File.new("testfile") * f.each {|line| puts "#{f.lineno}: #{line}" } - * + * * <em>produces:</em> - * + * * 1: This is line one * 2: This is line two * 3: This is line three @@ -1562,11 +1562,11 @@ rb_io_each_line(argc, argv, io) /* * call-seq: * ios.each_byte {|byte| block } => ios - * + * * Calls the given block once for each byte (0..255) in <em>ios</em>, * passing the byte as an argument. The stream must be opened for * reading or an <code>IOError</code> will be raised. - * + * * f = File.new("testfile") * checksum = 0 * f.each_byte {|x| checksum ^= x } #=> #<File:testfile> @@ -1608,10 +1608,10 @@ rb_io_each_byte(io) /* * call-seq: * ios.getc => fixnum or nil - * + * * Gets the next 8-bit byte (0..255) from <em>ios</em>. Returns * <code>nil</code> if called at end of file. - * + * * f = File.new("testfile") * f.getc #=> 84 * f.getc #=> 104 @@ -1666,7 +1666,7 @@ rb_getc(f) /* * call-seq: * ios.readchar => fixnum - * + * * Reads a character as with <code>IO#getc</code>, but raises an * <code>EOFError</code> on end of file. */ @@ -1686,13 +1686,13 @@ rb_io_readchar(io) /* * call-seq: * ios.ungetc(integer) => nil - * + * * Pushes back one character (passed as a parameter) onto <em>ios</em>, * such that a subsequent buffered read will return it. Only one character * may be pushed back before a subsequent read operation (that is, * you will be able to read only the last of several characters that have been pushed * back). Has no effect with unbuffered reads (such as <code>IO#sysread</code>). - * + * * f = File.new("testfile") #=> #<File:testfile> * c = f.getc #=> 84 * f.ungetc(c) #=> nil @@ -1721,10 +1721,10 @@ rb_io_ungetc(io, c) * call-seq: * ios.isatty => true or false * ios.tty? => true or false - * + * * Returns <code>true</code> if <em>ios</em> is associated with a * terminal device (tty), <code>false</code> otherwise. - * + * * File.new("testfile").isatty #=> false * File.new("/dev/tty").isatty #=> true */ @@ -1842,7 +1842,7 @@ rb_io_close(io) /* * call-seq: * ios.close => nil - * + * * Closes <em>ios</em> and flushes any pending writes to the operating * system. The stream is unavailable for any further data operations; * an <code>IOError</code> is raised if such an attempt is made. I/O @@ -1872,11 +1872,11 @@ io_close(io) /* * call-seq: * ios.closed? => true or false - * + * * Returns <code>true</code> if <em>ios</em> is completely closed (for * duplex streams, both reader and writer), <code>false</code> * otherwise. - * + * * f = File.new("testfile") * f.close #=> nil * f.closed? #=> true @@ -1901,17 +1901,17 @@ rb_io_closed(io) /* * call-seq: * ios.close_read => nil - * + * * Closes the read end of a duplex I/O stream (i.e., one that contains * both a read and a write stream, such as a pipe). Will raise an * <code>IOError</code> if the stream is not duplexed. - * + * * f = IO.popen("/bin/sh","r+") * f.close_read * f.readlines - * + * * <em>produces:</em> - * + * * prog.rb:3:in `readlines': not opened for reading (IOError) * from prog.rb:3 */ @@ -1945,17 +1945,17 @@ rb_io_close_read(io) /* * call-seq: * ios.close_write => nil - * + * * Closes the write end of a duplex I/O stream (i.e., one that contains * both a read and a write stream, such as a pipe). Will raise an * <code>IOError</code> if the stream is not duplexed. - * + * * f = IO.popen("/bin/sh","r+") * f.close_write * f.print "nowhere" - * + * * <em>produces:</em> - * + * * prog.rb:3:in `write': not opened for writing (IOError) * from prog.rb:3:in `print' * from prog.rb:3 @@ -1989,11 +1989,11 @@ rb_io_close_write(io) /* * call-seq: * ios.sysseek(offset, whence=SEEK_SET) => integer - * + * * Seeks to a given <i>offset</i> in the stream according to the value * of <i>whence</i> (see <code>IO#seek</code> for values of * <i>whence</i>). Returns the new offset into the file. - * + * * f = File.new("testfile") * f.sysseek(-13, IO::SEEK_END) #=> 53 * f.sysread(10) #=> "And so on." @@ -2031,12 +2031,12 @@ rb_io_sysseek(argc, argv, io) /* * call-seq: * ios.syswrite(string ) => integer - * + * * Writes the given string to <em>ios</em> using a low-level write. * Returns the number of bytes written. Do not mix with other methods * that write to <em>ios</em> or you may get unpredictable results. * Raises <code>SystemCallError</code> on error. - * + * * f = File.new("out", "w") * f.syswrite("ABCDEF") #=> 6 */ @@ -2073,13 +2073,13 @@ rb_io_syswrite(io, str) /* * call-seq: * ios.sysread(integer ) => string - * + * * Reads <i>integer</i> bytes from <em>ios</em> using a low-level * read and returns them as a string. Do not mix with other methods * that read from <em>ios</em> or you may get unpredictable results. * Raises <code>SystemCallError</code> on error and * <code>EOFError</code> at end of file. - * + * * f = File.new("testfile") * f.sysread(16) #=> "This is line one" */ @@ -2137,7 +2137,7 @@ rb_io_sysread(argc, argv, io) /* * call-seq: * ios.binmode => ios - * + * * Puts <em>ios</em> into binary mode. This is useful only in * MS-DOS/Windows environments. Once a stream is in binary mode, it * cannot be reset to nonbinary mode. @@ -2798,43 +2798,51 @@ rb_io_popen(str, argc, argv, klass) /* * call-seq: - * IO.popen(cmd_string, mode="r" ) => io - * IO.popen(cmd_string, mode="r" ) {|io| block } => obj - * - * Runs the specified command string as a subprocess; the subprocess's + * IO.popen(cmd, mode="r") => io + * IO.popen(cmd, mode="r") {|io| block } => obj + * + * Runs the specified command as a subprocess; the subprocess's * standard input and output will be connected to the returned - * <code>IO</code> object. If <i>cmd_string</i> starts with a + * <code>IO</code> object. If _cmd_ is a +String+ * ``<code>-</code>'', then a new instance of Ruby is started as the - * subprocess. The default mode for the new file object is ``r'', but - * <i>mode</i> may be set to any of the modes listed in the description - * for class IO. - * + * subprocess. If <i>cmd</i> is an +Array+ of +String+, then it will + * be used as the subprocess's +argv+ bypassing a shell. The default + * mode for the new file object is ``r'', but <i>mode</i> may be set + * to any of the modes listed in the description for class IO. + * + * Raises exceptions which <code>IO::pipe</code> and + * <code>Kernel::system</code> raise. + * * If a block is given, Ruby will run the command as a child connected * to Ruby with a pipe. Ruby's end of the pipe will be passed as a * parameter to the block. In this case <code>IO::popen</code> returns * the value of the block. - * - * If a block is given with a <i>cmd_string</i> of ``<code>-</code>'', + * + * If a block is given with a _cmd_ of ``<code>-</code>'', * the block will be run in two separate processes: once in the parent, * and once in a child. The parent process will be passed the pipe * object as a parameter to the block, the child version of the block * will be passed <code>nil</code>, and the child's standard in and * standard out will be connected to the parent through the pipe. Not * available on all platforms. - * + * * f = IO.popen("uname") * p f.readlines * puts "Parent is #{Process.pid}" - * IO.popen ("date") { |f| puts f.gets } + * IO.popen("date") { |f| puts f.gets } * IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f}"} - * + * IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f| + * f.puts "bar"; f.close_write; puts f.gets + * } + * * <em>produces:</em> - * + * * ["Linux\n"] * Parent is 26166 * Wed Apr 9 08:53:52 CDT 2003 * 26169 is here, f is * 26166 is here, f is #<IO:0x401b3d44> + * <foo>bar;zot; */ static VALUE @@ -2922,13 +2930,13 @@ rb_open_file(argc, argv, io) * call-seq: * IO.open(fd, mode_string="r" ) => io * IO.open(fd, mode_string="r" ) {|io| block } => obj - * + * * With no associated block, <code>open</code> is a synonym for * <code>IO::new</code>. If the optional code block is given, it will * be passed <i>io</i> as an argument, and the IO object will * automatically be closed when the block terminates. In this instance, * <code>IO::open</code> returns the value of the block. - * + * */ static VALUE @@ -2949,12 +2957,12 @@ rb_io_s_open(argc, argv, klass) /* * call-seq: * IO.sysopen(path, [mode, [perm]]) => fixnum - * + * * Opens the given path, returning the underlying file descriptor as a * <code>Fixnum</code>. - * + * * IO.sysopen("testfile") #=> 3 - * + * */ static VALUE @@ -2985,21 +2993,21 @@ rb_io_s_sysopen(argc, argv) * call-seq: * open(path [, mode [, perm]] ) => io or nil * open(path [, mode [. perm]] ) {|io| block } => nil - * + * * Creates an <code>IO</code> object connected to the given stream, * file, or subprocess. - * + * * If <i>path</i> does not start with a pipe character * (``<code>|</code>''), treat it as the name of a file to open using * the specified mode (defaulting to ``<code>r</code>''). (See the table * of valid modes on page 331.) If a file is being created, its initial * permissions may be set using the integer third parameter. - * + * * If a block is specified, it will be invoked with the * <code>File</code> object as a parameter, and the file will be * automatically closed when the block terminates. The call always * returns <code>nil</code> in this case. - * + * * If <i>path</i> starts with a pipe character, a subprocess is * created, connected to the caller by a pair of pipes. The returned * <code>IO</code> object may be used to write to the standard input @@ -3015,27 +3023,27 @@ rb_io_s_sysopen(argc, argv) * will be connected to the child's <code>$stdin</code> and * <code>$stdout</code>. The subprocess will be terminated at the end * of the block. - * + * * open("testfile") do |f| * print f.gets * end - * + * * <em>produces:</em> - * + * * This is line one - * + * * Open a subprocess and read its output: - * + * * cmd = open("|date") * print cmd.gets * cmd.close - * + * * <em>produces:</em> - * + * * Wed Apr 9 08:56:31 CDT 2003 - * + * * Open a subprocess running the same Ruby program: - * + * * f = open("|-", "w+") * if f == nil * puts "in Child" @@ -3043,13 +3051,13 @@ rb_io_s_sysopen(argc, argv) * else * puts "Got: #{f.gets}" * end - * + * * <em>produces:</em> - * + * * Got: in Child - * + * * Open a subprocess using a block to receive the I/O object: - * + * * open("|-") do |f| * if f == nil * puts "in Child" @@ -3057,9 +3065,9 @@ rb_io_s_sysopen(argc, argv) * puts "Got: #{f.gets}" * end * end - * + * * <em>produces:</em> - * + * * Got: in Child */ @@ -3210,13 +3218,13 @@ io_reopen(io, nfile) /* * call-seq: - * ios.reopen(other_IO) => ios + * ios.reopen(other_IO) => ios * ios.reopen(path, mode_str) => ios - * + * * Reassociates <em>ios</em> with the I/O stream given in * <i>other_IO</i> or to a new stream opened on <i>path</i>. This may * dynamically change the actual class of this stream. - * + * * f1 = File.new("testfile") * f2 = File.new("testfile") * f2.readlines[0] #=> "This is line one\n" @@ -3354,7 +3362,7 @@ rb_io_init_copy(dest, io) /* * call-seq: * ios.printf(format_string [, obj, ...] ) => nil - * + * * Formats and writes to <em>ios</em>, converting parameters under * control of the format string. See <code>Kernel#sprintf</code> * for details. @@ -3374,7 +3382,7 @@ rb_io_printf(argc, argv, out) * call-seq: * printf(io, string [, obj ... ] ) => nil * printf(string [, obj ... ] ) => nil - * + * * Equivalent to: * io.write(sprintf(string, obj, ...) * or @@ -3406,7 +3414,7 @@ rb_f_printf(argc, argv) * call-seq: * ios.print() => nil * ios.print(obj, ...) => nil - * + * * Writes the given object(s) to <em>ios</em>. The stream must be * opened for writing. If the output record separator (<code>$\</code>) * is not <code>nil</code>, it will be appended to the output. If no @@ -3414,11 +3422,11 @@ rb_f_printf(argc, argv) * strings will be converted by calling their <code>to_s</code> method. * With no argument, prints the contents of the variable <code>$_</code>. * Returns <code>nil</code>. - * + * * $stdout.print("This is ", 100, " percent.\n") - * + * * <em>produces:</em> - * + * * This is 100 percent. */ @@ -3460,7 +3468,7 @@ rb_io_print(argc, argv, out) /* * call-seq: * print(obj, ...) => nil - * + * * Prints each object in turn to <code>$stdout</code>. If the output * field separator (<code>$,</code>) is not +nil+, its * contents will appear between each field. If the output record @@ -3468,14 +3476,14 @@ rb_io_print(argc, argv, out) * appended to the output. If no arguments are given, prints * <code>$_</code>. Objects that aren't strings will be converted by * calling their <code>to_s</code> method. - * + * * print "cat", [1,2,3], 99, "\n" * $, = ", " * $\ = "\n" * print "cat", [1,2,3], 99 - * + * * <em>produces:</em> - * + * * cat12399 * cat, 1, 2, 3, 99 */ @@ -3492,16 +3500,16 @@ rb_f_print(argc, argv) /* * call-seq: * ios.putc(obj) => obj - * + * * If <i>obj</i> is <code>Numeric</code>, write the character whose * code is <i>obj</i>, otherwise write the first character of the * string representation of <i>obj</i> to <em>ios</em>. - * + * * $stdout.putc "A" * $stdout.putc 65 - * + * * <em>produces:</em> - * + * * AA */ @@ -3518,7 +3526,7 @@ rb_io_putc(io, ch) /* * call-seq: * putc(int) => int - * + * * Equivalent to: * * $stdout.putc(int) @@ -3551,17 +3559,17 @@ io_puts_ary(ary, out) /* * call-seq: * ios.puts(obj, ...) => nil - * + * * Writes the given objects to <em>ios</em> as with * <code>IO#print</code>. Writes a record separator (typically a * newline) after any that do not already end with a newline sequence. * If called with an array argument, writes each element on a new line. * If called without arguments, outputs a single record separator. - * + * * $stdout.puts("this", "is", "a", "test") - * + * * <em>produces:</em> - * + * * this * is * a @@ -3607,8 +3615,8 @@ rb_io_puts(argc, argv, out) /* * call-seq: * puts(obj, ...) => nil - * - * Equivalent to + * + * Equivalent to * * $stdout.puts(obj, ...) */ @@ -3633,18 +3641,18 @@ rb_p(obj) /* for debug print within C code */ /* * call-seq: * p(obj, ...) => nil - * + * * For each object, directly writes * _obj_.+inspect+ followed by the current output * record separator to the program's standard output. +p+ * bypasses the Ruby I/O libraries. - * + * * S = Struct.new(:name, :state) * s = S['dave', 'TX'] * p s - * + * * <em>produces:</em> - * + * * #<S name="dave", state="TX"> */ @@ -3667,23 +3675,23 @@ rb_f_p(argc, argv) /* * call-seq: * obj.display(port=$>) => nil - * + * * Prints <i>obj</i> on the given port (default <code>$></code>). * Equivalent to: - * + * * def display(port=$>) * port.write self * end - * + * * For example: - * + * * 1.display * "cat".display * [ 4, 5, 6 ].display * puts - * + * * <em>produces:</em> - * + * * 1cat456 */ @@ -3799,7 +3807,7 @@ prep_path(io, path) /* * call-seq: * IO.new(fd, mode) => io - * + * * Returns a new <code>IO</code> object (a stream) for the given * <code>IO</code> object or integer file descriptor and mode * string. See also <code>IO#fileno</code> and @@ -3810,9 +3818,9 @@ prep_path(io, path) * a = IO.new(2,"w") # '2' is standard error * $stderr.puts "Hello" * a.puts "World" - * + * * <em>produces:</em> - * + * * Hello * World */ @@ -3893,7 +3901,7 @@ rb_io_initialize(argc, argv, io) * call-seq: * File.new(filename, mode="r") => file * File.new(filename [, mode [, perm]]) => file - * + * * Opens the file named by _filename_ according to * _mode_ (default is ``r'') and returns a new @@ -3937,17 +3945,17 @@ rb_file_initialize(argc, argv, io) /* * call-seq: * IO.new(fd, mode_string) => io - * + * * Returns a new <code>IO</code> object (a stream) for the given * integer file descriptor and mode string. See also * <code>IO#fileno</code> and <code>IO::for_fd</code>. - * + * * a = IO.new(2,"w") # '2' is standard error * $stderr.puts "Hello" * a.puts "World" - * + * * <em>produces:</em> - * + * * Hello * World */ @@ -3971,9 +3979,9 @@ rb_io_s_new(argc, argv, klass) /* * call-seq: * IO.for_fd(fd, mode) => io - * + * * Synonym for <code>IO::new</code>. - * + * */ static VALUE @@ -4172,7 +4180,7 @@ argf_getline(argc, argv) /* * call-seq: * gets(separator=$/) => string or nil - * + * * Returns (and assigns to <code>$_</code>) the next line from the list * of files in +ARGV+ (or <code>$*</code>), or from standard * input if no files are present on the command line. Returns @@ -4183,17 +4191,17 @@ argf_getline(argc, argv) * at a time, where paragraphs are divided by two consecutive newlines. * If multiple filenames are present in +ARGV+, * +gets(nil)+ will read the contents one file at a time. - * + * * ARGV << "testfile" * print while gets - * + * * <em>produces:</em> - * + * * This is line one * This is line two * This is line three * And so on... - * + * * The style of programming using <code>$_</code> as an implicit * parameter is gradually losing favor in the Ruby community. */ @@ -4245,7 +4253,7 @@ rb_gets() /* * call-seq: * readline(separator=$/ => string - * + * * Equivalent to <code>Kernel::gets</code>, except * +readline+ raises +EOFError+ at end of file. */ @@ -4283,7 +4291,7 @@ rb_f_getc() /* * call-seq: * readlines(separator=$/) => array - * + * * Returns an array containing the lines returned by calling * <code>Kernel.gets(<i>aString</i>)</code> until the end of file. */ @@ -4307,11 +4315,11 @@ rb_f_readlines(argc, argv) /* * call-seq: * `cmd` => string - * + * * Returns the standard output of running _cmd_ in a subshell. * The built-in syntax <code>%x{...}</code> uses * this method. Sets <code>$?</code> to the process status. - * + * * `date` #=> "Wed Apr 9 08:56:30 CDT 2003\n" * `ls testdir`.split[1] #=> "main.rb" * `echo oops && exit 99` #=> "oops\n" @@ -4342,11 +4350,11 @@ rb_f_backquote(obj, str) /* * call-seq: - * IO.select(read_array - * [, write_array - * [, error_array + * IO.select(read_array + * [, write_array + * [, error_array * [, timeout]]] ) => array or nil - * + * * See <code>Kernel#select</code>. */ @@ -4591,7 +4599,7 @@ rb_io_ctl(io, req, arg, io_p) /* * call-seq: * ios.ioctl(integer_cmd, arg) => integer - * + * * Provides a mechanism for issuing low-level commands to control or * query I/O devices. Arguments and results are platform dependent. If * <i>arg</i> is a number, its value is passed directly. If it is a @@ -4615,7 +4623,7 @@ rb_io_ioctl(argc, argv, io) /* * call-seq: * ios.fcntl(integer_cmd, arg) => integer - * + * * Provides a mechanism for issuing low-level commands to control or * query file-oriented I/O streams. Arguments and results are platform * dependent. If <i>arg</i> is a number, its value is passed @@ -4645,7 +4653,7 @@ rb_io_fcntl(argc, argv, io) /* * call-seq: * syscall(fixnum [, args...]) => integer - * + * * Calls the operating system function identified by _fixnum_, * passing in the arguments, which must be either +String+ * objects, or +Integer+ objects that ultimately fit within @@ -4653,11 +4661,11 @@ rb_io_fcntl(argc, argv, io) * on the Atari-ST). The function identified by _fixnum_ is system * dependent. On some Unix systems, the numbers may be obtained from a * header file called <code>syscall.h</code>. - * + * * syscall 4, 1, "hello\n", 6 # '4' is write(2) on our box - * + * * <em>produces:</em> - * + * * hello */ @@ -4773,21 +4781,21 @@ io_new_instance(args) /* * call-seq: * IO.pipe -> array - * + * * Creates a pair of pipe endpoints (connected to each other) and * returns them as a two-element array of <code>IO</code> objects: * <code>[</code> <i>read_file</i>, <i>write_file</i> <code>]</code>. Not * available on all platforms. - * + * * In the example below, the two processes close the ends of the pipe * that they are not using. This is not just a cosmetic nicety. The * read end of a pipe will not generate an end of file condition if * there are any writers with the pipe still open. In the case of the * parent process, the <code>rd.read</code> will never return if it * does not first issue a <code>wr.close</code>. - * + * * rd, wr = IO.pipe - * + * * if fork * wr.close * puts "Parent got: <#{rd.read}>" @@ -4799,9 +4807,9 @@ io_new_instance(args) * wr.write "Hi Dad" * wr.close * end - * + * * <em>produces:</em> - * + * * Sending message to parent * Parent got: <Hi Dad> */ @@ -4869,19 +4877,19 @@ io_s_foreach(arg) /* * call-seq: * IO.foreach(name, sep_string=$/) {|line| block } => nil - * + * * Executes the block for every line in the named I/O port, where lines * are separated by <em>sep_string</em>. - * + * * IO.foreach("testfile") {|x| print "GOT ", x } - * + * * <em>produces:</em> - * + * * GOT This is line one * GOT This is line two * GOT This is line three * GOT And so on... - */ + */ static VALUE rb_io_s_foreach(argc, argv) @@ -4915,14 +4923,14 @@ io_s_readlines(arg) /* * call-seq: * IO.readlines(name, sep_string=$/) => array - * + * * Reads the entire file specified by <i>name</i> as individual * lines, and returns those lines in an array. Lines are separated by * <i>sep_string</i>. - * + * * a = IO.readlines("testfile") * a[0] #=> "This is line one\n" - * + * */ static VALUE @@ -4952,11 +4960,11 @@ io_s_read(arg) /* * call-seq: * IO.read(rane, [length [, offset]] ) => string - * + * * Opens the file, optionally seeks to the given offset, then returns * <i>length</i> bytes (defaulting to the rest of the file). * <code>read</code> ensures the file is closed before returning. - * + * * IO.read("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n" * IO.read("testfile", 20) #=> "This is line one\nThi" * IO.read("testfile", 20, 10) #=> "ne one\nThis is line " @@ -5258,38 +5266,38 @@ opt_i_set(val) * Class <code>IO</code> is the basis for all input and output in Ruby. * An I/O stream may be <em>duplexed</em> (that is, bidirectional), and * so may use more than one native operating system stream. - * + * * Many of the examples in this section use class <code>File</code>, * the only standard subclass of <code>IO</code>. The two classes are * closely associated. - * + * * As used in this section, <em>portname</em> may take any of the * following forms. - * + * * * A plain string represents a filename suitable for the underlying * operating system. - * + * * * A string starting with ``<code>|</code>'' indicates a subprocess. * The remainder of the string following the ``<code>|</code>'' is * invoked as a process with appropriate input/output channels * connected to it. - * + * * * A string equal to ``<code>|-</code>'' will create another Ruby * instance as a subprocess. - * + * * Ruby will convert pathnames between different operating system * conventions if possible. For instance, on a Windows system the * filename ``<code>/gumby/ruby/test.rb</code>'' will be opened as * ``<code>\gumby\ruby\test.rb</code>''. When specifying a * Windows-style filename in a Ruby string, remember to escape the * backslashes: - * + * * "c:\\gumby\\ruby\\test.rb" - * + * * Our examples here will use the Unix-style forward slashes; * <code>File::SEPARATOR</code> can be used to get the * platform-specific separator character. - * + * * I/O ports may be opened in any one of several different modes, which * are shown in this section as <em>mode</em>. The mode may * either be a Fixnum or a String. If numeric, it should be @@ -5306,7 +5314,7 @@ opt_i_set(val) * -----+-------------------------------------------------------- * "r+" | Read-write, starts at beginning of file. * -----+-------------------------------------------------------- - * "w" | Write-only, truncates existing file + * "w" | Write-only, truncates existing file * | to zero length or creates a new file for writing. * -----+-------------------------------------------------------- * "w+" | Read-write, truncates existing file to zero length @@ -5316,10 +5324,10 @@ opt_i_set(val) * | otherwise creates a new file for writing. * -----+-------------------------------------------------------- * "a+" | Read-write, starts at end of file if file exists, - * | otherwise creates a new file for reading and + * | otherwise creates a new file for reading and * | writing. * -----+-------------------------------------------------------- - * "b" | (DOS/Windows only) Binary file mode (may appear with + * "b" | (DOS/Windows only) Binary file mode (may appear with * | any of the key letters listed above). * * @@ -5333,7 +5341,7 @@ opt_i_set(val) void Init_IO() { -#ifdef __CYGWIN__ +#ifdef __CYGWIN__ #include <sys/cygwin.h> static struct __cygwin_perfile pf[] = { @@ -115,10 +115,10 @@ static VALUE S_Tms; /* * call-seq: * Process.pid => fixnum - * + * * Returns the process id of this process. Not available on all * platforms. - * + * * Process.pid #=> 27415 */ @@ -132,15 +132,15 @@ get_pid() /* * call-seq: * Process.ppid => fixnum - * + * * Returns the process id of the parent of this process. Always * returns 0 on NT. Not available on all platforms. - * + * * puts "I am #{Process.pid}" * Process.fork { puts "Dad is #{Process.ppid}" } - * + * * <em>produces:</em> - * + * * I am 27417 * Dad is 27417 */ @@ -164,7 +164,7 @@ get_ppid() * status of a running or terminated system process. The built-in * variable <code>$?</code> is either +nil+ or a * <code>Process::Status</code> object. - * + * * fork { exit 99 } #=> 26557 * Process.wait #=> 26557 * $?.class #=> Process::Status @@ -173,7 +173,7 @@ get_ppid() * $?.stopped? #=> false * $?.exited? #=> true * $?.exitstatus #=> 99 - * + * * Posix systems record information on processes using a 16-bit * integer. The lower bits record the process status (stopped, * exited, signaled) and the upper bits possibly contain additional @@ -203,10 +203,10 @@ last_status_set(status, pid) * call-seq: * stat.to_i => fixnum * stat.to_int => fixnum - * + * * Returns the bits in _stat_ as a <code>Fixnum</code>. Poking * around in these bits is platform dependent. - * + * * fork { exit 0xab } #=> 26566 * Process.wait #=> 26566 * sprintf('%04x', $?.to_i) #=> "ab00" @@ -223,7 +223,7 @@ pst_to_i(st) /* * call-seq: * stat.to_s => string - * + * * Equivalent to _stat_<code>.to_i.to_s</code>. */ @@ -238,9 +238,9 @@ pst_to_s(st) /* * call-seq: * stat.pid => fixnum - * + * * Returns the process ID that this status object represents. - * + * * fork { exit } #=> 26569 * Process.wait #=> 26569 * $?.pid #=> 26569 @@ -257,7 +257,7 @@ pst_pid(st) /* * call-seq: * stat.inspect => string - * + * * Override the inspection method. */ @@ -314,7 +314,7 @@ pst_inspect(st) /* * call-seq: * stat == other => true or false - * + * * Returns +true+ if the integer value of _stat_ * equals <em>other</em>. */ @@ -331,9 +331,9 @@ pst_equal(st1, st2) /* * call-seq: * stat & num => fixnum - * + * * Logical AND of the bits in _stat_ with <em>num</em>. - * + * * fork { exit 0x37 } * Process.wait * sprintf('%04x', $?.to_i) #=> "3700" @@ -353,9 +353,9 @@ pst_bitand(st1, st2) /* * call-seq: * stat >> num => fixnum - * + * * Shift the bits in _stat_ right <em>num</em> places. - * + * * fork { exit 99 } #=> 26563 * Process.wait #=> 26563 * $?.to_i #=> 25344 @@ -375,7 +375,7 @@ pst_rshift(st1, st2) /* * call-seq: * stat.stopped? => true or false - * + * * Returns +true+ if this process is stopped. This is only * returned if the corresponding <code>wait</code> call had the * <code>WUNTRACED</code> flag set. @@ -397,7 +397,7 @@ pst_wifstopped(st) /* * call-seq: * stat.stopsig => fixnum or nil - * + * * Returns the number of the signal that caused _stat_ to stop * (or +nil+ if self is not stopped). */ @@ -417,7 +417,7 @@ pst_wstopsig(st) /* * call-seq: * stat.signaled? => true or false - * + * * Returns +true+ if _stat_ terminated because of * an uncaught signal. */ @@ -438,7 +438,7 @@ pst_wifsignaled(st) /* * call-seq: * stat.termsig => fixnum or nil - * + * * Returns the number of the signal that caused _stat_ to * terminate (or +nil+ if self was not terminated by an * uncaught signal). @@ -459,7 +459,7 @@ pst_wtermsig(st) /* * call-seq: * stat.exited? => true or false - * + * * Returns +true+ if _stat_ exited normally (for * example using an <code>exit()</code> call or finishing the * program). @@ -481,16 +481,16 @@ pst_wifexited(st) /* * call-seq: * stat.exitstatus => fixnum or nil - * + * * Returns the least significant eight bits of the return code of * _stat_. Only available if <code>exited?</code> is * +true+. - * + * * fork { } #=> 26572 * Process.wait #=> 26572 * $?.exited? #=> true * $?.exitstatus #=> 0 - * + * * fork { exit 99 } #=> 26573 * Process.wait #=> 26573 * $?.exited? #=> true @@ -512,7 +512,7 @@ pst_wexitstatus(st) /* * call-seq: * stat.success? => true, false or nil - * + * * Returns +true+ if _stat_ is successful, +false+ if not. * Returns +nil+ if <code>exited?</code> is not +true+. */ @@ -532,7 +532,7 @@ pst_success_p(st) /* * call-seq: * stat.coredump? => true or false - * + * * Returns +true+ if _stat_ generated a coredump * when it terminated. Not available on all platforms. */ @@ -678,20 +678,20 @@ waitall_each(pid, status, ary) * Process.wait() => fixnum * Process.wait(pid=-1, flags=0) => fixnum * Process.waitpid(pid=-1, flags=0) => fixnum - * + * * Waits for a child process to exit, returns its process id, and * sets <code>$?</code> to a <code>Process::Status</code> object * containing information on that process. Which child it waits on * depends on the value of _pid_: - * + * * > 0:: Waits for the child whose process ID equals _pid_. - * + * * 0:: Waits for any child whose process group ID equals that of the * calling process. * * -1:: Waits for any child process (the default if no _pid_ is * given). - * + * * < -1:: Waits for any child whose process group ID equals the absolute * value of _pid_. * @@ -700,10 +700,10 @@ waitall_each(pid, status, ary) * or <code>Process::WUNTRACED</code> (return stopped children that * haven't been reported). Not all flags are available on all * platforms, but a flag value of zero will work on all platforms. - * + * * Calling this method raises a <code>SystemError</code> if there are * no child processes. Not available on all platforms. - * + * * include Process * fork { exit 99 } #=> 27429 * wait #=> 27429 @@ -749,13 +749,13 @@ proc_wait(argc, argv) * call-seq: * Process.wait2(pid=-1, flags=0) => [pid, status] * Process.waitpid2(pid=-1, flags=0) => [pid, status] - * + * * Waits for a child process to exit (see Process::waitpid for exact * semantics) and returns an array containing the process id and the * exit status (a <code>Process::Status</code> object) of that * child. Raises a <code>SystemError</code> if there are no child * processes. - * + * * Process.fork { exit 99 } #=> 27437 * pid, status = Process.wait2 * pid #=> 27437 @@ -776,11 +776,11 @@ proc_wait2(argc, argv) /* * call-seq: * Process.waitall => [ [pid1,status1], ...] - * + * * Waits for all children, returning an array of * _pid_/_status_ pairs (where _status_ is a * <code>Process::Status</code> object). - * + * * fork { sleep 0.2; exit 2 } #=> 27432 * fork { sleep 0.1; exit 1 } #=> 27433 * fork { exit 0 } #=> 27434 @@ -858,7 +858,7 @@ rb_detach_process(pid) /* * call-seq: * Process.detach(pid) => thread - * + * * Some operating systems retain the status of terminated child * processes until the parent collects that status (normally using * some variant of <code>wait()</code>. If the parent never collects @@ -877,27 +877,27 @@ rb_detach_process(pid) * * In this first example, we don't reap the first child process, so * it appears as a zombie in the process status display. - * + * * p1 = fork { sleep 0.1 } * p2 = fork { sleep 0.2 } * Process.waitpid(p2) * sleep 2 * system("ps -ho pid,state -p #{p1}") - * + * * <em>produces:</em> - * + * * 27389 Z - * + * * In the next example, <code>Process::detach</code> is used to reap * the child automatically. - * + * * p1 = fork { sleep 0.1 } * p2 = fork { sleep 0.2 } * Process.detach(p1) * Process.waitpid(p2) * sleep 2 * system("ps -ho pid,state -p #{p1}") - * + * * <em>(produces no output)</em> */ @@ -1211,7 +1211,7 @@ rb_check_argv(argc, argv) /* * call-seq: * exec(command [, arg, ...]) - * + * * Replaces the current process by running the given external _command_. * If +exec+ is given a single argument, that argument is * taken as a line that is subject to shell expansion before being @@ -1224,11 +1224,14 @@ rb_check_argv(argc, argv) * subshell; otherwise, one of the <code>exec(2)</code> system calls is * used, so the running command may inherit some of the environment of * the original program (including open file descriptors). - * + * + * Raises SystemCallError if the _command_ couldn't execute (typically + * <code>Errno::ENOENT</code> when it was not found). + * * exec "echo *" # echoes list of files in current directory * # never get here - * - * + * + * * exec "echo", "*" # echoes an asterisk * # never get here */ @@ -1405,7 +1408,7 @@ rb_fork(status, chfunc, charg) /* * call-seq: * Process.fork [{ block }] => fixnum or nil - * + * * See <code>Kernel::fork</code>. */ @@ -1448,11 +1451,11 @@ rb_f_fork(obj) /* * call-seq: * Process.exit!(fixnum=-1) - * + * * Exits the process immediately. No exit handlers are * run. <em>fixnum</em> is returned to the underlying system as the * exit status. - * + * * Process.exit!(0) */ @@ -1572,18 +1575,17 @@ rb_spawn(argc, argv) /* * call-seq: * system(cmd [, arg, ...]) => true or false - * - * Executes _cmd_ in a subshell, returning +true+ if - * the command was found and ran successfully, +false+ - * otherwise. An error status is available in <code>$?</code>. The - * arguments are processed in the same way as for - * <code>Kernel::exec</code>. - * + * + * Executes _cmd_ in a subshell, returning +true+ if the command ran + * successfully, +false+ otherwise. An error status is available in + * <code>$?</code>. The arguments are processed in the same way as + * for <code>Kernel::exec</code>, and raises same exceptions as it. + * * system("echo *") * system("echo", "*") - * + * * <em>produces:</em> - * + * * config.h main.rb * * */ @@ -1632,14 +1634,14 @@ rb_f_spawn(argc, argv) /* * call-seq: * sleep(duration=0) => fixnum - * + * * Suspends the current thread for _duration_ seconds (which may be * any number, including a +Float+ with fractional seconds). Returns the actual * number of seconds slept (rounded), which may be less than that asked * for if the thread was interrupted by a +SIGALRM+, or if * another thread calls <code>Thread#run</code>. An argument of zero * causes +sleep+ to sleep forever. - * + * * Time.new #=> Wed Apr 09 08:56:32 CDT 2003 * sleep 1.2 #=> 1 * Time.new #=> Wed Apr 09 08:56:33 CDT 2003 @@ -1674,10 +1676,10 @@ rb_f_sleep(argc, argv) /* * call-seq: * Process.getpgrp => integer - * + * * Returns the process group ID for this process. Not available on * all platforms. - * + * * Process.getpgid(0) #=> 25527 * Process.getpgrp #=> 25527 */ @@ -1706,7 +1708,7 @@ proc_getpgrp() /* * call-seq: * Process.setpgrp => 0 - * + * * Equivalent to <code>setpgid(0,0)</code>. Not available on all * platforms. */ @@ -1732,10 +1734,10 @@ proc_setpgrp() /* * call-seq: * Process.getpgid(pid) => integer - * + * * Returns the process group ID for the given process id. Not * available on all platforms. - * + * * Process.getpgid(Process.ppid()) #=> 25527 */ @@ -1757,7 +1759,7 @@ proc_getpgid(obj, pid) /* * call-seq: * Process.setpgid(pid, integer) => 0 - * + * * Sets the process group ID of _pid_ (0 indicates this * process) to <em>integer</em>. Not available on all platforms. */ @@ -1784,11 +1786,11 @@ proc_setpgid(obj, pid, pgrp) /* * call-seq: * Process.setsid => fixnum - * + * * Establishes this process as a new session and process group * leader, with no controlling tty. Returns the session id. Not * available on all platforms. - * + * * Process.setsid #=> 27422 */ @@ -1832,7 +1834,7 @@ proc_setsid() /* * call-seq: * Process.getpriority(kind, integer) => fixnum - * + * * Gets the scheduling priority for specified process, process group, * or user. <em>kind</em> indicates the kind of entity to find: one * of <code>Process::PRIO_PGRP</code>, @@ -1841,7 +1843,7 @@ proc_setsid() * indicating the particular process, process group, or user (an id * of 0 means _current_). Lower priorities are more favorable * for scheduling. Not available on all platforms. - * + * * Process.getpriority(Process::PRIO_USER, 0) #=> 19 * Process.getpriority(Process::PRIO_PROCESS, 0) #=> 19 */ @@ -1869,9 +1871,9 @@ proc_getpriority(obj, which, who) /* * call-seq: * Process.setpriority(kind, integer, priority) => 0 - * + * * See <code>Process#getpriority</code>. - * + * * Process.setpriority(Process::PRIO_USER, 0, 19) #=> 0 * Process.setpriority(Process::PRIO_PROCESS, 0, 19) #=> 0 * Process.getpriority(Process::PRIO_USER, 0) #=> 19 @@ -1933,10 +1935,10 @@ check_gid_switch() /* * call-seq: * Process::Sys.setuid(integer) => nil - * + * * Set the user ID of the current process to _integer_. Not * available on all platforms. - * + * */ static VALUE @@ -1957,10 +1959,10 @@ p_sys_setuid(obj, id) /* * call-seq: * Process::Sys.setruid(integer) => nil - * + * * Set the real user ID of the calling process to _integer_. * Not available on all platforms. - * + * */ static VALUE @@ -1980,10 +1982,10 @@ p_sys_setruid(obj, id) /* * call-seq: * Process::Sys.seteuid(integer) => nil - * + * * Set the effective user ID of the calling process to * _integer_. Not available on all platforms. - * + * */ static VALUE @@ -2003,7 +2005,7 @@ p_sys_seteuid(obj, id) /* * call-seq: * Process::Sys.setreuid(rid, eid) => nil - * + * * Sets the (integer) real and/or effective user IDs of the current * process to _rid_ and _eid_, respectively. A value of * <code>-1</code> for either means to leave that ID unchanged. Not @@ -2028,9 +2030,9 @@ p_sys_setreuid(obj, rid, eid) /* * call-seq: * Process::Sys.setresuid(rid, eid, sid) => nil - * + * * Sets the (integer) real, effective, and saved user IDs of the - * current process to _rid_, _eid_, and _sid_ respectively. A + * current process to _rid_, _eid_, and _sid_ respectively. A * value of <code>-1</code> for any value means to * leave that ID unchanged. Not available on all platforms. * @@ -2055,9 +2057,9 @@ p_sys_setresuid(obj, rid, eid, sid) * Process.uid => fixnum * Process::UID.rid => fixnum * Process::Sys.getuid => fixnum - * + * * Returns the (real) user ID of this process. - * + * * Process.uid #=> 501 */ @@ -2073,7 +2075,7 @@ proc_getuid(obj) /* * call-seq: * Process.uid= integer => numeric - * + * * Sets the (integer) user ID for this process. Not available on all * platforms. */ @@ -2108,7 +2110,7 @@ proc_setuid(obj, id) /******************************************************************** - * + * * Document-class: Process::UID * * The <code>Process::UID</code> module contains a collection of @@ -2123,11 +2125,11 @@ static int SAVED_USER_ID; /* * call-seq: * Process::UID.change_privilege(integer) => fixnum - * + * * Change the current process's real and effective user ID to that * specified by _integer_. Returns the new user ID. Not * available on all platforms. - * + * * [Process.uid, Process.euid] #=> [0, 0] * Process::UID.change_privilege(31) #=> 31 * [Process.uid, Process.euid] #=> [31, 31] @@ -2200,13 +2202,13 @@ p_uid_change_privilege(obj, id) #endif } else { /* unprivileged user */ #if defined(HAVE_SETRESUID) - if (setresuid((getuid() == uid)? -1: uid, - (geteuid() == uid)? -1: uid, + if (setresuid((getuid() == uid)? -1: uid, + (geteuid() == uid)? -1: uid, (SAVED_USER_ID == uid)? -1: uid) < 0) rb_sys_fail(0); SAVED_USER_ID = uid; #elif defined(HAVE_SETREUID) && !defined(OBSOLETE_SETREUID) if (SAVED_USER_ID == uid) { - if (setreuid((getuid() == uid)? -1: uid, + if (setreuid((getuid() == uid)? -1: uid, (geteuid() == uid)? -1: uid) < 0) rb_sys_fail(0); } else if (getuid() != uid) { if (setreuid(uid, (geteuid() == uid)? -1: uid) < 0) rb_sys_fail(0); @@ -2278,10 +2280,10 @@ p_uid_change_privilege(obj, id) /* * call-seq: * Process::Sys.setgid(integer) => nil - * + * * Set the group ID of the current process to _integer_. Not * available on all platforms. - * + * */ static VALUE @@ -2301,10 +2303,10 @@ p_sys_setgid(obj, id) /* * call-seq: * Process::Sys.setrgid(integer) => nil - * + * * Set the real group ID of the calling process to _integer_. * Not available on all platforms. - * + * */ static VALUE @@ -2325,10 +2327,10 @@ p_sys_setrgid(obj, id) /* * call-seq: * Process::Sys.setegid(integer) => nil - * + * * Set the effective group ID of the calling process to * _integer_. Not available on all platforms. - * + * */ static VALUE @@ -2348,7 +2350,7 @@ p_sys_setegid(obj, id) /* * call-seq: * Process::Sys.setregid(rid, eid) => nil - * + * * Sets the (integer) real and/or effective group IDs of the current * process to <em>rid</em> and <em>eid</em>, respectively. A value of * <code>-1</code> for either means to leave that ID unchanged. Not @@ -2372,7 +2374,7 @@ p_sys_setregid(obj, rid, eid) /* * call-seq: * Process::Sys.setresgid(rid, eid, sid) => nil - * + * * Sets the (integer) real, effective, and saved user IDs of the * current process to <em>rid</em>, <em>eid</em>, and <em>sid</em> * respectively. A value of <code>-1</code> for any value means to @@ -2397,7 +2399,7 @@ p_sys_setresgid(obj, rid, eid, sid) /* * call-seq: * Process::Sys.issetugid => true or false - * + * * Returns +true+ if the process was created as a result * of an execve(2) system call which had either of the setuid or * setgid bits set (and extra privileges were given as a result) or @@ -2428,9 +2430,9 @@ p_sys_issetugid(obj) * Process.gid => fixnum * Process::GID.rid => fixnum * Process::Sys.getgid => fixnum - * + * * Returns the (real) group ID for this process. - * + * * Process.gid #=> 500 */ @@ -2446,7 +2448,7 @@ proc_getgid(obj) /* * call-seq: * Process.gid= fixnum => fixnum - * + * * Sets the group ID for this process. */ @@ -2485,7 +2487,7 @@ static size_t maxgroups = 32; /* * call-seq: * Process.groups => array - * + * * Get an <code>Array</code> of the gids of groups in the * supplemental group access list for this process. * @@ -2523,7 +2525,7 @@ proc_getgroups(VALUE obj) /* * call-seq: * Process.groups= array => array - * + * * Set the supplemental group access list to the given * <code>Array</code> of group IDs. * @@ -2565,7 +2567,7 @@ proc_setgroups(VALUE obj, VALUE ary) else { gr = getgrnam(RSTRING(g)->ptr); if (gr == NULL) - rb_raise(rb_eArgError, + rb_raise(rb_eArgError, "can't find group for %s", RSTRING(g)->ptr); groups[i] = gr->gr_gid; } @@ -2587,7 +2589,7 @@ proc_setgroups(VALUE obj, VALUE ary) /* * call-seq: * Process.initgroups(username, gid) => array - * + * * Initializes the supplemental group access list by reading the * system group database and using all groups of which the given user * is a member. The group with the specified <em>gid</em> is also @@ -2620,10 +2622,10 @@ proc_initgroups(obj, uname, base_grp) /* * call-seq: * Process.maxgroups => fixnum - * + * * Returns the maximum number of gids allowed in the supplemental * group access list. - * + * * Process.maxgroups #=> 32 */ @@ -2638,7 +2640,7 @@ proc_getmaxgroups(obj) /* * call-seq: * Process.maxgroups= fixnum => fixnum - * + * * Sets the maximum number of gids allowed in the supplemental group * access list. */ @@ -2659,7 +2661,7 @@ proc_setmaxgroups(obj, val) /******************************************************************** - * + * * Document-class: Process::GID * * The <code>Process::GID</code> module contains a collection of @@ -2674,7 +2676,7 @@ static int SAVED_GROUP_ID; /* * call-seq: * Process::GID.change_privilege(integer) => fixnum - * + * * Change the current process's real and effective group ID to that * specified by _integer_. Returns the new group ID. Not * available on all platforms. @@ -2752,13 +2754,13 @@ p_gid_change_privilege(obj, id) #endif } else { /* unprivileged user */ #if defined(HAVE_SETRESGID) - if (setresgid((getgid() == gid)? -1: gid, - (getegid() == gid)? -1: gid, + if (setresgid((getgid() == gid)? -1: gid, + (getegid() == gid)? -1: gid, (SAVED_GROUP_ID == gid)? -1: gid) < 0) rb_sys_fail(0); SAVED_GROUP_ID = gid; #elif defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID) if (SAVED_GROUP_ID == gid) { - if (setregid((getgid() == gid)? -1: gid, + if (setregid((getgid() == gid)? -1: gid, (getegid() == gid)? -1: gid) < 0) rb_sys_fail(0); } else if (getgid() != gid) { if (setregid(gid, (getegid() == gid)? -1: gid) < 0) rb_sys_fail(0); @@ -2831,9 +2833,9 @@ p_gid_change_privilege(obj, id) * Process.euid => fixnum * Process::UID.eid => fixnum * Process::Sys.geteuid => fixnum - * + * * Returns the effective user ID for this process. - * + * * Process.euid #=> 501 */ @@ -2849,7 +2851,7 @@ proc_geteuid(obj) /* * call-seq: * Process.euid= integer - * + * * Sets the effective user ID for this process. Not available on all * platforms. */ @@ -2919,11 +2921,11 @@ rb_seteuid_core(euid) * call-seq: * Process::UID.grant_privilege(integer) => fixnum * Process::UID.eid= integer => fixnum - * + * * Set the effective user ID, and if possible, the saved user ID of * the process to the given _integer_. Returns the new * effective user ID. Not available on all platforms. - * + * * [Process.uid, Process.euid] #=> [0, 0] * Process::UID.grant_privilege(31) #=> 31 * [Process.uid, Process.euid] #=> [0, 31] @@ -2942,10 +2944,10 @@ p_uid_grant_privilege(obj, id) * Process.egid => fixnum * Process::GID.eid => fixnum * Process::Sys.geteid => fixnum - * + * * Returns the effective group ID for this process. Not available on * all platforms. - * + * * Process.egid #=> 500 */ @@ -2962,7 +2964,7 @@ proc_getegid(obj) /* * call-seq: * Process.egid = fixnum => fixnum - * + * * Sets the effective group ID for this process. Not available on all * platforms. */ @@ -3033,11 +3035,11 @@ rb_setegid_core(egid) * call-seq: * Process::GID.grant_privilege(integer) => fixnum * Process::GID.eid = integer => fixnum - * + * * Set the effective group ID, and if possible, the saved group ID of * the process to the given _integer_. Returns the new * effective group ID. Not available on all platforms. - * + * * [Process.gid, Process.egid] #=> [0, 0] * Process::GID.grant_privilege(31) #=> 33 * [Process.gid, Process.egid] #=> [0, 33] @@ -3054,10 +3056,10 @@ p_gid_grant_privilege(obj, id) /* * call-seq: * Process::UID.re_exchangeable? => true or false - * + * * Returns +true+ if the real and effective user IDs of a * process may be exchanged on the current platform. - * + * */ static VALUE @@ -3076,10 +3078,10 @@ p_uid_exchangeable() /* * call-seq: * Process::UID.re_exchange => fixnum - * + * * Exchange real and effective user IDs and return the new effective * user ID. Not available on all platforms. - * + * * [Process.uid, Process.euid] #=> [0, 31] * Process::UID.re_exchange #=> 0 * [Process.uid, Process.euid] #=> [31, 0] @@ -3112,10 +3114,10 @@ p_uid_exchange(obj) /* * call-seq: * Process::GID.re_exchangeable? => true or false - * + * * Returns +true+ if the real and effective group IDs of a * process may be exchanged on the current platform. - * + * */ static VALUE @@ -3134,10 +3136,10 @@ p_gid_exchangeable() /* * call-seq: * Process::GID.re_exchange => fixnum - * + * * Exchange real and effective group IDs and return the new effective * group ID. Not available on all platforms. - * + * * [Process.gid, Process.egid] #=> [0, 33] * Process::GID.re_exchange #=> 0 * [Process.gid, Process.egid] #=> [33, 0] @@ -3171,10 +3173,10 @@ p_gid_exchange(obj) /* * call-seq: * Process::UID.sid_available? => true or false - * + * * Returns +true+ if the current platform has saved user * ID functionality. - * + * */ static VALUE @@ -3202,13 +3204,13 @@ p_uid_sw_ensure(id) * call-seq: * Process::UID.switch => fixnum * Process::UID.switch {|| block} => object - * + * * Switch the effective and real user IDs of the current process. If * a <em>block</em> is given, the user IDs will be switched back * after the block is executed. Returns the new effective user ID if * called without a block, and the return value of the block if one * is given. - * + * */ static VALUE @@ -3285,10 +3287,10 @@ p_uid_switch(obj) /* * call-seq: * Process::GID.sid_available? => true or false - * + * * Returns +true+ if the current platform has saved group * ID functionality. - * + * */ static VALUE @@ -3315,13 +3317,13 @@ p_gid_sw_ensure(id) * call-seq: * Process::GID.switch => fixnum * Process::GID.switch {|| block} => object - * + * * Switch the effective and real group IDs of the current process. If * a <em>block</em> is given, the group IDs will be switched back * after the block is executed. Returns the new effective group ID if * called without a block, and the return value of the block if one * is given. - * + * */ static VALUE @@ -3395,11 +3397,11 @@ p_gid_switch(obj) /* * call-seq: * Process.times => aStructTms - * + * * Returns a <code>Tms</code> structure (see <code>Struct::Tms</code> * on page 388) that contains user and system CPU times for this * process. - * + * * t = Process.times * [ t.utime, t.stime ] #=> [0.0, 0.02] */ @@ -3553,25 +3555,25 @@ Init_process() rb_define_module_function(rb_mProcGID, "rid", proc_getgid, 0); rb_define_module_function(rb_mProcUID, "eid", proc_geteuid, 0); rb_define_module_function(rb_mProcGID, "eid", proc_getegid, 0); - rb_define_module_function(rb_mProcUID, "change_privilege", + rb_define_module_function(rb_mProcUID, "change_privilege", p_uid_change_privilege, 1); - rb_define_module_function(rb_mProcGID, "change_privilege", + rb_define_module_function(rb_mProcGID, "change_privilege", p_gid_change_privilege, 1); - rb_define_module_function(rb_mProcUID, "grant_privilege", + rb_define_module_function(rb_mProcUID, "grant_privilege", p_uid_grant_privilege, 1); - rb_define_module_function(rb_mProcGID, "grant_privilege", + rb_define_module_function(rb_mProcGID, "grant_privilege", p_gid_grant_privilege, 1); rb_define_alias(rb_mProcUID, "eid=", "grant_privilege"); rb_define_alias(rb_mProcGID, "eid=", "grant_privilege"); rb_define_module_function(rb_mProcUID, "re_exchange", p_uid_exchange, 0); rb_define_module_function(rb_mProcGID, "re_exchange", p_gid_exchange, 0); - rb_define_module_function(rb_mProcUID, "re_exchangeable?", + rb_define_module_function(rb_mProcUID, "re_exchangeable?", p_uid_exchangeable, 0); - rb_define_module_function(rb_mProcGID, "re_exchangeable?", + rb_define_module_function(rb_mProcGID, "re_exchangeable?", p_gid_exchangeable, 0); - rb_define_module_function(rb_mProcUID, "sid_available?", + rb_define_module_function(rb_mProcUID, "sid_available?", p_uid_have_saved_id, 0); - rb_define_module_function(rb_mProcGID, "sid_available?", + rb_define_module_function(rb_mProcGID, "sid_available?", p_gid_have_saved_id, 0); rb_define_module_function(rb_mProcUID, "switch", p_uid_switch, 0); rb_define_module_function(rb_mProcGID, "switch", p_gid_switch, 0); @@ -3592,15 +3594,15 @@ Init_process() rb_define_module_function(rb_mProcID_Syscall, "seteuid", p_sys_seteuid, 1); rb_define_module_function(rb_mProcID_Syscall, "setegid", p_sys_setegid, 1); - rb_define_module_function(rb_mProcID_Syscall, "setreuid", + rb_define_module_function(rb_mProcID_Syscall, "setreuid", p_sys_setreuid, 2); - rb_define_module_function(rb_mProcID_Syscall, "setregid", + rb_define_module_function(rb_mProcID_Syscall, "setregid", p_sys_setregid, 2); - rb_define_module_function(rb_mProcID_Syscall, "setresuid", + rb_define_module_function(rb_mProcID_Syscall, "setresuid", p_sys_setresuid, 3); - rb_define_module_function(rb_mProcID_Syscall, "setresgid", + rb_define_module_function(rb_mProcID_Syscall, "setresgid", p_sys_setresgid, 3); - rb_define_module_function(rb_mProcID_Syscall, "issetugid", + rb_define_module_function(rb_mProcID_Syscall, "issetugid", p_sys_issetugid, 0); } |