diff options
author | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-12-27 00:44:05 +0000 |
---|---|---|
committer | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-12-27 00:44:05 +0000 |
commit | e950d051e18abfb5f7b68e69133fed1ba0e7cff8 (patch) | |
tree | e7587a5f75720b17ce77ac3fd3d6dce08700b97a /io.c | |
parent | e973fe16f1c8becb17d5932a733c464885ea43ca (diff) | |
download | ruby-e950d051e18abfb5f7b68e69133fed1ba0e7cff8.tar.gz |
Added RDoc for class IO
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5314 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'io.c')
-rw-r--r-- | io.c | 821 |
1 files changed, 819 insertions, 2 deletions
@@ -407,6 +407,24 @@ rb_io_fwrite(ptr, len, f) return len - n; } +/* + * 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 + */ + static VALUE io_write(io, str) VALUE io, str; @@ -448,6 +466,22 @@ rb_io_write(io, str) return rb_funcall(io, id_write, 1, 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! + */ + + VALUE rb_io_addstr(io, str) VALUE io, str; @@ -456,6 +490,22 @@ rb_io_addstr(io, str) return io; } +/* + * 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 + */ + static VALUE rb_io_flush(io) VALUE io; @@ -472,6 +522,20 @@ rb_io_flush(io) return 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" + * f.pos #=> 17 + */ + static VALUE rb_io_tell(io) VALUE io; @@ -501,6 +565,27 @@ rb_io_seek(io, offset, whence) return INT2FIX(0); } +/* + * 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 + * | 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" + */ + static VALUE rb_io_seek_m(argc, argv, io) int argc; @@ -517,6 +602,17 @@ rb_io_seek_m(argc, argv, io) return rb_io_seek(io, offset, whence); } +/* + * 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" + */ + static VALUE rb_io_set_pos(io, offset) VALUE io, offset; @@ -532,6 +628,20 @@ rb_io_set_pos(io, offset) return OFFT2NUM(pos); } +/* + * 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 + * f.lineno #=> 0 + * f.readline #=> "This is line one\n" + */ + static VALUE rb_io_rewind(io) VALUE io; @@ -549,6 +659,19 @@ rb_io_rewind(io) return INT2FIX(0); } +/* + * 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 + */ + VALUE rb_io_eof(io) VALUE io; @@ -574,6 +697,19 @@ rb_io_eof(io) return Qtrue; } +/* + * 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 + */ + static VALUE rb_io_sync(io) VALUE io; @@ -584,6 +720,21 @@ rb_io_sync(io) return (fptr->mode & FMODE_SYNC) ? Qtrue : Qfalse; } +/* + * 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> + */ + static VALUE rb_io_set_sync(io, mode) VALUE io, mode; @@ -600,6 +751,18 @@ rb_io_set_sync(io, mode) return 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 + * using <code>IO#sync=</code>. The latter ensures that data is flushed + * from Ruby's buffers, but doesn't not guarantee that the underlying + * operating system actually writes it to disk. + */ + static VALUE rb_io_fsync(io) VALUE io; @@ -622,6 +785,18 @@ rb_io_fsync(io) #endif } +/* + * 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 + */ + static VALUE rb_io_fileno(io) VALUE io; @@ -634,6 +809,27 @@ rb_io_fileno(io) return INT2FIX(fd); } + +/* + * 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 + */ + static VALUE rb_io_pid(io) VALUE io; @@ -646,6 +842,14 @@ rb_io_pid(io) return INT2FIX(fptr->pid); } + +/* + * call-seq: + * ios.inspect => string + * + * Return a string describing this IO object. + */ + static VALUE rb_io_inspect(obj) VALUE obj; @@ -667,6 +871,13 @@ rb_io_inspect(obj) return rb_str_new2(buf); } +/* + * call-seq: + * ios.to_io -> ios + * + * Returns <em>ios</em>. + */ + static VALUE rb_io_to_io(io) VALUE io; @@ -809,6 +1020,20 @@ read_all(fptr, siz, str) return 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" + */ + static VALUE io_read(argc, argv, io) int argc; @@ -1087,6 +1312,23 @@ rb_io_gets(io) return rb_io_getline_fast(fptr, '\n'); } +/* + * 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 + * a time (two successive newlines in the input separate paragraphs). + * The stream must be opened for reading or an <code>IOerror</code> + * 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" + */ + static VALUE rb_io_gets_m(argc, argv, io) int argc; @@ -1111,6 +1353,25 @@ rb_io_gets_m(argc, argv, io) return str; } +/* + * 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" + * f.lineno #=> 1 + * f.gets #=> "This is line two\n" + * f.lineno #=> 2 + */ + static VALUE rb_io_lineno(io) VALUE io; @@ -1122,6 +1383,23 @@ rb_io_lineno(io) return INT2NUM(fptr->lineno); } +/* + * 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 + * f.lineno = 1000 + * f.lineno #=> 1000 + * $. # lineno of last read #=> 1 + * f.gets #=> "This is line two\n" + * $. # lineno of last read #=> 1001 + */ + static VALUE rb_io_set_lineno(io, lineno) VALUE io, lineno; @@ -1159,6 +1437,14 @@ argf_lineno() return 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. + */ + static VALUE rb_io_readline(argc, argv, io) int argc; @@ -1173,6 +1459,21 @@ rb_io_readline(argc, argv, io) return line; } +/* + * 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" + */ + static VALUE rb_io_readlines(argc, argv, io) int argc; @@ -1197,6 +1498,26 @@ rb_io_readlines(argc, argv, io) return ary; } +/* + * 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 + * 4: And so on... + */ + static VALUE rb_io_each_line(argc, argv, io) int argc; @@ -1220,6 +1541,20 @@ rb_io_each_line(argc, argv, io) return io; } +/* + * call-seq: + * ios.each_byte {|byte| block } => nil + * + * 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> + * checksum #=> 12 + */ + static VALUE rb_io_each_byte(io) VALUE io; @@ -1252,6 +1587,18 @@ rb_io_each_byte(io) return 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 + */ + VALUE rb_io_getc(io) VALUE io; @@ -1298,6 +1645,14 @@ rb_getc(f) return c; } +/* + * call-seq: + * ios.readchar => fixnum + * + * Reads a character as with <code>IO#getc</code>, but raises an + * <code>EOFError</code> on end of file. + */ + static VALUE rb_io_readchar(io) VALUE io; @@ -1310,6 +1665,22 @@ rb_io_readchar(io) return c; } +/* + * 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 + * f.getc #=> 84 + */ + VALUE rb_io_ungetc(io, c) VALUE io, c; @@ -1327,6 +1698,18 @@ rb_io_ungetc(io, c) return Qnil; } +/* + * 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 + */ + static VALUE rb_io_isatty(io) VALUE io; @@ -1432,6 +1815,17 @@ rb_io_close(io) return Qnil; } +/* + * 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 + * streams are automatically closed when they are claimed by the + * garbage collector. + */ + static VALUE rb_io_close_m(io) VALUE io; @@ -1451,6 +1845,25 @@ io_close(io) return rb_funcall(io, rb_intern("close"), 0, 0); } +/* + * 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 + * f = IO.popen("/bin/sh","r+") + * f.close_write #=> nil + * f.closed? #=> false + * f.close_read #=> nil + * f.closed? #=> true + */ + + static VALUE rb_io_closed(io) VALUE io; @@ -1461,6 +1874,24 @@ rb_io_closed(io) return (fptr->f || fptr->f2)?Qfalse:Qtrue; } +/* + * 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 + */ + static VALUE rb_io_close_read(io) VALUE io; @@ -1487,6 +1918,25 @@ rb_io_close_read(io) return Qnil; } +/* + * 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 + */ + static VALUE rb_io_close_write(io) VALUE io; @@ -1512,6 +1962,19 @@ rb_io_close_write(io) return Qnil; } +/* + * 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." + */ + static VALUE rb_io_sysseek(argc, argv, io) int argc; @@ -1541,6 +2004,19 @@ rb_io_sysseek(argc, argv, io) return OFFT2NUM(pos); } +/* + * 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 + */ + static VALUE rb_io_syswrite(io, str) VALUE io, str; @@ -1570,6 +2046,20 @@ rb_io_syswrite(io, str) return LONG2FIX(n); } +/* + * 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" + */ + static VALUE rb_io_sysread(argc, argv, io) int argc; @@ -1620,6 +2110,15 @@ rb_io_sysread(argc, argv, io) return str; } +/* + * 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. + */ + VALUE rb_io_binmode(io) VALUE io; @@ -2229,6 +2728,47 @@ rb_io_popen(str, argc, argv, klass) return port; } +/* + * 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 + * standard input and output will be connected to the returned + * <code>IO</code> object. If <i>cmd_string</i> starts with a + * ``<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. + * + * 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>'', + * 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("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f}"} + * + * <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> + */ + static VALUE rb_io_s_popen(argc, argv, klass) int argc; @@ -2276,6 +2816,19 @@ rb_open_file(argc, argv, io) return 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 rb_io_s_open(argc, argv, klass) int argc; @@ -2291,6 +2844,17 @@ rb_io_s_open(argc, argv, klass) return io; } +/* + * 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 rb_io_s_sysopen(argc, argv) int argc; @@ -2450,6 +3014,22 @@ io_reopen(io, nfile) return io; } +/* + * call-seq: + * 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" + * f2.reopen(f1) #=> #<File:testfile> + * f2.readlines[0] #=> "This is line one\n" + */ + static VALUE rb_io_reopen(argc, argv, file) int argc; @@ -2574,6 +3154,15 @@ rb_io_init_copy(dest, io) return dest; } +/* + * 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. + */ + VALUE rb_io_printf(argc, argv, out) int argc; @@ -2605,6 +3194,26 @@ rb_f_printf(argc, argv) return Qnil; } +/* + * 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 + * arguments are given, prints <code>$_</code>. Objects that aren't + * 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. + */ + VALUE rb_io_print(argc, argv, out) int argc; @@ -2649,6 +3258,22 @@ rb_f_print(argc, argv) return Qnil; } +/* + * 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 + */ + static VALUE rb_io_putc(io, ch) VALUE io, ch; @@ -2683,6 +3308,26 @@ io_puts_ary(ary, out) return Qnil; } +/* + * 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 + * test + */ + VALUE rb_io_puts(argc, argv, out) int argc; @@ -2861,6 +3506,24 @@ prep_path(io, path) fptr->path = strdup(path); } +/* + * call-seq: + * IO.new(fd, mode) => 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 + */ + static VALUE rb_io_initialize(argc, argv, io) int argc; @@ -2922,6 +3585,24 @@ rb_file_initialize(argc, argv, io) return 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 + */ + static VALUE rb_io_s_new(argc, argv, klass) int argc; @@ -2937,6 +3618,15 @@ rb_io_s_new(argc, argv, klass) return rb_class_new_instance(argc, argv, klass); } + +/* + * call-seq: + * IO.for_fd(fd, mode) => io + * + * Synonym for <code>IO::new</code>. + * + */ + static VALUE rb_io_s_for_fd(argc, argv, klass) int argc; @@ -3238,6 +3928,16 @@ rb_f_backquote(obj, str) #include <sys/select.h> #endif +/* + * call-seq: + * IO.select(read_array + * [, write_array + * [, error_array + * [, timeout]]] ) => array or nil + * + * See <code>Kernel#select</code>. + */ + static VALUE rb_f_select(argc, argv, obj) int argc; @@ -3475,6 +4175,19 @@ rb_io_ctl(io, req, arg, io_p) #endif } + +/* + * 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 + * string, it is interpreted as a binary sequence of bytes. On Unix + * platforms, see <code>ioctl(2)</code> for details. Not implemented on + * all platforms. + */ + static VALUE rb_io_ioctl(argc, argv, io) int argc; @@ -3487,6 +4200,19 @@ rb_io_ioctl(argc, argv, io) return rb_io_ctl(io, req, arg, 1); } +/* + * 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 + * directly. If it is a string, it is interpreted as a binary sequence + * of bytes (<code>Array#pack</code> might be a useful way to build this + * string). On Unix platforms, see <code>fcntl(2)</code> for details. + * Not implemented on all platforms. + */ + static VALUE rb_io_fcntl(argc, argv, io) int argc; @@ -3613,6 +4339,42 @@ io_new_instance(args) return rb_class_new_instance(2, (VALUE*)args+1, *(VALUE*)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}>" + * rd.close + * Process.wait + * else + * rd.close + * puts "Sending message to parent" + * wr.write "Hi Dad" + * wr.close + * end + * + * <em>produces:</em> + * + * Sending message to parent + * Parent got: <Hi Dad> + */ + static VALUE rb_io_s_pipe(klass) VALUE klass; @@ -3673,6 +4435,23 @@ io_s_foreach(arg) return Qnil; } +/* + * 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) int argc; @@ -3703,6 +4482,19 @@ io_s_readlines(arg) return rb_io_readlines(arg->argc, &arg->sep, arg->io); } +/* + * 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 rb_io_s_readlines(argc, argv, io) int argc; @@ -3728,6 +4520,19 @@ io_s_read(arg) return io_read(arg->argc, &arg->sep, arg->io); } +/* + * 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 " + */ + static VALUE rb_io_s_read(argc, argv, io) int argc; @@ -4060,8 +4865,14 @@ opt_i_set(val) * 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_string</em>. This mode string - * must be one of the values listed in the following table. + * are shown in this section as <em>mode</em>. The mode may + * either be a Fixnum or a String. If numeric, it should be + * one of the operating system specific constants (O_RDONLY, + * O_WRONLY, O_RDWR, O_APPEND and so on). See man open(2) for + * more information. + * + * If the mode is given as a String, it must be one of the + * values listed in the following table. * * Mode | Meaning * -----+-------------------------------------------------------- @@ -4085,6 +4896,12 @@ opt_i_set(val) * "b" | (DOS/Windows only) Binary file mode (may appear with * | any of the key letters listed above). * + * + * The global constant ARGF (also accessible as $<) provides an + * IO-like stream which allows access to all files mentioned on the + * command line (or STDIN if no files are mentioned). ARGF provides + * the methods <code>#path</code> and <code>#filename</code> to access + * the name of the file currently being read. */ void |