File: C:/Ruby27-x64/share/doc/ruby/html/IO.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class IO - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "./";
var index_rel_prefix = "./";
</script>
<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>
<link href="./css/fonts.css" rel="stylesheet">
<link href="./css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="./index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="./table_of_contents.html#pages">Pages</a>
<a href="./table_of_contents.html#classes">Classes</a>
<a href="./table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="Object.html">Object</a>
</div>
<div id="includes-section" class="nav-section">
<h3>Included Modules</h3>
<ul class="link-list">
<li><a class="include" href="File/File/Constants.html">File::File::Constants</a>
<li><a class="include" href="Enumerable.html">Enumerable</a>
</ul>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-binread">::binread</a>
<li ><a href="#method-c-binwrite">::binwrite</a>
<li ><a href="#method-c-console">::console</a>
<li ><a href="#method-c-copy_stream">::copy_stream</a>
<li ><a href="#method-c-for_fd">::for_fd</a>
<li ><a href="#method-c-foreach">::foreach</a>
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-c-open">::open</a>
<li ><a href="#method-c-pipe">::pipe</a>
<li ><a href="#method-c-popen">::popen</a>
<li ><a href="#method-c-read">::read</a>
<li ><a href="#method-c-readlines">::readlines</a>
<li ><a href="#method-c-select">::select</a>
<li ><a href="#method-c-sysopen">::sysopen</a>
<li ><a href="#method-c-try_convert">::try_convert</a>
<li ><a href="#method-c-write">::write</a>
<li ><a href="#method-i-3C-3C">#<<</a>
<li ><a href="#method-i-advise">#advise</a>
<li ><a href="#method-i-autoclose-3D">#autoclose=</a>
<li ><a href="#method-i-autoclose-3F">#autoclose?</a>
<li ><a href="#method-i-beep">#beep</a>
<li ><a href="#method-i-binmode">#binmode</a>
<li ><a href="#method-i-binmode-3F">#binmode?</a>
<li ><a href="#method-i-bytes">#bytes</a>
<li ><a href="#method-i-chars">#chars</a>
<li ><a href="#method-i-check_winsize_changed">#check_winsize_changed</a>
<li ><a href="#method-i-clear_screen">#clear_screen</a>
<li ><a href="#method-i-close">#close</a>
<li ><a href="#method-i-close_on_exec-3D">#close_on_exec=</a>
<li ><a href="#method-i-close_on_exec-3F">#close_on_exec?</a>
<li ><a href="#method-i-close_read">#close_read</a>
<li ><a href="#method-i-close_write">#close_write</a>
<li ><a href="#method-i-closed-3F">#closed?</a>
<li ><a href="#method-i-codepoints">#codepoints</a>
<li ><a href="#method-i-console_mode">#console_mode</a>
<li ><a href="#method-i-console_mode-3D">#console_mode=</a>
<li ><a href="#method-i-cooked">#cooked</a>
<li ><a href="#method-i-cooked-21">#cooked!</a>
<li ><a href="#method-i-cursor">#cursor</a>
<li ><a href="#method-i-cursor-3D">#cursor=</a>
<li ><a href="#method-i-cursor_down">#cursor_down</a>
<li ><a href="#method-i-cursor_left">#cursor_left</a>
<li ><a href="#method-i-cursor_right">#cursor_right</a>
<li ><a href="#method-i-cursor_up">#cursor_up</a>
<li ><a href="#method-i-each">#each</a>
<li ><a href="#method-i-each_byte">#each_byte</a>
<li ><a href="#method-i-each_char">#each_char</a>
<li ><a href="#method-i-each_codepoint">#each_codepoint</a>
<li ><a href="#method-i-each_line">#each_line</a>
<li ><a href="#method-i-echo-3D">#echo=</a>
<li ><a href="#method-i-echo-3F">#echo?</a>
<li ><a href="#method-i-eof">#eof</a>
<li ><a href="#method-i-eof-3F">#eof?</a>
<li ><a href="#method-i-erase_line">#erase_line</a>
<li ><a href="#method-i-erase_screen">#erase_screen</a>
<li ><a href="#method-i-expect">#expect</a>
<li ><a href="#method-i-external_encoding">#external_encoding</a>
<li ><a href="#method-i-fcntl">#fcntl</a>
<li ><a href="#method-i-fdatasync">#fdatasync</a>
<li ><a href="#method-i-fileno">#fileno</a>
<li ><a href="#method-i-flush">#flush</a>
<li ><a href="#method-i-fsync">#fsync</a>
<li ><a href="#method-i-getbyte">#getbyte</a>
<li ><a href="#method-i-getc">#getc</a>
<li ><a href="#method-i-getch">#getch</a>
<li ><a href="#method-i-getpass">#getpass</a>
<li ><a href="#method-i-gets">#gets</a>
<li ><a href="#method-i-goto">#goto</a>
<li ><a href="#method-i-goto_column">#goto_column</a>
<li ><a href="#method-i-iflush">#iflush</a>
<li ><a href="#method-i-inspect">#inspect</a>
<li ><a href="#method-i-internal_encoding">#internal_encoding</a>
<li ><a href="#method-i-ioctl">#ioctl</a>
<li ><a href="#method-i-ioflush">#ioflush</a>
<li ><a href="#method-i-isatty">#isatty</a>
<li ><a href="#method-i-lineno">#lineno</a>
<li ><a href="#method-i-lineno-3D">#lineno=</a>
<li ><a href="#method-i-lines">#lines</a>
<li ><a href="#method-i-noecho">#noecho</a>
<li ><a href="#method-i-nonblock">#nonblock</a>
<li ><a href="#method-i-nonblock-3D">#nonblock=</a>
<li ><a href="#method-i-nonblock-3F">#nonblock?</a>
<li ><a href="#method-i-nread">#nread</a>
<li ><a href="#method-i-oflush">#oflush</a>
<li ><a href="#method-i-pathconf">#pathconf</a>
<li ><a href="#method-i-pid">#pid</a>
<li ><a href="#method-i-pos">#pos</a>
<li ><a href="#method-i-pos-3D">#pos=</a>
<li ><a href="#method-i-pread">#pread</a>
<li ><a href="#method-i-pressed-3F">#pressed?</a>
<li ><a href="#method-i-print">#print</a>
<li ><a href="#method-i-printf">#printf</a>
<li ><a href="#method-i-putc">#putc</a>
<li ><a href="#method-i-puts">#puts</a>
<li ><a href="#method-i-pwrite">#pwrite</a>
<li ><a href="#method-i-raw">#raw</a>
<li ><a href="#method-i-raw-21">#raw!</a>
<li ><a href="#method-i-read">#read</a>
<li ><a href="#method-i-read_nonblock">#read_nonblock</a>
<li ><a href="#method-i-readbyte">#readbyte</a>
<li ><a href="#method-i-readchar">#readchar</a>
<li ><a href="#method-i-readline">#readline</a>
<li ><a href="#method-i-readlines">#readlines</a>
<li ><a href="#method-i-readpartial">#readpartial</a>
<li ><a href="#method-i-ready-3F">#ready?</a>
<li ><a href="#method-i-reopen">#reopen</a>
<li ><a href="#method-i-rewind">#rewind</a>
<li ><a href="#method-i-scroll_backward">#scroll_backward</a>
<li ><a href="#method-i-scroll_forward">#scroll_forward</a>
<li ><a href="#method-i-seek">#seek</a>
<li ><a href="#method-i-set_encoding">#set_encoding</a>
<li ><a href="#method-i-set_encoding_by_bom">#set_encoding_by_bom</a>
<li ><a href="#method-i-stat">#stat</a>
<li ><a href="#method-i-sync">#sync</a>
<li ><a href="#method-i-sync-3D">#sync=</a>
<li ><a href="#method-i-sysread">#sysread</a>
<li ><a href="#method-i-sysseek">#sysseek</a>
<li ><a href="#method-i-syswrite">#syswrite</a>
<li ><a href="#method-i-tell">#tell</a>
<li ><a href="#method-i-to_i">#to_i</a>
<li ><a href="#method-i-to_io">#to_io</a>
<li ><a href="#method-i-tty-3F">#tty?</a>
<li ><a href="#method-i-ungetbyte">#ungetbyte</a>
<li ><a href="#method-i-ungetc">#ungetc</a>
<li ><a href="#method-i-wait">#wait</a>
<li ><a href="#method-i-wait_readable">#wait_readable</a>
<li ><a href="#method-i-wait_writable">#wait_writable</a>
<li ><a href="#method-i-winsize">#winsize</a>
<li ><a href="#method-i-winsize-3D">#winsize=</a>
<li ><a href="#method-i-write">#write</a>
<li ><a href="#method-i-write_nonblock">#write_nonblock</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-IO">
<h1 id="class-IO" class="class">
class IO
</h1>
<section class="description">
<p>Expect library adds the <a href="IO.html"><code>IO</code></a> instance method <a href="IO.html#method-i-expect"><code>expect</code></a>, which does similar act to tcl's expect extension.</p>
<p>In order to use this method, you must require expect:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'expect'</span>
</pre>
<p>Please see <a href="IO.html#method-i-expect"><code>expect</code></a> for usage.</p>
<p>The <a href="IO.html"><code>IO</code></a> class 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.</p>
<p>Many of the examples in this section use the <a href="File.html"><code>File</code></a> class, the only standard subclass of <a href="IO.html"><code>IO</code></a>. The two classes are closely associated. Like the <a href="File.html"><code>File</code></a> class, the <a href="Socket.html"><code>Socket</code></a> library subclasses from <a href="IO.html"><code>IO</code></a> (such as <a href="TCPSocket.html"><code>TCPSocket</code></a> or <a href="UDPSocket.html"><code>UDPSocket</code></a>).</p>
<p>The <a href="Kernel.html#method-i-open"><code>Kernel#open</code></a> method can create an <a href="IO.html"><code>IO</code></a> (or <a href="File.html"><code>File</code></a>) object for these types of arguments:</p>
<ul><li>
<p>A plain string represents a filename suitable for the underlying operating system.</p>
</li><li>
<p>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.</p>
</li><li>
<p>A string equal to <code>"|-"</code> will create another Ruby instance as a subprocess.</p>
</li></ul>
<p>The <a href="IO.html"><code>IO</code></a> may be opened with different file modes (read-only, write-only) and encodings for proper conversion. See <a href="IO.html#method-c-new"><code>IO.new</code></a> for these options. See <a href="Kernel.html#method-i-open"><code>Kernel#open</code></a> for details of the various command formats described above.</p>
<p><a href="IO.html#method-c-popen"><code>IO.popen</code></a>, the <a href="Open3.html"><code>Open3</code></a> library, or Process#spawn may also be used to communicate with subprocesses through an <a href="IO.html"><code>IO</code></a>.</p>
<p>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:</p>
<pre class="ruby"><span class="ruby-string">"C:\\gumby\\ruby\\test.rb"</span>
</pre>
<p>Our examples here will use the Unix-style forward slashes; File::ALT_SEPARATOR can be used to get the platform-specific separator character.</p>
<p>The global constant <a href="ARGF.html"><code>ARGF</code></a> (also accessible as <code>$<</code>) provides an IO-like stream which allows access to all files mentioned on the command line (or STDIN if no files are mentioned). <a href="ARGF.html#method-i-path"><code>ARGF#path</code></a> and its alias <a href="ARGF.html#method-i-filename"><code>ARGF#filename</code></a> are provided to access the name of the file currently being read.</p>
<h2 id="class-IO-label-io-2Fconsole">io/console<span><a href="#class-IO-label-io-2Fconsole">¶</a> <a href="#top">↑</a></span></h2>
<p>The io/console extension provides methods for interacting with the console. The console can be accessed from <a href="IO.html#method-c-console"><code>IO.console</code></a> or the standard input/output/error <a href="IO.html"><code>IO</code></a> objects.</p>
<p>Requiring io/console adds the following methods:</p>
<ul><li>
<p><a href="IO.html#method-c-console"><code>IO::console</code></a></p>
</li><li>
<p><a href="IO.html#method-i-raw"><code>IO#raw</code></a></p>
</li><li>
<p><a href="IO.html#method-i-raw-21"><code>IO#raw!</code></a></p>
</li><li>
<p><a href="IO.html#method-i-cooked"><code>IO#cooked</code></a></p>
</li><li>
<p><a href="IO.html#method-i-cooked-21"><code>IO#cooked!</code></a></p>
</li><li>
<p><a href="IO.html#method-i-getch"><code>IO#getch</code></a></p>
</li><li>
<p><a href="IO.html#method-i-echo-3D"><code>IO#echo=</code></a></p>
</li><li>
<p><a href="IO.html#method-i-echo-3F"><code>IO#echo?</code></a></p>
</li><li>
<p><a href="IO.html#method-i-noecho"><code>IO#noecho</code></a></p>
</li><li>
<p><a href="IO.html#method-i-winsize"><code>IO#winsize</code></a></p>
</li><li>
<p><a href="IO.html#method-i-winsize-3D"><code>IO#winsize=</code></a></p>
</li><li>
<p><a href="IO.html#method-i-iflush"><code>IO#iflush</code></a></p>
</li><li>
<p><a href="IO.html#method-i-ioflush"><code>IO#ioflush</code></a></p>
</li><li>
<p><a href="IO.html#method-i-oflush"><code>IO#oflush</code></a></p>
</li></ul>
<p>Example:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'io/console'</span>
<span class="ruby-identifier">rows</span>, <span class="ruby-identifier">columns</span> = <span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">winsize</span>
<span class="ruby-identifier">puts</span> <span class="ruby-node">"Your screen is #{columns} wide and #{rows} tall"</span>
</pre>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="EWOULDBLOCKWaitReadable">EWOULDBLOCKWaitReadable
<dd><p><a href="IO/EAGAINWaitReadable.html"><code>EAGAINWaitReadable</code></a></p>
<dt id="EWOULDBLOCKWaitWritable">EWOULDBLOCKWaitWritable
<dd><p><a href="IO/EAGAINWaitWritable.html"><code>EAGAINWaitWritable</code></a></p>
<dt id="SEEK_CUR">SEEK_CUR
<dd><p><a href="Set.html"><code>Set</code></a> I/O position from the current position</p>
<dt id="SEEK_DATA">SEEK_DATA
<dd><p><a href="Set.html"><code>Set</code></a> I/O position to the next location containing data</p>
<dt id="SEEK_END">SEEK_END
<dd><p><a href="Set.html"><code>Set</code></a> I/O position from the end</p>
<dt id="SEEK_HOLE">SEEK_HOLE
<dd><p><a href="Set.html"><code>Set</code></a> I/O position to the next hole</p>
<dt id="SEEK_SET">SEEK_SET
<dd><p><a href="Set.html"><code>Set</code></a> I/O position from the beginning</p>
</dl>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-binread" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
binread(name, [length [, offset]] ) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Opens the file, optionally seeks to the given <em>offset</em>, then returns <em>length</em> bytes (defaulting to the rest of the file). binread ensures the file is closed before returning. The open mode would be <code>"rb:ASCII-8BIT"</code>.</p>
<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">binread</span>(<span class="ruby-string">"testfile"</span>) <span class="ruby-comment">#=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">binread</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-value">20</span>) <span class="ruby-comment">#=> "This is line one\nThi"</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">binread</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-value">20</span>, <span class="ruby-value">10</span>) <span class="ruby-comment">#=> "ne one\nThis is line "</span>
</pre>
<div class="method-source-code" id="binread-source">
<pre>static VALUE
rb_io_s_binread(int argc, VALUE *argv, VALUE io)
{
VALUE offset;
struct foreach_arg arg;
enum {
fmode = FMODE_READABLE|FMODE_BINMODE,
oflags = O_RDONLY
#ifdef O_BINARY
|O_BINARY
#endif
};
convconfig_t convconfig = {NULL, NULL, 0, Qnil};
rb_scan_args(argc, argv, "12", NULL, NULL, &offset);
FilePathValue(argv[0]);
convconfig.enc = rb_ascii8bit_encoding();
arg.io = rb_io_open_generic(io, argv[0], oflags, fmode, &convconfig, 0);
if (NIL_P(arg.io)) return Qnil;
arg.argv = argv+1;
arg.argc = (argc > 1) ? 1 : 0;
if (!NIL_P(offset)) {
struct seek_arg sarg;
int state = 0;
sarg.io = arg.io;
sarg.offset = offset;
sarg.mode = SEEK_SET;
rb_protect(seek_before_access, (VALUE)&sarg, &state);
if (state) {
rb_io_close(arg.io);
rb_jump_tag(state);
}
}
return rb_ensure(io_s_read, (VALUE)&arg, rb_io_close, arg.io);
}</pre>
</div>
</div>
</div>
<div id="method-c-binwrite" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
binwrite(name, string, [offset] ) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
binwrite(name, string, [offset], open_args ) → integer
</span>
</div>
<div class="method-description">
<p>Same as <a href="IO.html#method-c-write"><code>IO.write</code></a> except opening the file in binary mode and ASCII-8BIT encoding (<code>"wb:ASCII-8BIT"</code>).</p>
<div class="method-source-code" id="binwrite-source">
<pre>static VALUE
rb_io_s_binwrite(int argc, VALUE *argv, VALUE io)
{
return io_s_write(argc, argv, io, 1);
}</pre>
</div>
</div>
</div>
<div id="method-c-console" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
console → #<File:/dev/tty>
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
console(sym, *args)
</span>
</div>
<div class="method-description">
<p>Returns an <a href="File.html"><code>File</code></a> instance opened console.</p>
<p>If <code>sym</code> is given, it will be sent to the opened console with <code>args</code> and the result will be returned instead of the console <a href="IO.html"><code>IO</code></a> itself.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="console-source">
<pre>static VALUE
console_dev(int argc, VALUE *argv, VALUE klass)
{
VALUE con = 0;
rb_io_t *fptr;
VALUE sym = 0;
rb_check_arity(argc, 0, UNLIMITED_ARGUMENTS);
if (argc) {
Check_Type(sym = argv[0], T_SYMBOL);
}
if (klass == rb_cIO) klass = rb_cFile;
if (rb_const_defined(klass, id_console)) {
con = rb_const_get(klass, id_console);
if (!RB_TYPE_P(con, T_FILE) ||
(!(fptr = RFILE(con)->fptr) || GetReadFD(fptr) == -1)) {
rb_const_remove(klass, id_console);
con = 0;
}
}
if (sym) {
if (sym == ID2SYM(id_close) && argc == 1) {
if (con) {
rb_io_close(con);
rb_const_remove(klass, id_console);
con = 0;
}
return Qnil;
}
}
if (!con) {
VALUE args[2];
#if defined HAVE_TERMIOS_H || defined HAVE_TERMIO_H || defined HAVE_SGTTY_H
# define CONSOLE_DEVICE "/dev/tty"
#elif defined _WIN32
# define CONSOLE_DEVICE "con$"
# define CONSOLE_DEVICE_FOR_READING "conin$"
# define CONSOLE_DEVICE_FOR_WRITING "conout$"
#endif
#ifndef CONSOLE_DEVICE_FOR_READING
# define CONSOLE_DEVICE_FOR_READING CONSOLE_DEVICE
#endif
#ifdef CONSOLE_DEVICE_FOR_WRITING
VALUE out;
rb_io_t *ofptr;
#endif
int fd;
#ifdef CONSOLE_DEVICE_FOR_WRITING
fd = rb_cloexec_open(CONSOLE_DEVICE_FOR_WRITING, O_RDWR, 0);
if (fd < 0) return Qnil;
rb_update_max_fd(fd);
args[1] = INT2FIX(O_WRONLY);
args[0] = INT2NUM(fd);
out = rb_class_new_instance(2, args, klass);
#endif
fd = rb_cloexec_open(CONSOLE_DEVICE_FOR_READING, O_RDWR, 0);
if (fd < 0) {
#ifdef CONSOLE_DEVICE_FOR_WRITING
rb_io_close(out);
#endif
return Qnil;
}
rb_update_max_fd(fd);
args[1] = INT2FIX(O_RDWR);
args[0] = INT2NUM(fd);
con = rb_class_new_instance(2, args, klass);
GetOpenFile(con, fptr);
fptr->pathv = rb_obj_freeze(rb_str_new2(CONSOLE_DEVICE));
#ifdef CONSOLE_DEVICE_FOR_WRITING
GetOpenFile(out, ofptr);
ofptr->pathv = fptr->pathv;
fptr->tied_io_for_writing = out;
ofptr->mode |= FMODE_SYNC;
#endif
fptr->mode |= FMODE_SYNC;
rb_const_set(klass, id_console, con);
}
if (sym) {
return rb_f_send(argc, argv, con);
}
return con;
}</pre>
</div>
</div>
</div>
<div id="method-c-copy_stream" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
copy_stream(src, dst)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
copy_stream(src, dst, copy_length)
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
copy_stream(src, dst, copy_length, src_offset)
</span>
</div>
<div class="method-description">
<p><a href="IO.html#method-c-copy_stream"><code>IO.copy_stream</code></a> copies <em>src</em> to <em>dst</em>. <em>src</em> and <em>dst</em> is either a filename or an IO-like object. IO-like object for <em>src</em> should have <a href="IO.html#method-i-readpartial"><code>readpartial</code></a> or <a href="IO.html#method-i-read"><code>read</code></a> method. IO-like object for <em>dst</em> should have <a href="IO.html#method-i-write"><code>write</code></a> method. (Specialized mechanisms, such as sendfile system call, may be used on appropriate situation.)</p>
<p>This method returns the number of bytes copied.</p>
<p>If optional arguments are not given, the start position of the copy is the beginning of the filename or the current file offset of the <a href="IO.html"><code>IO</code></a>. The end position of the copy is the end of file.</p>
<p>If <em>copy_length</em> is given, No more than <em>copy_length</em> bytes are copied.</p>
<p>If <em>src_offset</em> is given, it specifies the start position of the copy.</p>
<p>When <em>src_offset</em> is specified and <em>src</em> is an <a href="IO.html"><code>IO</code></a>, <a href="IO.html#method-c-copy_stream"><code>IO.copy_stream</code></a> doesn't move the current file offset.</p>
<div class="method-source-code" id="copy_stream-source">
<pre>static VALUE
rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io)
{
VALUE src, dst, length, src_offset;
struct copy_stream_struct st;
MEMZERO(&st, struct copy_stream_struct, 1);
rb_scan_args(argc, argv, "22", &src, &dst, &length, &src_offset);
st.src = src;
st.dst = dst;
if (NIL_P(length))
st.copy_length = (off_t)-1;
else
st.copy_length = NUM2OFFT(length);
if (NIL_P(src_offset))
st.src_offset = (off_t)-1;
else
st.src_offset = NUM2OFFT(src_offset);
rb_ensure(copy_stream_body, (VALUE)&st, copy_stream_finalize, (VALUE)&st);
return OFFT2NUM(st.total);
}</pre>
</div>
</div>
</div>
<div id="method-c-for_fd" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
for_fd(fd, mode [, opt]) → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Synonym for <a href="IO.html#method-c-new"><code>IO.new</code></a>.</p>
<div class="method-source-code" id="for_fd-source">
<pre>static VALUE
rb_io_s_for_fd(int argc, VALUE *argv, VALUE klass)
{
VALUE io = rb_obj_alloc(klass);
rb_io_initialize(argc, argv, io);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-c-foreach" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
foreach(name, sep=$/ [, getline_args, open_args]) {|line| block } → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
foreach(name, limit [, getline_args, open_args]) {|line| block } → nil
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
foreach(name, sep, limit [, getline_args, open_args]) {|line| block } → nil
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
foreach(...) → an_enumerator
</span>
</div>
<div class="method-description">
<p>Executes the block for every line in the named I/O port, where lines are separated by <em>sep</em>.</p>
<p>If no block is given, an enumerator is returned instead.</p>
<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">foreach</span>(<span class="ruby-string">"testfile"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span> <span class="ruby-identifier">print</span> <span class="ruby-string">"GOT "</span>, <span class="ruby-identifier">x</span> }
</pre>
<p><em>produces:</em></p>
<pre class="ruby"><span class="ruby-constant">GOT</span> <span class="ruby-constant">This</span> <span class="ruby-identifier">is</span> <span class="ruby-identifier">line</span> <span class="ruby-identifier">one</span>
<span class="ruby-constant">GOT</span> <span class="ruby-constant">This</span> <span class="ruby-identifier">is</span> <span class="ruby-identifier">line</span> <span class="ruby-identifier">two</span>
<span class="ruby-constant">GOT</span> <span class="ruby-constant">This</span> <span class="ruby-identifier">is</span> <span class="ruby-identifier">line</span> <span class="ruby-identifier">three</span>
<span class="ruby-constant">GOT</span> <span class="ruby-constant">And</span> <span class="ruby-identifier">so</span> <span class="ruby-identifier">on</span><span class="ruby-operator">...</span>
</pre>
<p>If the last argument is a hash, it's the keyword argument to open. See <a href="IO.html#method-c-readlines"><code>IO.readlines</code></a> for details about getline_args. And see also <a href="IO.html#method-c-read"><code>IO.read</code></a> for details about open_args.</p>
<div class="method-source-code" id="foreach-source">
<pre>static VALUE
rb_io_s_foreach(int argc, VALUE *argv, VALUE self)
{
VALUE opt;
int orig_argc = argc;
struct foreach_arg arg;
struct getline_arg garg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, NULL, NULL, &opt);
RETURN_ENUMERATOR(self, orig_argc, argv);
extract_getline_args(argc-1, argv+1, &garg);
open_key_args(self, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
extract_getline_opts(opt, &garg);
check_getline_args(&garg.rs, &garg.limit, garg.io = arg.io);
return rb_ensure(io_s_foreach, (VALUE)&garg, rb_io_close, arg.io);
}</pre>
</div>
</div>
</div>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
new(fd [, mode] [, opt]) → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a new <a href="IO.html"><code>IO</code></a> object (a stream) for the given integer file descriptor <code>fd</code> and <code>mode</code> string. <code>opt</code> may be used to specify parts of <code>mode</code> in a more readable fashion. See also <a href="IO.html#method-c-sysopen"><code>IO.sysopen</code></a> and <a href="IO.html#method-c-for_fd"><code>IO.for_fd</code></a>.</p>
<p><a href="IO.html#method-c-new"><code>IO.new</code></a> is called by various <a href="File.html"><code>File</code></a> and <a href="IO.html"><code>IO</code></a> opening methods such as <a href="IO.html#method-c-open"><code>IO::open</code></a>, <a href="Kernel.html#method-i-open"><code>Kernel#open</code></a>, and <a href="File.html#method-c-open"><code>File::open</code></a>.</p>
<h3 id="method-c-new-label-Open+Mode">Open Mode<span><a href="#method-c-new-label-Open+Mode">¶</a> <a href="#top">↑</a></span></h3>
<p>When <code>mode</code> is an integer it must be combination of the modes defined in <a href="File/File/Constants.html"><code>File::Constants</code></a> (<code>File::RDONLY</code>, <code>File::WRONLY|File::CREAT</code>). See the open(2) man page for more information.</p>
<p>When <code>mode</code> is a string it must be in one of the following forms:</p>
<pre>fmode
fmode ":" ext_enc
fmode ":" ext_enc ":" int_enc
fmode ":" "BOM|UTF-*"</pre>
<p><code>fmode</code> is an <a href="IO.html"><code>IO</code></a> open mode string, <code>ext_enc</code> is the external encoding for the <a href="IO.html"><code>IO</code></a> and <code>int_enc</code> is the internal encoding.</p>
<h4 id="method-c-new-label-IO+Open+Mode"><a href="IO.html"><code>IO</code></a> Open Mode<span><a href="#method-c-new-label-IO+Open+Mode">¶</a> <a href="#top">↑</a></span></h4>
<p>Ruby allows the following open modes:</p>
<pre>"r" Read-only, starts at beginning of file (default mode).
"r+" Read-write, starts at beginning of 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
or creates a new file for reading and writing.
"a" Write-only, each write call appends data at end of file.
Creates a new file for writing if file does not exist.
"a+" Read-write, each write call appends data at end of file.
Creates a new file for reading and writing if file does
not exist.</pre>
<p>The following modes must be used separately, and along with one or more of the modes seen above.</p>
<pre>"b" Binary file mode
Suppresses EOL <-> CRLF conversion on Windows. And
sets external encoding to ASCII-8BIT unless explicitly
specified.
"t" Text file mode</pre>
<p>The exclusive access mode (“x”) can be used together with “w” to ensure the file is created. Errno::EEXIST is raised when it already exists. It may not be supported with all kinds of streams (e.g. pipes).</p>
<p>When the open mode of original <a href="IO.html"><code>IO</code></a> is read only, the mode cannot be changed to be writable. Similarly, the open mode cannot be changed from write only to readable.</p>
<p>When such a change is attempted the error is raised in different locations according to the platform.</p>
<h3 id="method-c-new-label-IO+Encoding"><a href="IO.html"><code>IO</code></a> <a href="Encoding.html"><code>Encoding</code></a><span><a href="#method-c-new-label-IO+Encoding">¶</a> <a href="#top">↑</a></span></h3>
<p>When <code>ext_enc</code> is specified, strings read will be tagged by the encoding when reading, and strings output will be converted to the specified encoding when writing.</p>
<p>When <code>ext_enc</code> and <code>int_enc</code> are specified read strings will be converted from <code>ext_enc</code> to <code>int_enc</code> upon input, and written strings will be converted from <code>int_enc</code> to <code>ext_enc</code> upon output. See <a href="Encoding.html"><code>Encoding</code></a> for further details of transcoding on input and output.</p>
<p>If “BOM|UTF-8”, “BOM|UTF-16LE” or “BOM|UTF16-BE” are used, Ruby checks for a Unicode BOM in the input document to help determine the encoding. For UTF-16 encodings the file open mode must be binary. When present, the BOM is stripped and the external encoding from the BOM is used. When the BOM is missing the given Unicode encoding is used as <code>ext_enc</code>. (The BOM-set encoding option is case insensitive, so “bom|utf-8” is also valid.)</p>
<h3 id="method-c-new-label-Options">Options<span><a href="#method-c-new-label-Options">¶</a> <a href="#top">↑</a></span></h3>
<p><code>opt</code> can be used instead of <code>mode</code> for improved readability. The following keys are supported:</p>
<dl class="rdoc-list note-list"><dt>:mode
<dd>
<p>Same as <code>mode</code> parameter</p>
</dd><dt>:flags
<dd>
<p>Specifies file open flags as integer. If <code>mode</code> parameter is given, this parameter will be bitwise-ORed.</p>
</dd><dt>:external_encoding
<dd>
<p>External encoding for the <a href="IO.html"><code>IO</code></a>.</p>
</dd><dt>:internal_encoding
<dd>
<p>Internal encoding for the <a href="IO.html"><code>IO</code></a>. “-” is a synonym for the default internal encoding.</p>
<p>If the value is <code>nil</code> no conversion occurs.</p>
</dd><dt>:encoding
<dd>
<p>Specifies external and internal encodings as “extern:intern”.</p>
</dd><dt>:textmode
<dd>
<p>If the value is truth value, same as “t” in argument <code>mode</code>.</p>
</dd><dt>:binmode
<dd>
<p>If the value is truth value, same as “b” in argument <code>mode</code>.</p>
</dd><dt>:autoclose
<dd>
<p>If the value is <code>false</code>, the <code>fd</code> will be kept open after this <a href="IO.html"><code>IO</code></a> instance gets finalized.</p>
</dd></dl>
<p>Also, <code>opt</code> can have same keys in <a href="String.html#method-i-encode"><code>String#encode</code></a> for controlling conversion between the external encoding and the internal encoding.</p>
<h3 id="method-c-new-label-Example+1">Example 1<span><a href="#method-c-new-label-Example+1">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">fd</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">sysopen</span>(<span class="ruby-string">"/dev/tty"</span>, <span class="ruby-string">"w"</span>)
<span class="ruby-identifier">a</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>,<span class="ruby-string">"w"</span>)
<span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"Hello"</span>
<span class="ruby-identifier">a</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"World"</span>
</pre>
<p>Produces:</p>
<pre class="ruby"><span class="ruby-constant">Hello</span>
<span class="ruby-constant">World</span>
</pre>
<h3 id="method-c-new-label-Example+2">Example 2<span><a href="#method-c-new-label-Example+2">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'fcntl'</span>
<span class="ruby-identifier">fd</span> = <span class="ruby-constant">STDERR</span>.<span class="ruby-identifier">fcntl</span>(<span class="ruby-constant">Fcntl</span><span class="ruby-operator">::</span><span class="ruby-constant">F_DUPFD</span>)
<span class="ruby-identifier">io</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>, <span class="ruby-value">mode:</span> <span class="ruby-string">'w:UTF-16LE'</span>, <span class="ruby-value">cr_newline:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"Hello, World!"</span>
<span class="ruby-identifier">fd</span> = <span class="ruby-constant">STDERR</span>.<span class="ruby-identifier">fcntl</span>(<span class="ruby-constant">Fcntl</span><span class="ruby-operator">::</span><span class="ruby-constant">F_DUPFD</span>)
<span class="ruby-identifier">io</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">fd</span>, <span class="ruby-value">mode:</span> <span class="ruby-string">'w'</span>, <span class="ruby-value">cr_newline:</span> <span class="ruby-keyword">true</span>,
<span class="ruby-value">external_encoding:</span> <span class="ruby-constant">Encoding</span><span class="ruby-operator">::</span><span class="ruby-constant">UTF_16LE</span>)
<span class="ruby-identifier">io</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"Hello, World!"</span>
</pre>
<p>Both of above print “Hello, World!” in UTF-16LE to standard error output with converting EOL generated by <a href="IO.html#method-i-puts"><code>puts</code></a> to CR.</p>
<div class="method-source-code" id="new-source">
<pre>static VALUE
rb_io_initialize(int argc, VALUE *argv, VALUE io)
{
VALUE fnum, vmode;
rb_io_t *fp;
int fd, fmode, oflags = O_RDONLY;
convconfig_t convconfig;
VALUE opt;
#if defined(HAVE_FCNTL) && defined(F_GETFL)
int ofmode;
#else
struct stat st;
#endif
argc = rb_scan_args(argc, argv, "11:", &fnum, &vmode, &opt);
rb_io_extract_modeenc(&vmode, 0, opt, &oflags, &fmode, &convconfig);
fd = NUM2INT(fnum);
if (rb_reserved_fd_p(fd)) {
rb_raise(rb_eArgError, "The given fd is not accessible because RubyVM reserves it");
}
#if defined(HAVE_FCNTL) && defined(F_GETFL)
oflags = fcntl(fd, F_GETFL);
if (oflags == -1) rb_sys_fail(0);
#else
if (fstat(fd, &st) < 0) rb_sys_fail(0);
#endif
rb_update_max_fd(fd);
#if defined(HAVE_FCNTL) && defined(F_GETFL)
ofmode = rb_io_oflags_fmode(oflags);
if (NIL_P(vmode)) {
fmode = ofmode;
}
else if ((~ofmode & fmode) & FMODE_READWRITE) {
VALUE error = INT2FIX(EINVAL);
rb_exc_raise(rb_class_new_instance(1, &error, rb_eSystemCallError));
}
#endif
if (!NIL_P(opt) && rb_hash_aref(opt, sym_autoclose) == Qfalse) {
fmode |= FMODE_PREP;
}
MakeOpenFile(io, fp);
fp->fd = fd;
fp->mode = fmode;
fp->encs = convconfig;
clear_codeconv(fp);
io_check_tty(fp);
if (fileno(stdin) == fd)
fp->stdio_file = stdin;
else if (fileno(stdout) == fd)
fp->stdio_file = stdout;
else if (fileno(stderr) == fd)
fp->stdio_file = stderr;
if (fmode & FMODE_SETENC_BY_BOM) io_set_encoding_by_bom(io);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-c-open" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
open(fd, mode="r" [, opt]) → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
open(fd, mode="r" [, opt]) {|io| block } → obj
</span>
</div>
<div class="method-description">
<p>With no associated block, <a href="IO.html#method-c-open"><code>IO.open</code></a> is a synonym for <a href="IO.html#method-c-new"><code>IO.new</code></a>. If the optional code block is given, it will be passed <code>io</code> as an argument, and the <a href="IO.html"><code>IO</code></a> object will automatically be closed when the block terminates. In this instance, <a href="IO.html#method-c-open"><code>IO.open</code></a> returns the value of the block.</p>
<p>See <a href="IO.html#method-c-new"><code>IO.new</code></a> for a description of the <code>fd</code>, <code>mode</code> and <code>opt</code> parameters.</p>
<div class="method-source-code" id="open-source">
<pre>static VALUE
rb_io_s_open(int argc, VALUE *argv, VALUE klass)
{
VALUE io = rb_class_new_instance_kw(argc, argv, klass, RB_PASS_CALLED_KEYWORDS);
if (rb_block_given_p()) {
return rb_ensure(rb_yield, io, io_close, io);
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-c-pipe" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pipe → [read_io, write_io]
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
pipe(ext_enc) → [read_io, write_io]
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
pipe("ext_enc:int_enc" [, opt]) → [read_io, write_io]
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
pipe(ext_enc, int_enc [, opt]) → [read_io, write_io]
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
pipe(...) {|read_io, write_io| ... }
</span>
</div>
<div class="method-description">
<p>Creates a pair of pipe endpoints (connected to each other) and returns them as a two-element array of <a href="IO.html"><code>IO</code></a> objects: <code>[</code> <em>read_io</em>, <em>write_io</em> <code>]</code>.</p>
<p>If a block is given, the block is called and returns the value of the block. <em>read_io</em> and <em>write_io</em> are sent to the block as arguments. If read_io and write_io are not closed when the block exits, they are closed. i.e. closing read_io and/or write_io doesn't cause an error.</p>
<p>Not available on all platforms.</p>
<p>If an encoding (encoding name or encoding object) is specified as an optional argument, read string from pipe is tagged with the encoding specified. If the argument is a colon separated two encoding names “A:B”, the read string is converted from encoding A (external encoding) to encoding B (internal encoding), then tagged with B. If two optional arguments are specified, those must be encoding objects or encoding names, and the first one is the external encoding, and the second one is the internal encoding. If the external encoding and the internal encoding is specified, optional hash argument specify the conversion option.</p>
<p>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>.</p>
<pre class="ruby"><span class="ruby-identifier">rd</span>, <span class="ruby-identifier">wr</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">fork</span>
<span class="ruby-identifier">wr</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">puts</span> <span class="ruby-node">"Parent got: <#{rd.read}>"</span>
<span class="ruby-identifier">rd</span>.<span class="ruby-identifier">close</span>
<span class="ruby-constant">Process</span>.<span class="ruby-identifier">wait</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">rd</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">"Sending message to parent"</span>
<span class="ruby-identifier">wr</span>.<span class="ruby-identifier">write</span> <span class="ruby-string">"Hi Dad"</span>
<span class="ruby-identifier">wr</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>
</pre>
<p><em>produces:</em></p>
<pre>Sending message to parent
Parent got: <Hi Dad></pre>
<div class="method-source-code" id="pipe-source">
<pre>static VALUE
rb_io_s_pipe(int argc, VALUE *argv, VALUE klass)
{
int pipes[2], state;
VALUE r, w, args[3], v1, v2;
VALUE opt;
rb_io_t *fptr, *fptr2;
struct io_encoding_set_args ies_args;
int fmode = 0;
VALUE ret;
argc = rb_scan_args(argc, argv, "02:", &v1, &v2, &opt);
if (rb_pipe(pipes) < 0)
rb_sys_fail(0);
args[0] = klass;
args[1] = INT2NUM(pipes[0]);
args[2] = INT2FIX(O_RDONLY);
r = rb_protect(io_new_instance, (VALUE)args, &state);
if (state) {
close(pipes[0]);
close(pipes[1]);
rb_jump_tag(state);
}
GetOpenFile(r, fptr);
ies_args.fptr = fptr;
ies_args.v1 = v1;
ies_args.v2 = v2;
ies_args.opt = opt;
rb_protect(io_encoding_set_v, (VALUE)&ies_args, &state);
if (state) {
close(pipes[1]);
io_close(r);
rb_jump_tag(state);
}
args[1] = INT2NUM(pipes[1]);
args[2] = INT2FIX(O_WRONLY);
w = rb_protect(io_new_instance, (VALUE)args, &state);
if (state) {
close(pipes[1]);
if (!NIL_P(r)) rb_io_close(r);
rb_jump_tag(state);
}
GetOpenFile(w, fptr2);
rb_io_synchronized(fptr2);
extract_binmode(opt, &fmode);
if ((fmode & FMODE_BINMODE) && v1 == Qnil) {
rb_io_ascii8bit_binmode(r);
rb_io_ascii8bit_binmode(w);
}
#if DEFAULT_TEXTMODE
if ((fptr->mode & FMODE_TEXTMODE) && (fmode & FMODE_BINMODE)) {
fptr->mode &= ~FMODE_TEXTMODE;
setmode(fptr->fd, O_BINARY);
}
#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
if (fptr->encs.ecflags & ECONV_DEFAULT_NEWLINE_DECORATOR) {
fptr->encs.ecflags |= ECONV_UNIVERSAL_NEWLINE_DECORATOR;
}
#endif
#endif
fptr->mode |= fmode;
#if DEFAULT_TEXTMODE
if ((fptr2->mode & FMODE_TEXTMODE) && (fmode & FMODE_BINMODE)) {
fptr2->mode &= ~FMODE_TEXTMODE;
setmode(fptr2->fd, O_BINARY);
}
#endif
fptr2->mode |= fmode;
ret = rb_assoc_new(r, w);
if (rb_block_given_p()) {
VALUE rw[2];
rw[0] = r;
rw[1] = w;
return rb_ensure(rb_yield, ret, pipe_pair_close, (VALUE)rw);
}
return ret;
}</pre>
</div>
</div>
</div>
<div id="method-c-popen" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
popen([env,] cmd, mode="r" [, opt]) → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
popen([env,] cmd, mode="r" [, opt]) {|io| block } → obj
</span>
</div>
<div class="method-description">
<p>Runs the specified command as a subprocess; the subprocess's standard input and output will be connected to the returned <a href="IO.html"><code>IO</code></a> object.</p>
<p>The PID of the started process can be obtained by <a href="IO.html#method-i-pid"><code>IO#pid</code></a> method.</p>
<p><em>cmd</em> is a string or an array as follows.</p>
<pre>cmd:
"-" : fork
commandline : command line string which is passed to a shell
[env, cmdname, arg1, ..., opts] : command name and zero or more arguments (no shell)
[env, [cmdname, argv0], arg1, ..., opts] : command name, argv[0] and zero or more arguments (no shell)
(env and opts are optional.)</pre>
<p>If <em>cmd</em> is a <code>String</code> “<code>-</code>'', then a new instance of Ruby is started as the subprocess.</p>
<p>If <em>cmd</em> is an <code>Array</code> of <code>String</code>, then it will be used as the subprocess's <code>argv</code> bypassing a shell. The array can contain a hash at first for environments and a hash at last for options similar to <a href="Kernel.html#method-i-spawn"><code>spawn</code></a>.</p>
<p>The default mode for the new file object is “r'', but <em>mode</em> may be set to any of the modes listed in the description for class <a href="IO.html"><code>IO</code></a>. The last argument <em>opt</em> qualifies <em>mode</em>.</p>
<pre class="ruby"><span class="ruby-comment"># set IO encoding</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"nkf -e filename"</span>, <span class="ruby-value">:external_encoding</span><span class="ruby-operator">=></span><span class="ruby-string">"EUC-JP"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">nkf_io</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">euc_jp_string</span> = <span class="ruby-identifier">nkf_io</span>.<span class="ruby-identifier">read</span>
}
<span class="ruby-comment"># merge standard output and standard error using</span>
<span class="ruby-comment"># spawn option. See the document of Kernel.spawn.</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>([<span class="ruby-string">"ls"</span>, <span class="ruby-string">"/"</span>, <span class="ruby-value">:err</span><span class="ruby-operator">=></span>[<span class="ruby-value">:child</span>, <span class="ruby-value">:out</span>]]) {<span class="ruby-operator">|</span><span class="ruby-identifier">ls_io</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">ls_result_with_error</span> = <span class="ruby-identifier">ls_io</span>.<span class="ruby-identifier">read</span>
}
<span class="ruby-comment"># spawn options can be mixed with IO options</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>([<span class="ruby-string">"ls"</span>, <span class="ruby-string">"/"</span>], <span class="ruby-value">:err</span><span class="ruby-operator">=></span>[<span class="ruby-value">:child</span>, <span class="ruby-value">:out</span>]) {<span class="ruby-operator">|</span><span class="ruby-identifier">ls_io</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">ls_result_with_error</span> = <span class="ruby-identifier">ls_io</span>.<span class="ruby-identifier">read</span>
}
</pre>
<p>Raises exceptions which <a href="IO.html#method-c-pipe"><code>IO.pipe</code></a> and <a href="Kernel.html#method-i-spawn"><code>Kernel.spawn</code></a> raise.</p>
<p>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. At the end of block, Ruby closes the pipe and sets <code>$?</code>. In this case <a href="IO.html#method-c-popen"><code>IO.popen</code></a> returns the value of the block.</p>
<p>If a block is given with a <em>cmd</em> 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.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"uname"</span>)
<span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span>
<span class="ruby-identifier">puts</span> <span class="ruby-node">"Parent is #{Process.pid}"</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"date"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">puts</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> }
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"-"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span> <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">"#{Process.pid} is here, f is #{f.inspect}"</span>}
<span class="ruby-identifier">p</span> <span class="ruby-identifier">$?</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-node">%w"sed -e s|^|<foo>| -e s&$&;zot;&"</span>, <span class="ruby-string">"r+"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"bar"</span>; <span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_write</span>; <span class="ruby-identifier">puts</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>
}
</pre>
<p><em>produces:</em></p>
<pre>["Linux\n"]
Parent is 21346
Thu Jan 15 22:41:19 JST 2009
21346 is here, f is #<IO:fd 3>
21352 is here, f is nil
#<Process::Status: pid 21352 exit 0>
<foo>bar;zot;</pre>
<div class="method-source-code" id="popen-source">
<pre>static VALUE
rb_io_s_popen(int argc, VALUE *argv, VALUE klass)
{
const char *modestr;
VALUE pname, pmode = Qnil, port, tmp, opt = Qnil, env = Qnil, execarg_obj = Qnil;
int oflags, fmode;
convconfig_t convconfig;
if (argc > 1 && !NIL_P(opt = rb_check_hash_type(argv[argc-1]))) --argc;
if (argc > 1 && !NIL_P(env = rb_check_hash_type(argv[0]))) --argc, ++argv;
switch (argc) {
case 2:
pmode = argv[1];
case 1:
pname = argv[0];
break;
default:
{
int ex = !NIL_P(opt);
rb_error_arity(argc + ex, 1 + ex, 2 + ex);
}
}
tmp = rb_check_array_type(pname);
if (!NIL_P(tmp)) {
long len = RARRAY_LEN(tmp);
#if SIZEOF_LONG > SIZEOF_INT
if (len > INT_MAX) {
rb_raise(rb_eArgError, "too many arguments");
}
#endif
execarg_obj = rb_execarg_new((int)len, RARRAY_CONST_PTR(tmp), FALSE, FALSE);
RB_GC_GUARD(tmp);
}
else {
SafeStringValue(pname);
execarg_obj = Qnil;
if (!is_popen_fork(pname))
execarg_obj = rb_execarg_new(1, &pname, TRUE, FALSE);
}
if (!NIL_P(execarg_obj)) {
if (!NIL_P(opt))
opt = rb_execarg_extract_options(execarg_obj, opt);
if (!NIL_P(env))
rb_execarg_setenv(execarg_obj, env);
}
rb_io_extract_modeenc(&pmode, 0, opt, &oflags, &fmode, &convconfig);
modestr = rb_io_oflags_modestr(oflags);
port = pipe_open(execarg_obj, modestr, fmode, &convconfig);
if (NIL_P(port)) {
/* child */
if (rb_block_given_p()) {
rb_yield(Qnil);
rb_io_flush(rb_stdout);
rb_io_flush(rb_stderr);
_exit(0);
}
return Qnil;
}
RBASIC_SET_CLASS(port, klass);
if (rb_block_given_p()) {
return rb_ensure(rb_yield, port, pipe_close, port);
}
return port;
}</pre>
</div>
</div>
</div>
<div id="method-c-read" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
read(name, [length [, offset]] [, opt] ) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Opens the file, optionally seeks to the given <code>offset</code>, then returns <code>length</code> bytes (defaulting to the rest of the file). <a href="IO.html#method-i-read"><code>read</code></a> ensures the file is closed before returning.</p>
<p>If <code>name</code> starts with a pipe character (<code>"|"</code>), a subprocess is created in the same way as <a href="Kernel.html#method-i-open"><code>Kernel#open</code></a>, and its output is returned.</p>
<h3 id="method-c-read-label-Options">Options<span><a href="#method-c-read-label-Options">¶</a> <a href="#top">↑</a></span></h3>
<p>The options hash accepts the following keys:</p>
<dl class="rdoc-list note-list"><dt>:encoding
<dd>
<p>string or encoding</p>
<p>Specifies the encoding of the read string. <code>:encoding</code> will be ignored if <code>length</code> is specified. See <a href="Encoding.html#method-c-aliases"><code>Encoding.aliases</code></a> for possible encodings.</p>
</dd><dt>:mode
<dd>
<p>string or integer</p>
<p>Specifies the <em>mode</em> argument for open(). It must start with an “r”, otherwise it will cause an error. See <a href="IO.html#method-c-new"><code>IO.new</code></a> for the list of possible modes.</p>
</dd><dt>:open_args
<dd>
<p>array</p>
<p>Specifies arguments for open() as an array. This key can not be used in combination with either <code>:encoding</code> or <code>:mode</code>.</p>
</dd></dl>
<p>Examples:</p>
<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">"testfile"</span>) <span class="ruby-comment">#=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-value">20</span>) <span class="ruby-comment">#=> "This is line one\nThi"</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-value">20</span>, <span class="ruby-value">10</span>) <span class="ruby-comment">#=> "ne one\nThis is line "</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">"binfile"</span>, <span class="ruby-value">mode:</span> <span class="ruby-string">"rb"</span>) <span class="ruby-comment">#=> "\xF7\x00\x00\x0E\x12"</span>
</pre>
<div class="method-source-code" id="read-source">
<pre>static VALUE
rb_io_s_read(int argc, VALUE *argv, VALUE io)
{
VALUE opt, offset;
struct foreach_arg arg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, &offset, NULL, &opt);
open_key_args(io, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
if (!NIL_P(offset)) {
struct seek_arg sarg;
int state = 0;
sarg.io = arg.io;
sarg.offset = offset;
sarg.mode = SEEK_SET;
rb_protect(seek_before_access, (VALUE)&sarg, &state);
if (state) {
rb_io_close(arg.io);
rb_jump_tag(state);
}
if (arg.argc == 2) arg.argc = 1;
}
return rb_ensure(io_s_read, (VALUE)&arg, rb_io_close, arg.io);
}</pre>
</div>
</div>
</div>
<div id="method-c-readlines" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
readlines(name, sep=$/ [, getline_args, open_args]) → array
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readlines(name, limit [, getline_args, open_args]) → array
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readlines(name, sep, limit [, getline_args, open_args]) → array
</span>
</div>
<div class="method-description">
<p>Reads the entire file specified by <em>name</em> as individual lines, and returns those lines in an array. Lines are separated by <em>sep</em>.</p>
<pre class="ruby"><span class="ruby-identifier">a</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">a</span>[<span class="ruby-value">0</span>] <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">b</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">readlines</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">b</span>[<span class="ruby-value">0</span>] <span class="ruby-comment">#=> "This is line one"</span>
</pre>
<p>If the last argument is a hash, it's the keyword argument to open.</p>
<h3 id="method-c-readlines-label-Options+for+getline">Options for getline<span><a href="#method-c-readlines-label-Options+for+getline">¶</a> <a href="#top">↑</a></span></h3>
<p>The options hash accepts the following keys:</p>
<dl class="rdoc-list note-list"><dt>:chomp
<dd>
<p>When the optional <code>chomp</code> keyword argument has a true value, <code>\n</code>, <code>\r</code>, and <code>\r\n</code> will be removed from the end of each line.</p>
</dd></dl>
<p>See also <a href="IO.html#method-c-read"><code>IO.read</code></a> for details about open_args.</p>
<div class="method-source-code" id="readlines-source">
<pre>static VALUE
rb_io_s_readlines(int argc, VALUE *argv, VALUE io)
{
VALUE opt;
struct foreach_arg arg;
struct getline_arg garg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, NULL, NULL, &opt);
extract_getline_args(argc-1, argv+1, &garg);
open_key_args(io, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
extract_getline_opts(opt, &garg);
check_getline_args(&garg.rs, &garg.limit, garg.io = arg.io);
return rb_ensure(io_s_readlines, (VALUE)&garg, rb_io_close, arg.io);
}</pre>
</div>
</div>
</div>
<div id="method-c-select" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
select(read_array [, write_array [, error_array [, timeout]]]) → array or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Calls select(2) system call. It monitors given arrays of <a href="IO.html"><code>IO</code></a> objects, waits until one or more of <a href="IO.html"><code>IO</code></a> objects are ready for reading, are ready for writing, and have pending exceptions respectively, and returns an array that contains arrays of those <a href="IO.html"><code>IO</code></a> objects. It will return <code>nil</code> if optional <em>timeout</em> value is given and no <a href="IO.html"><code>IO</code></a> object is ready in <em>timeout</em> seconds.</p>
<p><a href="IO.html#method-c-select"><code>IO.select</code></a> peeks the buffer of <a href="IO.html"><code>IO</code></a> objects for testing readability. If the <a href="IO.html"><code>IO</code></a> buffer is not empty, <a href="IO.html#method-c-select"><code>IO.select</code></a> immediately notifies readability. This “peek” only happens for <a href="IO.html"><code>IO</code></a> objects. It does not happen for IO-like objects such as <a href="OpenSSL/SSL/SSLSocket.html"><code>OpenSSL::SSL::SSLSocket</code></a>.</p>
<p>The best way to use <a href="IO.html#method-c-select"><code>IO.select</code></a> is invoking it after nonblocking methods such as <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a>, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a>, etc. The methods raise an exception which is extended by <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> or <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. The modules notify how the caller should wait with <a href="IO.html#method-c-select"><code>IO.select</code></a>. If <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> is raised, the caller should wait for reading. If <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> is raised, the caller should wait for writing.</p>
<p>So, blocking read (<a href="IO.html#method-i-readpartial"><code>readpartial</code></a>) can be emulated using <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> and <a href="IO.html#method-c-select"><code>IO.select</code></a> as follows:</p>
<pre class="ruby"><span class="ruby-keyword">begin</span>
<span class="ruby-identifier">result</span> = <span class="ruby-identifier">io_like</span>.<span class="ruby-identifier">read_nonblock</span>(<span class="ruby-identifier">maxlen</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">io_like</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitWritable</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>(<span class="ruby-keyword">nil</span>, [<span class="ruby-identifier">io_like</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
</pre>
<p>Especially, the combination of nonblocking methods and <a href="IO.html#method-c-select"><code>IO.select</code></a> is preferred for <a href="IO.html"><code>IO</code></a> like objects such as <a href="OpenSSL/SSL/SSLSocket.html"><code>OpenSSL::SSL::SSLSocket</code></a>. It has <a href="IO.html#method-i-to_io"><code>to_io</code></a> method to return underlying <a href="IO.html"><code>IO</code></a> object. <a href="IO.html#method-c-select"><code>IO.select</code></a> calls <a href="IO.html#method-i-to_io"><code>to_io</code></a> to obtain the file descriptor to wait.</p>
<p>This means that readability notified by <a href="IO.html#method-c-select"><code>IO.select</code></a> doesn't mean readability from <a href="OpenSSL/SSL/SSLSocket.html"><code>OpenSSL::SSL::SSLSocket</code></a> object.</p>
<p>The most likely situation is that <a href="OpenSSL/SSL/SSLSocket.html"><code>OpenSSL::SSL::SSLSocket</code></a> buffers some data. <a href="IO.html#method-c-select"><code>IO.select</code></a> doesn't see the buffer. So <a href="IO.html#method-c-select"><code>IO.select</code></a> can block when <a href="OpenSSL/Buffering.html#method-i-readpartial"><code>OpenSSL::SSL::SSLSocket#readpartial</code></a> doesn't block.</p>
<p>However, several more complicated situations exist.</p>
<p>SSL is a protocol which is sequence of records. The record consists of multiple bytes. So, the remote side of SSL sends a partial record, <a href="IO.html#method-c-select"><code>IO.select</code></a> notifies readability but <a href="OpenSSL/SSL/SSLSocket.html"><code>OpenSSL::SSL::SSLSocket</code></a> cannot decrypt a byte and <a href="OpenSSL/Buffering.html#method-i-readpartial"><code>OpenSSL::SSL::SSLSocket#readpartial</code></a> will block.</p>
<p>Also, the remote side can request SSL renegotiation which forces the local SSL engine to write some data. This means <a href="OpenSSL/Buffering.html#method-i-readpartial"><code>OpenSSL::SSL::SSLSocket#readpartial</code></a> may invoke <a href="IO.html#method-i-write"><code>write</code></a> system call and it can block. In such a situation, <a href="OpenSSL/Buffering.html#method-i-read_nonblock"><code>OpenSSL::SSL::SSLSocket#read_nonblock</code></a> raises <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> instead of blocking. So, the caller should wait for ready for writability as above example.</p>
<p>The combination of nonblocking methods and <a href="IO.html#method-c-select"><code>IO.select</code></a> is also useful for streams such as tty, pipe socket socket when multiple processes read from a stream.</p>
<p>Finally, Linux kernel developers don't guarantee that readability of select(2) means readability of following read(2) even for a single process. See select(2) manual on GNU/Linux system.</p>
<p>Invoking <a href="IO.html#method-c-select"><code>IO.select</code></a> before <a href="IO.html#method-i-readpartial"><code>IO#readpartial</code></a> works well as usual. However it is not the best way to use <a href="IO.html#method-c-select"><code>IO.select</code></a>.</p>
<p>The writability notified by select(2) doesn't show how many bytes are writable. <a href="IO.html#method-i-write"><code>IO#write</code></a> method blocks until given whole string is written. So, <code>IO#write(two or more bytes)</code> can block after writability is notified by <a href="IO.html#method-c-select"><code>IO.select</code></a>. <a href="IO.html#method-i-write_nonblock"><code>IO#write_nonblock</code></a> is required to avoid the blocking.</p>
<p>Blocking write (<a href="IO.html#method-i-write"><code>write</code></a>) can be emulated using <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> and <a href="IO.html#method-c-select"><code>IO.select</code></a> as follows: <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> should also be rescued for SSL renegotiation in <a href="OpenSSL/SSL/SSLSocket.html"><code>OpenSSL::SSL::SSLSocket</code></a>.</p>
<pre class="ruby"><span class="ruby-keyword">while</span> <span class="ruby-value">0</span> <span class="ruby-operator"><</span> <span class="ruby-identifier">string</span>.<span class="ruby-identifier">bytesize</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">written</span> = <span class="ruby-identifier">io_like</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-identifier">string</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">io_like</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitWritable</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>(<span class="ruby-keyword">nil</span>, [<span class="ruby-identifier">io_like</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">string</span> = <span class="ruby-identifier">string</span>.<span class="ruby-identifier">byteslice</span>(<span class="ruby-identifier">written</span><span class="ruby-operator">..</span><span class="ruby-value">-1</span>)
<span class="ruby-keyword">end</span>
</pre>
<h3 id="method-c-select-label-Parameters">Parameters<span><a href="#method-c-select-label-Parameters">¶</a> <a href="#top">↑</a></span></h3>
<dl class="rdoc-list note-list"><dt>read_array
<dd>
<p>an array of <a href="IO.html"><code>IO</code></a> objects that wait until ready for read</p>
</dd><dt>write_array
<dd>
<p>an array of <a href="IO.html"><code>IO</code></a> objects that wait until ready for write</p>
</dd><dt>error_array
<dd>
<p>an array of <a href="IO.html"><code>IO</code></a> objects that wait for exceptions</p>
</dd><dt>timeout
<dd>
<p>a numeric value in second</p>
</dd></dl>
<h3 id="method-c-select-label-Example">Example<span><a href="#method-c-select-label-Example">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">rp</span>, <span class="ruby-identifier">wp</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">mesg</span> = <span class="ruby-string">"ping "</span>
<span class="ruby-value">100</span>.<span class="ruby-identifier">times</span> {
<span class="ruby-comment"># IO.select follows IO#read. Not the best way to use IO.select.</span>
<span class="ruby-identifier">rs</span>, <span class="ruby-identifier">ws</span>, = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">rp</span>], [<span class="ruby-identifier">wp</span>])
<span class="ruby-keyword">if</span> <span class="ruby-identifier">r</span> = <span class="ruby-identifier">rs</span>[<span class="ruby-value">0</span>]
<span class="ruby-identifier">ret</span> = <span class="ruby-identifier">r</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">5</span>)
<span class="ruby-identifier">print</span> <span class="ruby-identifier">ret</span>
<span class="ruby-keyword">case</span> <span class="ruby-identifier">ret</span>
<span class="ruby-keyword">when</span> <span class="ruby-regexp">/ping/</span>
<span class="ruby-identifier">mesg</span> = <span class="ruby-string">"pong\n"</span>
<span class="ruby-keyword">when</span> <span class="ruby-regexp">/pong/</span>
<span class="ruby-identifier">mesg</span> = <span class="ruby-string">"ping "</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">w</span> = <span class="ruby-identifier">ws</span>[<span class="ruby-value">0</span>]
<span class="ruby-identifier">w</span>.<span class="ruby-identifier">write</span>(<span class="ruby-identifier">mesg</span>)
<span class="ruby-keyword">end</span>
}
</pre>
<p><em>produces:</em></p>
<pre class="ruby"><span class="ruby-identifier">ping</span> <span class="ruby-identifier">pong</span>
<span class="ruby-identifier">ping</span> <span class="ruby-identifier">pong</span>
<span class="ruby-identifier">ping</span> <span class="ruby-identifier">pong</span>
(<span class="ruby-identifier">snipped</span>)
<span class="ruby-identifier">ping</span>
</pre>
<div class="method-source-code" id="select-source">
<pre>static VALUE
rb_f_select(int argc, VALUE *argv, VALUE obj)
{
VALUE timeout;
struct select_args args;
struct timeval timerec;
int i;
rb_scan_args(argc, argv, "13", &args.read, &args.write, &args.except, &timeout);
if (NIL_P(timeout)) {
args.timeout = 0;
}
else {
timerec = rb_time_interval(timeout);
args.timeout = &timerec;
}
for (i = 0; i < numberof(args.fdsets); ++i)
rb_fd_init(&args.fdsets[i]);
return rb_ensure(select_call, (VALUE)&args, select_end, (VALUE)&args);
}</pre>
</div>
</div>
</div>
<div id="method-c-sysopen" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
sysopen(path, [mode, [perm]]) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Opens the given path, returning the underlying file descriptor as a <a href="Integer.html"><code>Integer</code></a>.</p>
<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">sysopen</span>(<span class="ruby-string">"testfile"</span>) <span class="ruby-comment">#=> 3</span>
</pre>
<div class="method-source-code" id="sysopen-source">
<pre>static VALUE
rb_io_s_sysopen(int argc, VALUE *argv, VALUE _)
{
VALUE fname, vmode, vperm;
VALUE intmode;
int oflags, fd;
mode_t perm;
rb_scan_args(argc, argv, "12", &fname, &vmode, &vperm);
FilePathValue(fname);
if (NIL_P(vmode))
oflags = O_RDONLY;
else if (!NIL_P(intmode = rb_check_to_integer(vmode, "to_int")))
oflags = NUM2INT(intmode);
else {
SafeStringValue(vmode);
oflags = rb_io_modestr_oflags(StringValueCStr(vmode));
}
if (NIL_P(vperm)) perm = 0666;
else perm = NUM2MODET(vperm);
RB_GC_GUARD(fname) = rb_str_new4(fname);
fd = rb_sysopen(fname, oflags, perm);
return INT2NUM(fd);
}</pre>
</div>
</div>
</div>
<div id="method-c-try_convert" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
try_convert(obj) → io or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Try to convert <em>obj</em> into an <a href="IO.html"><code>IO</code></a>, using <a href="IO.html#method-i-to_io"><code>to_io</code></a> method. Returns converted <a href="IO.html"><code>IO</code></a> or <code>nil</code> if <em>obj</em> cannot be converted for any reason.</p>
<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">try_convert</span>(<span class="ruby-constant">STDOUT</span>) <span class="ruby-comment">#=> STDOUT</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">try_convert</span>(<span class="ruby-string">"STDOUT"</span>) <span class="ruby-comment">#=> nil</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">'zlib'</span>
<span class="ruby-identifier">f</span> = <span class="ruby-identifier">open</span>(<span class="ruby-string">"/tmp/zz.gz"</span>) <span class="ruby-comment">#=> #<File:/tmp/zz.gz></span>
<span class="ruby-identifier">z</span> = <span class="ruby-constant">Zlib</span><span class="ruby-operator">::</span><span class="ruby-constant">GzipReader</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">f</span>) <span class="ruby-comment">#=> #<Zlib::GzipReader:0x81d8744></span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">try_convert</span>(<span class="ruby-identifier">z</span>) <span class="ruby-comment">#=> #<File:/tmp/zz.gz></span>
</pre>
<div class="method-source-code" id="try_convert-source">
<pre>static VALUE
rb_io_s_try_convert(VALUE dummy, VALUE io)
{
return rb_io_check_io(io);
}</pre>
</div>
</div>
</div>
<div id="method-c-write" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
write(name, string [, offset]) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
write(name, string [, offset] [, opt]) → integer
</span>
</div>
<div class="method-description">
<p>Opens the file, optionally seeks to the given <em>offset</em>, writes <em>string</em>, then returns the length written. <a href="IO.html#method-i-write"><code>write</code></a> ensures the file is closed before returning. If <em>offset</em> is not given in write mode, the file is truncated. Otherwise, it is not truncated.</p>
<pre class="ruby"><span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-string">"0123456789"</span>, <span class="ruby-value">20</span>) <span class="ruby-comment">#=> 10</span>
<span class="ruby-comment"># File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-string">"0123456789"</span>) <span class="ruby-comment">#=> 10</span>
<span class="ruby-comment"># File would now read: "0123456789"</span>
</pre>
<p>If the last argument is a hash, it specifies options for the internal open(). It accepts the following keys:</p>
<dl class="rdoc-list note-list"><dt>:encoding
<dd>
<p>string or encoding</p>
<p>Specifies the encoding of the read string. See <a href="Encoding.html#method-c-aliases"><code>Encoding.aliases</code></a> for possible encodings.</p>
</dd><dt>:mode
<dd>
<p>string or integer</p>
<p>Specifies the <em>mode</em> argument for open(). It must start with “w”, “a”, or “r+”, otherwise it will cause an error. See <a href="IO.html#method-c-new"><code>IO.new</code></a> for the list of possible modes.</p>
</dd><dt>:perm
<dd>
<p>integer</p>
<p>Specifies the <em>perm</em> argument for open().</p>
</dd><dt>:open_args
<dd>
<p>array</p>
<p>Specifies arguments for open() as an array. This key can not be used in combination with other keys.</p>
</dd></dl>
<div class="method-source-code" id="write-source">
<pre>static VALUE
rb_io_s_write(int argc, VALUE *argv, VALUE io)
{
return io_s_write(argc, argv, io, 0);
}</pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-3C-3C" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ios << obj → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p><a href="String.html"><code>String</code></a> Output—Writes <em>obj</em> to <em>ios</em>. <em>obj</em> will be converted to a string using <code>to_s</code>.</p>
<pre class="ruby"><span class="ruby-identifier">$stdout</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"Hello "</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"world!\n"</span>
</pre>
<p><em>produces:</em></p>
<pre class="ruby"><span class="ruby-constant">Hello</span> <span class="ruby-identifier">world!</span>
</pre>
<div class="method-source-code" id="3C-3C-source">
<pre>VALUE
rb_io_addstr(VALUE io, VALUE str)
{
rb_io_write(io, str);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-advise" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
advise(advice, offset=0, len=0) → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Announce an intention to access data from the current file in a specific pattern. On platforms that do not support the <em>posix_fadvise(2)</em> system call, this method is a no-op.</p>
<p><em>advice</em> is one of the following symbols:</p>
<dl class="rdoc-list note-list"><dt>:normal
<dd>
<p>No advice to give; the default assumption for an open file.</p>
</dd><dt>:sequential
<dd>
<p>The data will be accessed sequentially with lower offsets read before higher ones.</p>
</dd><dt>:random
<dd>
<p>The data will be accessed in random order.</p>
</dd><dt>:willneed
<dd>
<p>The data will be accessed in the near future.</p>
</dd><dt>:dontneed
<dd>
<p>The data will not be accessed in the near future.</p>
</dd><dt>:noreuse
<dd>
<p>The data will only be accessed once.</p>
</dd></dl>
<p>The semantics of a piece of advice are platform-dependent. See <em>man 2 posix_fadvise</em> for details.</p>
<p>“data” means the region of the current file that begins at <em>offset</em> and extends for <em>len</em> bytes. If <em>len</em> is 0, the region ends at the last byte of the file. By default, both <em>offset</em> and <em>len</em> are 0, meaning that the advice applies to the entire file.</p>
<p>If an error occurs, one of the following exceptions will be raised:</p>
<dl class="rdoc-list note-list"><dt><a href="IOError.html"><code>IOError</code></a>
<dd>
<p>The <a href="IO.html"><code>IO</code></a> stream is closed.</p>
</dd><dt>Errno::EBADF
<dd>
<p>The file descriptor of the current file is invalid.</p>
</dd><dt>Errno::EINVAL
<dd>
<p>An invalid value for <em>advice</em> was given.</p>
</dd><dt>Errno::ESPIPE
<dd>
<p>The file descriptor of the current file refers to a FIFO or pipe. (Linux raises Errno::EINVAL in this case).</p>
</dd><dt><a href="TypeError.html"><code>TypeError</code></a>
<dd>
<p>Either <em>advice</em> was not a <a href="Symbol.html"><code>Symbol</code></a>, or one of the other arguments was not an <a href="Integer.html"><code>Integer</code></a>.</p>
</dd><dt><a href="RangeError.html"><code>RangeError</code></a>
<dd>
<p>One of the arguments given was too big/small.</p>
</dd><dt>This list is not exhaustive; other <a href="Errno.html"><code>Errno</code></a>
<dd>
<p>exceptions are also possible.</p>
</dd></dl>
<div class="method-source-code" id="advise-source">
<pre>static VALUE
rb_io_advise(int argc, VALUE *argv, VALUE io)
{
VALUE advice, offset, len;
off_t off, l;
rb_io_t *fptr;
rb_scan_args(argc, argv, "12", &advice, &offset, &len);
advice_arg_check(advice);
io = GetWriteIO(io);
GetOpenFile(io, fptr);
off = NIL_P(offset) ? 0 : NUM2OFFT(offset);
l = NIL_P(len) ? 0 : NUM2OFFT(len);
#ifdef HAVE_POSIX_FADVISE
return do_io_advise(fptr, advice, off, l);
#else
((void)off, (void)l); /* Ignore all hint */
return Qnil;
#endif
}</pre>
</div>
</div>
</div>
<div id="method-i-autoclose-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
autoclose = bool → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets auto-close flag.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-identifier">open</span>(<span class="ruby-string">"/dev/null"</span>)
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">for_fd</span>(<span class="ruby-identifier">f</span>.<span class="ruby-identifier">fileno</span>)
<span class="ruby-comment"># ...</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># may cause Errno::EBADF</span>
<span class="ruby-identifier">f</span> = <span class="ruby-identifier">open</span>(<span class="ruby-string">"/dev/null"</span>)
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">for_fd</span>(<span class="ruby-identifier">f</span>.<span class="ruby-identifier">fileno</span>).<span class="ruby-identifier">autoclose</span> = <span class="ruby-keyword">false</span>
<span class="ruby-comment"># ...</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment"># won't cause Errno::EBADF</span>
</pre>
<div class="method-source-code" id="autoclose-3D-source">
<pre>static VALUE
rb_io_set_autoclose(VALUE io, VALUE autoclose)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!RTEST(autoclose))
fptr->mode |= FMODE_PREP;
else
fptr->mode &= ~FMODE_PREP;
return autoclose;
}</pre>
</div>
</div>
</div>
<div id="method-i-autoclose-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
autoclose? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if the underlying file descriptor of <em>ios</em> will be closed automatically at its finalization, otherwise <code>false</code>.</p>
<div class="method-source-code" id="autoclose-3F-source">
<pre>static VALUE
rb_io_autoclose_p(VALUE io)
{
rb_io_t *fptr = RFILE(io)->fptr;
rb_io_check_closed(fptr);
return (fptr->mode & FMODE_PREP) ? Qfalse : Qtrue;
}</pre>
</div>
</div>
</div>
<div id="method-i-beep" class="method-detail ">
<div class="method-heading">
<span class="method-name">beep</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="beep-source">
<pre>static VALUE
console_beep(VALUE io)
{
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetWriteFD(fptr);
#ifdef _WIN32
(void)fd;
MessageBeep(0);
#else
if (write(fd, "\a", 1) < 0)
rb_sys_fail(0);
#endif
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-binmode" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
binmode → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Puts <em>ios</em> into binary mode. Once a stream is in binary mode, it cannot be reset to nonbinary mode.</p>
<ul><li>
<p>newline conversion disabled</p>
</li><li>
<p>encoding conversion disabled</p>
</li><li>
<p>content is treated as ASCII-8BIT</p>
</li></ul>
<div class="method-source-code" id="binmode-source">
<pre>static VALUE
rb_io_binmode_m(VALUE io)
{
VALUE write_io;
rb_io_ascii8bit_binmode(io);
write_io = GetWriteIO(io);
if (write_io != io)
rb_io_ascii8bit_binmode(write_io);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-binmode-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
binmode? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if <em>ios</em> is binmode.</p>
<div class="method-source-code" id="binmode-3F-source">
<pre>static VALUE
rb_io_binmode_p(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
return fptr->mode & FMODE_BINMODE ? Qtrue : Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-bytes" class="method-detail ">
<div class="method-heading">
<span class="method-name">bytes</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This is a deprecated alias for <a href="IO.html#method-i-each_byte"><code>each_byte</code></a>.</p>
<div class="method-source-code" id="bytes-source">
<pre>static VALUE
rb_io_bytes(VALUE io)
{
rb_warn_deprecated("IO#bytes", "#each_byte");
if (!rb_block_given_p())
return rb_enumeratorize(io, ID2SYM(rb_intern("each_byte")), 0, 0);
return rb_io_each_byte(io);
}</pre>
</div>
</div>
</div>
<div id="method-i-chars" class="method-detail ">
<div class="method-heading">
<span class="method-name">chars</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This is a deprecated alias for <a href="IO.html#method-i-each_char"><code>each_char</code></a>.</p>
<div class="method-source-code" id="chars-source">
<pre>static VALUE
rb_io_chars(VALUE io)
{
rb_warn_deprecated("IO#chars", "#each_char");
if (!rb_block_given_p())
return rb_enumeratorize(io, ID2SYM(rb_intern("each_char")), 0, 0);
return rb_io_each_char(io);
}</pre>
</div>
</div>
</div>
<div id="method-i-check_winsize_changed" class="method-detail ">
<div class="method-heading">
<span class="method-name">check_winsize_changed</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="check_winsize_changed-source">
<pre>static VALUE
console_check_winsize_changed(VALUE io)
{
rb_io_t *fptr;
HANDLE h;
DWORD num;
GetOpenFile(io, fptr);
h = (HANDLE)rb_w32_get_osfhandle(GetReadFD(fptr));
while (GetNumberOfConsoleInputEvents(h, &num) && num > 0) {
INPUT_RECORD rec;
if (ReadConsoleInput(h, &rec, 1, &num)) {
if (rec.EventType == WINDOW_BUFFER_SIZE_EVENT) {
rb_yield(Qnil);
}
}
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-clear_screen" class="method-detail ">
<div class="method-heading">
<span class="method-name">clear_screen</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="clear_screen-source">
<pre>static VALUE
console_clear_screen(VALUE io)
{
console_erase_screen(io, INT2FIX(2));
console_goto(io, INT2FIX(0), INT2FIX(0));
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-close" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
close → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Closes <em>ios</em> and flushes any pending writes to the operating system. The stream is unavailable for any further data operations; an <a href="IOError.html"><code>IOError</code></a> is raised if such an attempt is made. I/O streams are automatically closed when they are claimed by the garbage collector.</p>
<p>If <em>ios</em> is opened by <a href="IO.html#method-c-popen"><code>IO.popen</code></a>, <a href="IO.html#method-i-close"><code>close</code></a> sets <code>$?</code>.</p>
<p>Calling this method on closed <a href="IO.html"><code>IO</code></a> object is just ignored since Ruby 2.3.</p>
<div class="method-source-code" id="close-source">
<pre>static VALUE
rb_io_close_m(VALUE io)
{
rb_io_t *fptr = rb_io_get_fptr(io);
if (fptr->fd < 0) {
return Qnil;
}
rb_io_close(io);
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-close_on_exec-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
close_on_exec = bool → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets a close-on-exec flag.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-identifier">open</span>(<span class="ruby-string">"/dev/null"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">system</span>(<span class="ruby-string">"cat"</span>, <span class="ruby-node">"/proc/self/fd/#{f.fileno}"</span>) <span class="ruby-comment"># cat: /proc/self/fd/3: No such file or directory</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">closed?</span> <span class="ruby-comment">#=> false</span>
</pre>
<p>Ruby sets close-on-exec flags of all file descriptors by default since Ruby 2.0.0. So you don't need to set by yourself. Also, unsetting a close-on-exec flag can cause file descriptor leak if another thread use fork() and exec() (via system() method for example). If you really needs file descriptor inheritance to child process, use spawn()'s argument such as fd=>fd.</p>
<div class="method-source-code" id="close_on_exec-3D-source">
<pre>static VALUE
rb_io_set_close_on_exec(VALUE io, VALUE arg)
{
int flag = RTEST(arg) ? FD_CLOEXEC : 0;
rb_io_t *fptr;
VALUE write_io;
int fd, ret;
write_io = GetWriteIO(io);
if (io != write_io) {
GetOpenFile(write_io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fptr->fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if ((ret & FD_CLOEXEC) != flag) {
ret = (ret & ~FD_CLOEXEC) | flag;
ret = fcntl(fd, F_SETFD, ret);
if (ret != 0) rb_sys_fail_path(fptr->pathv);
}
}
}
GetOpenFile(io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if ((ret & FD_CLOEXEC) != flag) {
ret = (ret & ~FD_CLOEXEC) | flag;
ret = fcntl(fd, F_SETFD, ret);
if (ret != 0) rb_sys_fail_path(fptr->pathv);
}
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-close_on_exec-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
close_on_exec? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if <em>ios</em> will be closed on exec.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-identifier">open</span>(<span class="ruby-string">"/dev/null"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec?</span> <span class="ruby-comment">#=> false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec?</span> <span class="ruby-comment">#=> true</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec</span> = <span class="ruby-keyword">false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_on_exec?</span> <span class="ruby-comment">#=> false</span>
</pre>
<div class="method-source-code" id="close_on_exec-3F-source">
<pre>static VALUE
rb_io_close_on_exec_p(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
int fd, ret;
write_io = GetWriteIO(io);
if (io != write_io) {
GetOpenFile(write_io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if (!(ret & FD_CLOEXEC)) return Qfalse;
}
}
GetOpenFile(io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if (!(ret & FD_CLOEXEC)) return Qfalse;
}
return Qtrue;
}</pre>
</div>
</div>
</div>
<div id="method-i-close_read" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
close_read → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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 <a href="IOError.html"><code>IOError</code></a> if the stream is not duplexed.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"/bin/sh"</span>,<span class="ruby-string">"r+"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_read</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>
</pre>
<p><em>produces:</em></p>
<pre>prog.rb:3:in `readlines': not opened for reading (IOError)
from prog.rb:3</pre>
<p>Calling this method on closed <a href="IO.html"><code>IO</code></a> object is just ignored since Ruby 2.3.</p>
<div class="method-source-code" id="close_read-source">
<pre>static VALUE
rb_io_close_read(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
fptr = rb_io_get_fptr(rb_io_taint_check(io));
if (fptr->fd < 0) return Qnil;
if (is_socket(fptr->fd, fptr->pathv)) {
#ifndef SHUT_RD
# define SHUT_RD 0
#endif
if (shutdown(fptr->fd, SHUT_RD) < 0)
rb_sys_fail_path(fptr->pathv);
fptr->mode &= ~FMODE_READABLE;
if (!(fptr->mode & FMODE_WRITABLE))
return rb_io_close(io);
return Qnil;
}
write_io = GetWriteIO(io);
if (io != write_io) {
rb_io_t *wfptr;
wfptr = rb_io_get_fptr(rb_io_taint_check(write_io));
wfptr->pid = fptr->pid;
fptr->pid = 0;
RFILE(io)->fptr = wfptr;
/* bind to write_io temporarily to get rid of memory/fd leak */
fptr->tied_io_for_writing = 0;
RFILE(write_io)->fptr = fptr;
rb_io_fptr_cleanup(fptr, FALSE);
/* should not finalize fptr because another thread may be reading it */
return Qnil;
}
if ((fptr->mode & (FMODE_DUPLEX|FMODE_WRITABLE)) == FMODE_WRITABLE) {
rb_raise(rb_eIOError, "closing non-duplex IO for reading");
}
return rb_io_close(io);
}</pre>
</div>
</div>
</div>
<div id="method-i-close_write" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
close_write → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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 <a href="IOError.html"><code>IOError</code></a> if the stream is not duplexed.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"/bin/sh"</span>,<span class="ruby-string">"r+"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_write</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">print</span> <span class="ruby-string">"nowhere"</span>
</pre>
<p><em>produces:</em></p>
<pre>prog.rb:3:in `write': not opened for writing (IOError)
from prog.rb:3:in `print'
from prog.rb:3</pre>
<p>Calling this method on closed <a href="IO.html"><code>IO</code></a> object is just ignored since Ruby 2.3.</p>
<div class="method-source-code" id="close_write-source">
<pre>static VALUE
rb_io_close_write(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
write_io = GetWriteIO(io);
fptr = rb_io_get_fptr(rb_io_taint_check(write_io));
if (fptr->fd < 0) return Qnil;
if (is_socket(fptr->fd, fptr->pathv)) {
#ifndef SHUT_WR
# define SHUT_WR 1
#endif
if (shutdown(fptr->fd, SHUT_WR) < 0)
rb_sys_fail_path(fptr->pathv);
fptr->mode &= ~FMODE_WRITABLE;
if (!(fptr->mode & FMODE_READABLE))
return rb_io_close(write_io);
return Qnil;
}
if ((fptr->mode & (FMODE_DUPLEX|FMODE_READABLE)) == FMODE_READABLE) {
rb_raise(rb_eIOError, "closing non-duplex IO for writing");
}
if (io != write_io) {
fptr = rb_io_get_fptr(rb_io_taint_check(io));
fptr->tied_io_for_writing = 0;
}
rb_io_close(write_io);
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-closed-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
closed? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if <em>ios</em> is completely closed (for duplex streams, both reader and writer), <code>false</code> otherwise.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close</span> <span class="ruby-comment">#=> nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">closed?</span> <span class="ruby-comment">#=> true</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"/bin/sh"</span>,<span class="ruby-string">"r+"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_write</span> <span class="ruby-comment">#=> nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">closed?</span> <span class="ruby-comment">#=> false</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">close_read</span> <span class="ruby-comment">#=> nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">closed?</span> <span class="ruby-comment">#=> true</span>
</pre>
<div class="method-source-code" id="closed-3F-source">
<pre>static VALUE
rb_io_closed(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
rb_io_t *write_fptr;
write_io = GetWriteIO(io);
if (io != write_io) {
write_fptr = RFILE(write_io)->fptr;
if (write_fptr && 0 <= write_fptr->fd) {
return Qfalse;
}
}
fptr = rb_io_get_fptr(io);
return 0 <= fptr->fd ? Qfalse : Qtrue;
}</pre>
</div>
</div>
</div>
<div id="method-i-codepoints" class="method-detail ">
<div class="method-heading">
<span class="method-name">codepoints</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This is a deprecated alias for <a href="IO.html#method-i-each_codepoint"><code>each_codepoint</code></a>.</p>
<div class="method-source-code" id="codepoints-source">
<pre>static VALUE
rb_io_codepoints(VALUE io)
{
rb_warn_deprecated("IO#codepoints", "#each_codepoint");
if (!rb_block_given_p())
return rb_enumeratorize(io, ID2SYM(rb_intern("each_codepoint")), 0, 0);
return rb_io_each_codepoint(io);
}</pre>
</div>
</div>
</div>
<div id="method-i-console_mode" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
console_mode → mode
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a data represents the current console mode.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="console_mode-source">
<pre>static VALUE
console_conmode_get(VALUE io)
{
conmode t;
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
if (!getattr(fd, &t)) rb_sys_fail(0);
return conmode_new(cConmode, &t);
}</pre>
</div>
</div>
</div>
<div id="method-i-console_mode-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
console_mode = mode
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets the console mode to <code>mode</code>.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="console_mode-3D-source">
<pre>static VALUE
console_conmode_set(VALUE io, VALUE mode)
{
conmode *t, r;
rb_io_t *fptr;
int fd;
TypedData_Get_Struct(mode, conmode, &conmode_type, t);
r = *t;
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
if (!setattr(fd, &r)) rb_sys_fail(0);
return mode;
}</pre>
</div>
</div>
</div>
<div id="method-i-cooked" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
cooked {|io| }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Yields <code>self</code> within cooked mode.</p>
<pre class="ruby"><span class="ruby-constant">STDIN</span>.<span class="ruby-identifier">cooked</span>(<span class="ruby-operator">&</span><span class="ruby-value">:gets</span>)
</pre>
<p>will read and return a line with echo back and line editing.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="cooked-source">
<pre>static VALUE
console_cooked(VALUE io)
{
return ttymode(io, rb_yield, io, set_cookedmode, NULL);
}</pre>
</div>
</div>
</div>
<div id="method-i-cooked-21" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
cooked!
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Enables cooked mode.</p>
<p>If the terminal mode needs to be back, use io.cooked { … }.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="cooked-21-source">
<pre>static VALUE
console_set_cooked(VALUE io)
{
conmode t;
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
if (!getattr(fd, &t)) rb_sys_fail(0);
set_cookedmode(&t, NULL);
if (!setattr(fd, &t)) rb_sys_fail(0);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-cursor" class="method-detail ">
<div class="method-heading">
<span class="method-name">cursor</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="cursor-source">
<pre>static VALUE
console_cursor_pos(VALUE io)
{
rb_io_t *fptr;
int fd;
rb_console_size_t ws;
GetOpenFile(io, fptr);
fd = GetWriteFD(fptr);
if (!GetConsoleScreenBufferInfo((HANDLE)rb_w32_get_osfhandle(fd), &ws)) {
rb_syserr_fail(LAST_ERROR, 0);
}
return rb_assoc_new(UINT2NUM(ws.dwCursorPosition.Y), UINT2NUM(ws.dwCursorPosition.X));
}</pre>
</div>
</div>
</div>
<div id="method-i-cursor-3D" class="method-detail ">
<div class="method-heading">
<span class="method-name">cursor=</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="cursor-3D-source">
<pre>static VALUE
console_cursor_set(VALUE io, VALUE cpos)
{
cpos = rb_convert_type(cpos, T_ARRAY, "Array", "to_ary");
if (RARRAY_LEN(cpos) != 2) rb_raise(rb_eArgError, "expected 2D coordinate");
return console_goto(io, RARRAY_AREF(cpos, 0), RARRAY_AREF(cpos, 1));
}</pre>
</div>
</div>
</div>
<div id="method-i-cursor_down" class="method-detail ">
<div class="method-heading">
<span class="method-name">cursor_down</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="cursor_down-source">
<pre>static VALUE
console_cursor_down(VALUE io, VALUE val)
{
return console_move(io, +NUM2INT(val), 0);
}</pre>
</div>
</div>
</div>
<div id="method-i-cursor_left" class="method-detail ">
<div class="method-heading">
<span class="method-name">cursor_left</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="cursor_left-source">
<pre>static VALUE
console_cursor_left(VALUE io, VALUE val)
{
return console_move(io, 0, -NUM2INT(val));
}</pre>
</div>
</div>
</div>
<div id="method-i-cursor_right" class="method-detail ">
<div class="method-heading">
<span class="method-name">cursor_right</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="cursor_right-source">
<pre>static VALUE
console_cursor_right(VALUE io, VALUE val)
{
return console_move(io, 0, +NUM2INT(val));
}</pre>
</div>
</div>
</div>
<div id="method-i-cursor_up" class="method-detail ">
<div class="method-heading">
<span class="method-name">cursor_up</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="cursor_up-source">
<pre>static VALUE
console_cursor_up(VALUE io, VALUE val)
{
return console_move(io, -NUM2INT(val), 0);
}</pre>
</div>
</div>
</div>
<div id="method-i-each" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
each(sep=$/ [, getline_args]) {|line| block } → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each(limit [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each(sep, limit [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each(...) → an_enumerator
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(sep=$/ [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(limit [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(sep, limit [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(...) → an_enumerator
</span>
</div>
<div class="method-description">
<p>Executes the block for every line in <em>ios</em>, where lines are separated by <em>sep</em>. <em>ios</em> must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<p>If no block is given, an enumerator is returned instead.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">puts</span> <span class="ruby-node">"#{f.lineno}: #{line}"</span> }
</pre>
<p><em>produces:</em></p>
<pre>1: This is line one
2: This is line two
3: This is line three
4: And so on...</pre>
<p>See <a href="IO.html#method-c-readlines"><code>IO.readlines</code></a> for details about getline_args.</p>
<div class="method-source-code" id="each-source">
<pre>static VALUE
rb_io_each_line(int argc, VALUE *argv, VALUE io)
{
VALUE str;
struct getline_arg args;
RETURN_ENUMERATOR(io, argc, argv);
prepare_getline_args(argc, argv, &args, io);
if (args.limit == 0)
rb_raise(rb_eArgError, "invalid limit: 0 for each_line");
while (!NIL_P(str = rb_io_getline_1(args.rs, args.limit, args.chomp, io))) {
rb_yield(str);
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-each_byte" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
each_byte {|byte| block } → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_byte → an_enumerator
</span>
</div>
<div class="method-description">
<p>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 <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<p>If no block is given, an enumerator is returned instead.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">checksum</span> = <span class="ruby-value">0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_byte</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span> <span class="ruby-identifier">checksum</span> <span class="ruby-operator">^=</span> <span class="ruby-identifier">x</span> } <span class="ruby-comment">#=> #<File:testfile></span>
<span class="ruby-identifier">checksum</span> <span class="ruby-comment">#=> 12</span>
</pre>
<div class="method-source-code" id="each_byte-source">
<pre>static VALUE
rb_io_each_byte(VALUE io)
{
rb_io_t *fptr;
RETURN_ENUMERATOR(io, 0, 0);
GetOpenFile(io, fptr);
do {
while (fptr->rbuf.len > 0) {
char *p = fptr->rbuf.ptr + fptr->rbuf.off++;
fptr->rbuf.len--;
rb_yield(INT2FIX(*p & 0xff));
errno = 0;
}
rb_io_check_byte_readable(fptr);
READ_CHECK(fptr);
} while (io_fillbuf(fptr) >= 0);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-each_char" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
each_char {|c| block } → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_char → an_enumerator
</span>
</div>
<div class="method-description">
<p>Calls the given block once for each character in <em>ios</em>, passing the character as an argument. The stream must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<p>If no block is given, an enumerator is returned instead.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each_char</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">c</span><span class="ruby-operator">|</span> <span class="ruby-identifier">print</span> <span class="ruby-identifier">c</span>, <span class="ruby-string">' '</span> } <span class="ruby-comment">#=> #<File:testfile></span>
</pre>
<div class="method-source-code" id="each_char-source">
<pre>static VALUE
rb_io_each_char(VALUE io)
{
rb_io_t *fptr;
rb_encoding *enc;
VALUE c;
RETURN_ENUMERATOR(io, 0, 0);
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
enc = io_input_encoding(fptr);
READ_CHECK(fptr);
while (!NIL_P(c = io_getc(fptr, enc))) {
rb_yield(c);
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-each_codepoint" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
each_codepoint {|c| block } → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
codepoints {|c| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_codepoint → an_enumerator
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
codepoints → an_enumerator
</span>
</div>
<div class="method-description">
<p>Passes the <a href="Integer.html"><code>Integer</code></a> ordinal of each character in <em>ios</em>, passing the codepoint as an argument. The stream must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<p>If no block is given, an enumerator is returned instead.</p>
<div class="method-source-code" id="each_codepoint-source">
<pre>static VALUE
rb_io_each_codepoint(VALUE io)
{
rb_io_t *fptr;
rb_encoding *enc;
unsigned int c;
int r, n;
RETURN_ENUMERATOR(io, 0, 0);
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
READ_CHECK(fptr);
if (NEED_READCONV(fptr)) {
SET_BINARY_MODE(fptr);
r = 1; /* no invalid char yet */
for (;;) {
make_readconv(fptr, 0);
for (;;) {
if (fptr->cbuf.len) {
if (fptr->encs.enc)
r = rb_enc_precise_mbclen(fptr->cbuf.ptr+fptr->cbuf.off,
fptr->cbuf.ptr+fptr->cbuf.off+fptr->cbuf.len,
fptr->encs.enc);
else
r = ONIGENC_CONSTRUCT_MBCLEN_CHARFOUND(1);
if (!MBCLEN_NEEDMORE_P(r))
break;
if (fptr->cbuf.len == fptr->cbuf.capa) {
rb_raise(rb_eIOError, "too long character");
}
}
if (more_char(fptr) == MORE_CHAR_FINISHED) {
clear_readconv(fptr);
if (!MBCLEN_CHARFOUND_P(r)) {
enc = fptr->encs.enc;
goto invalid;
}
return io;
}
}
if (MBCLEN_INVALID_P(r)) {
enc = fptr->encs.enc;
goto invalid;
}
n = MBCLEN_CHARFOUND_LEN(r);
if (fptr->encs.enc) {
c = rb_enc_codepoint(fptr->cbuf.ptr+fptr->cbuf.off,
fptr->cbuf.ptr+fptr->cbuf.off+fptr->cbuf.len,
fptr->encs.enc);
}
else {
c = (unsigned char)fptr->cbuf.ptr[fptr->cbuf.off];
}
fptr->cbuf.off += n;
fptr->cbuf.len -= n;
rb_yield(UINT2NUM(c));
}
}
NEED_NEWLINE_DECORATOR_ON_READ_CHECK(fptr);
enc = io_input_encoding(fptr);
while (io_fillbuf(fptr) >= 0) {
r = rb_enc_precise_mbclen(fptr->rbuf.ptr+fptr->rbuf.off,
fptr->rbuf.ptr+fptr->rbuf.off+fptr->rbuf.len, enc);
if (MBCLEN_CHARFOUND_P(r) &&
(n = MBCLEN_CHARFOUND_LEN(r)) <= fptr->rbuf.len) {
c = rb_enc_codepoint(fptr->rbuf.ptr+fptr->rbuf.off,
fptr->rbuf.ptr+fptr->rbuf.off+fptr->rbuf.len, enc);
fptr->rbuf.off += n;
fptr->rbuf.len -= n;
rb_yield(UINT2NUM(c));
}
else if (MBCLEN_INVALID_P(r)) {
invalid:
rb_raise(rb_eArgError, "invalid byte sequence in %s", rb_enc_name(enc));
}
else if (MBCLEN_NEEDMORE_P(r)) {
char cbuf[8], *p = cbuf;
int more = MBCLEN_NEEDMORE_LEN(r);
if (more > numberof(cbuf)) goto invalid;
more += n = fptr->rbuf.len;
if (more > numberof(cbuf)) goto invalid;
while ((n = (int)read_buffered_data(p, more, fptr)) > 0 &&
(p += n, (more -= n) > 0)) {
if (io_fillbuf(fptr) < 0) goto invalid;
if ((n = fptr->rbuf.len) > more) n = more;
}
r = rb_enc_precise_mbclen(cbuf, p, enc);
if (!MBCLEN_CHARFOUND_P(r)) goto invalid;
c = rb_enc_codepoint(cbuf, p, enc);
rb_yield(UINT2NUM(c));
}
else {
continue;
}
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-each_line" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
each_line(sep=$/ [, getline_args]) {|line| block } → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(limit [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(sep, limit [, getline_args]) {|line| block } → ios
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
each_line(...) → an_enumerator
</span>
</div>
<div class="method-description">
<p>Executes the block for every line in <em>ios</em>, where lines are separated by <em>sep</em>. <em>ios</em> must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<p>If no block is given, an enumerator is returned instead.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">each</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">line</span><span class="ruby-operator">|</span> <span class="ruby-identifier">puts</span> <span class="ruby-node">"#{f.lineno}: #{line}"</span> }
</pre>
<p><em>produces:</em></p>
<pre>1: This is line one
2: This is line two
3: This is line three
4: And so on...</pre>
<p>See <a href="IO.html#method-c-readlines"><code>IO.readlines</code></a> for details about getline_args.</p>
<div class="method-source-code" id="each_line-source">
<pre>static VALUE
rb_io_each_line(int argc, VALUE *argv, VALUE io)
{
VALUE str;
struct getline_arg args;
RETURN_ENUMERATOR(io, argc, argv);
prepare_getline_args(argc, argv, &args, io);
if (args.limit == 0)
rb_raise(rb_eArgError, "invalid limit: 0 for each_line");
while (!NIL_P(str = rb_io_getline_1(args.rs, args.limit, args.chomp, io))) {
rb_yield(str);
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-echo-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
echo = flag
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Enables/disables echo back. On some platforms, all combinations of this flags and raw/cooked mode may not be valid.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="echo-3D-source">
<pre>static VALUE
console_set_echo(VALUE io, VALUE f)
{
conmode t;
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
if (!getattr(fd, &t)) rb_sys_fail(0);
if (RTEST(f))
set_echo(&t, NULL);
else
set_noecho(&t, NULL);
if (!setattr(fd, &t)) rb_sys_fail(0);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-echo-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
echo? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if echo back is enabled.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="echo-3F-source">
<pre>static VALUE
console_echo_p(VALUE io)
{
conmode t;
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
if (!getattr(fd, &t)) rb_sys_fail(0);
return echo_p(&t) ? Qtrue : Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-eof" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
eof → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
eof? → true or false
</span>
</div>
<div class="method-description">
<p>Returns true if <em>ios</em> is at end of file that means there are no more data to read. The stream must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">dummy</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof</span> <span class="ruby-comment">#=> true</span>
</pre>
<p>If <em>ios</em> is a stream such as pipe or socket, <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a> blocks until the other end sends some data or closes it.</p>
<pre class="ruby"><span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">close</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment">#=> true after 1 second blocking</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"a"</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment">#=> false after 1 second blocking</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># blocks forever</span>
</pre>
<p>Note that <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a> reads data to the input byte buffer. So <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a> may not behave as you intend with <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a>, unless you call <a href="IO.html#method-i-rewind"><code>IO#rewind</code></a> first (which is not available for some streams).</p>
<div class="method-source-code" id="eof-source">
<pre>VALUE
rb_io_eof(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
if (READ_CHAR_PENDING(fptr)) return Qfalse;
if (READ_DATA_PENDING(fptr)) return Qfalse;
READ_CHECK(fptr);
#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
if (!NEED_READCONV(fptr) && NEED_NEWLINE_DECORATOR_ON_READ(fptr)) {
return eof(fptr->fd) ? Qtrue : Qfalse;
}
#endif
if (io_fillbuf(fptr) < 0) {
return Qtrue;
}
return Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-eof-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
eof? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns true if <em>ios</em> is at end of file that means there are no more data to read. The stream must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">dummy</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">eof</span> <span class="ruby-comment">#=> true</span>
</pre>
<p>If <em>ios</em> is a stream such as pipe or socket, <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a> blocks until the other end sends some data or closes it.</p>
<pre class="ruby"><span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">close</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment">#=> true after 1 second blocking</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">new</span> { <span class="ruby-identifier">sleep</span> <span class="ruby-value">1</span>; <span class="ruby-identifier">w</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"a"</span> }
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment">#=> false after 1 second blocking</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">eof?</span> <span class="ruby-comment"># blocks forever</span>
</pre>
<p>Note that <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a> reads data to the input byte buffer. So <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a> may not behave as you intend with <a href="IO.html#method-i-eof-3F"><code>IO#eof?</code></a>, unless you call <a href="IO.html#method-i-rewind"><code>IO#rewind</code></a> first (which is not available for some streams).</p>
<div class="method-source-code" id="eof-3F-source">
<pre>VALUE
rb_io_eof(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
if (READ_CHAR_PENDING(fptr)) return Qfalse;
if (READ_DATA_PENDING(fptr)) return Qfalse;
READ_CHECK(fptr);
#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
if (!NEED_READCONV(fptr) && NEED_NEWLINE_DECORATOR_ON_READ(fptr)) {
return eof(fptr->fd) ? Qtrue : Qfalse;
}
#endif
if (io_fillbuf(fptr) < 0) {
return Qtrue;
}
return Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-erase_line" class="method-detail ">
<div class="method-heading">
<span class="method-name">erase_line</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="erase_line-source">
<pre>static VALUE
console_erase_line(VALUE io, VALUE val)
{
rb_io_t *fptr;
HANDLE h;
rb_console_size_t ws;
COORD *pos = &ws.dwCursorPosition;
DWORD w;
int mode = mode_in_range(val, 2, "line erase");
GetOpenFile(io, fptr);
h = (HANDLE)rb_w32_get_osfhandle(GetWriteFD(fptr));
if (!GetConsoleScreenBufferInfo(h, &ws)) {
rb_syserr_fail(LAST_ERROR, 0);
}
w = winsize_col(&ws);
switch (mode) {
case 0: /* after cursor */
w -= pos->X;
break;
case 1: /* before *and* cursor */
w = pos->X + 1;
pos->X = 0;
break;
case 2: /* entire line */
pos->X = 0;
break;
}
constat_clear(h, ws.wAttributes, w, *pos);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-erase_screen" class="method-detail ">
<div class="method-heading">
<span class="method-name">erase_screen</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="erase_screen-source">
<pre>static VALUE
console_erase_screen(VALUE io, VALUE val)
{
rb_io_t *fptr;
HANDLE h;
rb_console_size_t ws;
COORD *pos = &ws.dwCursorPosition;
DWORD w;
int mode = mode_in_range(val, 3, "screen erase");
GetOpenFile(io, fptr);
h = (HANDLE)rb_w32_get_osfhandle(GetWriteFD(fptr));
if (!GetConsoleScreenBufferInfo(h, &ws)) {
rb_syserr_fail(LAST_ERROR, 0);
}
w = winsize_col(&ws);
switch (mode) {
case 0: /* erase after cursor */
w = (w * (ws.srWindow.Bottom - pos->Y + 1) - pos->X);
break;
case 1: /* erase before *and* cursor */
w = (w * (pos->Y - ws.srWindow.Top) + pos->X + 1);
pos->X = 0;
pos->Y = ws.srWindow.Top;
break;
case 2: /* erase entire screen */
w = (w * winsize_row(&ws));
pos->X = 0;
pos->Y = ws.srWindow.Top;
break;
case 3: /* erase entire screen */
w = (w * ws.dwSize.Y);
pos->X = 0;
pos->Y = 0;
break;
}
constat_clear(h, ws.wAttributes, w, *pos);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-expect" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
IO#expect(pattern,timeout=9999999) → Array
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
IO#expect(pattern,timeout=9999999) { |result| ... } → nil
</span>
</div>
<div class="method-description">
<p>Reads from the <a href="IO.html"><code>IO</code></a> until the given <code>pattern</code> matches or the <code>timeout</code> is over.</p>
<p>It returns an array with the read buffer, followed by the matches. If a block is given, the result is yielded to the block and returns nil.</p>
<p>When called without a block, it waits until the input that matches the given <code>pattern</code> is obtained from the <a href="IO.html"><code>IO</code></a> or the time specified as the timeout passes. An array is returned when the pattern is obtained from the <a href="IO.html"><code>IO</code></a>. The first element of the array is the entire string obtained from the <a href="IO.html"><code>IO</code></a> until the pattern matches, followed by elements indicating which the pattern which matched to the anchor in the regular expression.</p>
<p>The optional timeout parameter defines, in seconds, the total time to wait for the pattern. If the timeout expires or eof is found, nil is returned or yielded. However, the buffer in a timeout session is kept for the next expect call. The default timeout is 9999999 seconds.</p>
<div class="method-source-code" id="expect-source">
<pre><span class="ruby-comment"># File ext/pty/lib/expect.rb, line 33</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">expect</span>(<span class="ruby-identifier">pat</span>,<span class="ruby-identifier">timeout</span>=<span class="ruby-value">9999999</span>)
<span class="ruby-identifier">buf</span> = <span class="ruby-string">''</span>.<span class="ruby-identifier">dup</span>
<span class="ruby-keyword">case</span> <span class="ruby-identifier">pat</span>
<span class="ruby-keyword">when</span> <span class="ruby-constant">String</span>
<span class="ruby-identifier">e_pat</span> = <span class="ruby-constant">Regexp</span>.<span class="ruby-identifier">new</span>(<span class="ruby-constant">Regexp</span>.<span class="ruby-identifier">quote</span>(<span class="ruby-identifier">pat</span>))
<span class="ruby-keyword">when</span> <span class="ruby-constant">Regexp</span>
<span class="ruby-identifier">e_pat</span> = <span class="ruby-identifier">pat</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">raise</span> <span class="ruby-constant">TypeError</span>, <span class="ruby-node">"unsupported pattern class: #{pat.class}"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-ivar">@unusedBuf</span> <span class="ruby-operator">||=</span> <span class="ruby-string">''</span>
<span class="ruby-keyword">while</span> <span class="ruby-keyword">true</span>
<span class="ruby-keyword">if</span> <span class="ruby-keyword">not</span> <span class="ruby-ivar">@unusedBuf</span>.<span class="ruby-identifier">empty?</span>
<span class="ruby-identifier">c</span> = <span class="ruby-ivar">@unusedBuf</span>.<span class="ruby-identifier">slice!</span>(<span class="ruby-value">0</span>)
<span class="ruby-keyword">elsif</span> <span class="ruby-operator">!</span><span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-keyword">self</span>],<span class="ruby-keyword">nil</span>,<span class="ruby-keyword">nil</span>,<span class="ruby-identifier">timeout</span>) <span class="ruby-keyword">or</span> <span class="ruby-identifier">eof?</span> <span class="ruby-keyword">then</span>
<span class="ruby-identifier">result</span> = <span class="ruby-keyword">nil</span>
<span class="ruby-ivar">@unusedBuf</span> = <span class="ruby-identifier">buf</span>
<span class="ruby-keyword">break</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">c</span> = <span class="ruby-identifier">getc</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">buf</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">c</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">$expect_verbose</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">print</span> <span class="ruby-identifier">c</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">flush</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">mat</span>=<span class="ruby-identifier">e_pat</span>.<span class="ruby-identifier">match</span>(<span class="ruby-identifier">buf</span>) <span class="ruby-keyword">then</span>
<span class="ruby-identifier">result</span> = [<span class="ruby-identifier">buf</span>,<span class="ruby-operator">*</span><span class="ruby-identifier">mat</span>.<span class="ruby-identifier">captures</span>]
<span class="ruby-keyword">break</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">block_given?</span> <span class="ruby-keyword">then</span>
<span class="ruby-keyword">yield</span> <span class="ruby-identifier">result</span>
<span class="ruby-keyword">else</span>
<span class="ruby-keyword">return</span> <span class="ruby-identifier">result</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">nil</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-external_encoding" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
external_encoding → encoding
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the <a href="Encoding.html"><code>Encoding</code></a> object that represents the encoding of the file. If <em>io</em> is in write mode and no encoding is specified, returns <code>nil</code>.</p>
<div class="method-source-code" id="external_encoding-source">
<pre>static VALUE
rb_io_external_encoding(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (fptr->encs.enc2) {
return rb_enc_from_encoding(fptr->encs.enc2);
}
if (fptr->mode & FMODE_WRITABLE) {
if (fptr->encs.enc)
return rb_enc_from_encoding(fptr->encs.enc);
return Qnil;
}
return rb_enc_from_encoding(io_read_encoding(fptr));
}</pre>
</div>
</div>
</div>
<div id="method-i-fcntl" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
fcntl(integer_cmd, arg) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Provides a mechanism for issuing low-level commands to control or query file-oriented I/O streams. Arguments and results are platform dependent. If <em>arg</em> is a number, its value is passed directly. If it is a string, it is interpreted as a binary sequence of bytes (<a href="Array.html#method-i-pack"><code>Array#pack</code></a> might be a useful way to build this string). On Unix platforms, see <code>fcntl(2)</code> for details. Not implemented on all platforms.</p>
<div class="method-source-code" id="fcntl-source">
<pre>static VALUE
rb_io_fcntl(int argc, VALUE *argv, VALUE io)
{
VALUE req, arg;
rb_scan_args(argc, argv, "11", &req, &arg);
return rb_fcntl(io, req, arg);
}</pre>
</div>
</div>
</div>
<div id="method-i-fdatasync" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
fdatasync → 0 or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Immediately writes all buffered data in <em>ios</em> to disk.</p>
<p>If the underlying operating system does not support <em>fdatasync(2)</em>, <a href="IO.html#method-i-fsync"><code>IO#fsync</code></a> is called instead (which might raise a <a href="NotImplementedError.html"><code>NotImplementedError</code></a>).</p>
<div class="method-source-code" id="fdatasync-source">
<pre>static VALUE
rb_io_fdatasync(VALUE io)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
if (io_fflush(fptr) < 0)
rb_sys_fail(0);
if ((int)rb_thread_io_blocking_region(nogvl_fdatasync, fptr, fptr->fd) == 0)
return INT2FIX(0);
/* fall back */
return rb_io_fsync(io);
}</pre>
</div>
</div>
</div>
<div id="method-i-fileno" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
fileno → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
to_i → integer
</span>
</div>
<div class="method-description">
<p>Returns an integer representing the numeric file descriptor for <em>ios</em>.</p>
<pre class="ruby"><span class="ruby-identifier">$stdin</span>.<span class="ruby-identifier">fileno</span> <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">fileno</span> <span class="ruby-comment">#=> 1</span>
</pre>
<div class="method-source-code" id="fileno-source">
<pre>static VALUE
rb_io_fileno(VALUE io)
{
rb_io_t *fptr = RFILE(io)->fptr;
int fd;
rb_io_check_closed(fptr);
fd = fptr->fd;
return INT2FIX(fd);
}</pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="IO.html#method-i-to_i">to_i</a>
</div>
</div>
<div id="method-i-flush" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
flush → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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).</p>
<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">print</span> <span class="ruby-string">"no newline"</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">flush</span>
</pre>
<p><em>produces:</em></p>
<pre class="ruby"><span class="ruby-identifier">no</span> <span class="ruby-identifier">newline</span>
</pre>
<div class="method-source-code" id="flush-source">
<pre>VALUE
rb_io_flush(VALUE io)
{
return rb_io_flush_raw(io, 1);
}</pre>
</div>
</div>
</div>
<div id="method-i-fsync" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
fsync → 0 or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Immediately writes all buffered data in <em>ios</em> to disk. Note that <a href="IO.html#method-i-fsync"><code>fsync</code></a> differs from using <a href="IO.html#method-i-sync-3D"><code>IO#sync=</code></a>. The latter ensures that data is flushed from Ruby's buffers, but does not guarantee that the underlying operating system actually writes it to disk.</p>
<p><a href="NotImplementedError.html"><code>NotImplementedError</code></a> is raised if the underlying operating system does not support <em>fsync(2)</em>.</p>
<div class="method-source-code" id="fsync-source">
<pre>static VALUE
rb_io_fsync(VALUE io)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
if (io_fflush(fptr) < 0)
rb_sys_fail(0);
if ((int)rb_thread_io_blocking_region(nogvl_fsync, fptr, fptr->fd) < 0)
rb_sys_fail_path(fptr->pathv);
return INT2FIX(0);
}</pre>
</div>
</div>
</div>
<div id="method-i-getbyte" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
getbyte → integer or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Gets the next 8-bit byte (0..255) from <em>ios</em>. Returns <code>nil</code> if called at end of file.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getbyte</span> <span class="ruby-comment">#=> 84</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getbyte</span> <span class="ruby-comment">#=> 104</span>
</pre>
<div class="method-source-code" id="getbyte-source">
<pre>VALUE
rb_io_getbyte(VALUE io)
{
rb_io_t *fptr;
int c;
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
READ_CHECK(fptr);
if (fptr->fd == 0 && (fptr->mode & FMODE_TTY) && RB_TYPE_P(rb_stdout, T_FILE)) {
rb_io_t *ofp;
GetOpenFile(rb_stdout, ofp);
if (ofp->mode & FMODE_TTY) {
rb_io_flush(rb_stdout);
}
}
if (io_fillbuf(fptr) < 0) {
return Qnil;
}
fptr->rbuf.off++;
fptr->rbuf.len--;
c = (unsigned char)fptr->rbuf.ptr[fptr->rbuf.off-1];
return INT2FIX(c & 0xff);
}</pre>
</div>
</div>
</div>
<div id="method-i-getc" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
getc → string or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads a one-character string from <em>ios</em>. Returns <code>nil</code> if called at end of file.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span> <span class="ruby-comment">#=> "h"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span> <span class="ruby-comment">#=> "e"</span>
</pre>
<div class="method-source-code" id="getc-source">
<pre>static VALUE
rb_io_getc(VALUE io)
{
rb_io_t *fptr;
rb_encoding *enc;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
enc = io_input_encoding(fptr);
READ_CHECK(fptr);
return io_getc(fptr, enc);
}</pre>
</div>
</div>
</div>
<div id="method-i-getch" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
getch(min: nil, time: nil, intr: nil) → char
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads and returns a character in raw mode.</p>
<p>See <a href="IO.html#method-i-raw"><code>IO#raw</code></a> for details on the parameters.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="getch-source">
<pre>static VALUE
console_getch(int argc, VALUE *argv, VALUE io)
{
rawmode_arg_t opts, *optp = rawmode_opt(&argc, argv, 0, 0, &opts);
#ifndef _WIN32
return ttymode(io, getc_call, io, set_rawmode, optp);
#else
rb_io_t *fptr;
VALUE str;
wint_t c;
int w, len;
char buf[8];
wint_t wbuf[2];
struct timeval *to = NULL, tv;
GetOpenFile(io, fptr);
if (optp) {
if (optp->vtime) {
to = &tv;
tv.tv_sec = optp->vtime / 10;
tv.tv_usec = (optp->vtime % 10) * 100000;
}
if (optp->vmin != 1) {
rb_warning("min option ignored");
}
if (optp->intr) {
w = rb_wait_for_single_fd(fptr->fd, RB_WAITFD_IN, to);
if (w < 0) rb_eof_error();
if (!(w & RB_WAITFD_IN)) return Qnil;
}
else {
rb_warning("vtime option ignored if intr flag is unset");
}
}
len = (int)(VALUE)rb_thread_call_without_gvl(nogvl_getch, wbuf, RUBY_UBF_IO, 0);
switch (len) {
case 0:
return Qnil;
case 2:
buf[0] = (char)wbuf[0];
c = wbuf[1];
len = 1;
do {
buf[len++] = (unsigned char)c;
} while ((c >>= CHAR_BIT) && len < (int)sizeof(buf));
return rb_str_new(buf, len);
default:
c = wbuf[0];
len = rb_uv_to_utf8(buf, c);
str = rb_utf8_str_new(buf, len);
return rb_str_conv_enc(str, NULL, rb_default_external_encoding());
}
#endif
}</pre>
</div>
</div>
</div>
<div id="method-i-getpass" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
getpass(prompt=nil) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads and returns a line without echo back. Prints <code>prompt</code> unless it is <code>nil</code>.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="getpass-source">
<pre>static VALUE
console_getpass(int argc, VALUE *argv, VALUE io)
{
VALUE str, wio;
rb_check_arity(argc, 0, 1);
wio = rb_io_get_write_io(io);
if (wio == io && io == rb_stdin) wio = rb_stderr;
prompt(argc, argv, wio);
str = rb_ensure(getpass_call, io, puts_call, wio);
return str_chomp(str);
}</pre>
</div>
</div>
</div>
<div id="method-i-gets" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
gets(sep=$/ [, getline_args]) → string or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
gets(limit [, getline_args]) → string or nil
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
gets(sep, limit [, getline_args]) → string or nil
</span>
</div>
<div class="method-description">
<p>Reads the next “line'' from the I/O stream; lines are separated by <em>sep</em>. 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 <a href="IOError.html"><code>IOError</code></a> 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. If the first argument is an integer, or optional second argument is given, the returning string would not be longer than the given value in bytes.</p>
<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>).<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">$_</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>).<span class="ruby-identifier">gets</span>(<span class="ruby-value">4</span>)<span class="ruby-comment">#=> "This"</span>
</pre>
<p>If <a href="IO.html"><code>IO</code></a> contains multibyte characters byte then <code>gets(1)</code> returns character entirely:</p>
<pre class="ruby"><span class="ruby-comment"># Russian characters take 2 bytes</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-string">"\u{442 435 441 442}"</span>)
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"testfile"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span><span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">1</span>)} <span class="ruby-comment">#=> "\u0442"</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"testfile"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span><span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">2</span>)} <span class="ruby-comment">#=> "\u0442"</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"testfile"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span><span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">3</span>)} <span class="ruby-comment">#=> "\u0442\u0435"</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"testfile"</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span><span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span>(<span class="ruby-value">4</span>)} <span class="ruby-comment">#=> "\u0442\u0435"</span>
</pre>
<div class="method-source-code" id="gets-source">
<pre>static VALUE
rb_io_gets_m(int argc, VALUE *argv, VALUE io)
{
VALUE str;
str = rb_io_getline(argc, argv, io);
rb_lastline_set(str);
return str;
}</pre>
</div>
</div>
</div>
<div id="method-i-goto" class="method-detail ">
<div class="method-heading">
<span class="method-name">goto</span><span
class="method-args">(p1, p2)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="goto-source">
<pre>static VALUE
console_goto(VALUE io, VALUE y, VALUE x)
{
rb_io_t *fptr;
int fd;
COORD pos;
GetOpenFile(io, fptr);
fd = GetWriteFD(fptr);
pos.X = NUM2UINT(x);
pos.Y = NUM2UINT(y);
if (!SetConsoleCursorPosition((HANDLE)rb_w32_get_osfhandle(fd), pos)) {
rb_syserr_fail(LAST_ERROR, 0);
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-goto_column" class="method-detail ">
<div class="method-heading">
<span class="method-name">goto_column</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="goto_column-source">
<pre>static VALUE
console_goto_column(VALUE io, VALUE val)
{
rb_io_t *fptr;
HANDLE h;
rb_console_size_t ws;
COORD *pos = &ws.dwCursorPosition;
GetOpenFile(io, fptr);
h = (HANDLE)rb_w32_get_osfhandle(GetWriteFD(fptr));
if (!GetConsoleScreenBufferInfo(h, &ws)) {
rb_syserr_fail(LAST_ERROR, 0);
}
pos->X = NUM2INT(val);
if (!SetConsoleCursorPosition(h, *pos)) {
rb_syserr_fail(LAST_ERROR, 0);
}
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-iflush" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
iflush
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Flushes input buffer in kernel.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="iflush-source">
<pre>static VALUE
console_iflush(VALUE io)
{
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
#if defined HAVE_TERMIOS_H || defined HAVE_TERMIO_H
if (tcflush(fd, TCIFLUSH)) rb_sys_fail(0);
#endif
(void)fd;
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-inspect" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
inspect → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Return a string describing this <a href="IO.html"><code>IO</code></a> object.</p>
<div class="method-source-code" id="inspect-source">
<pre>static VALUE
rb_io_inspect(VALUE obj)
{
rb_io_t *fptr;
VALUE result;
static const char closed[] = " (closed)";
fptr = RFILE(obj)->fptr;
if (!fptr) return rb_any_to_s(obj);
result = rb_str_new_cstr("#<");
rb_str_append(result, rb_class_name(CLASS_OF(obj)));
rb_str_cat2(result, ":");
if (NIL_P(fptr->pathv)) {
if (fptr->fd < 0) {
rb_str_cat(result, closed+1, strlen(closed)-1);
}
else {
rb_str_catf(result, "fd %d", fptr->fd);
}
}
else {
rb_str_append(result, fptr->pathv);
if (fptr->fd < 0) {
rb_str_cat(result, closed, strlen(closed));
}
}
return rb_str_cat2(result, ">");
}</pre>
</div>
</div>
</div>
<div id="method-i-internal_encoding" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
internal_encoding → encoding
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the <a href="Encoding.html"><code>Encoding</code></a> of the internal string if conversion is specified. Otherwise returns <code>nil</code>.</p>
<div class="method-source-code" id="internal_encoding-source">
<pre>static VALUE
rb_io_internal_encoding(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!fptr->encs.enc2) return Qnil;
return rb_enc_from_encoding(io_read_encoding(fptr));
}</pre>
</div>
</div>
</div>
<div id="method-i-ioctl" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ioctl(integer_cmd, arg) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Provides a mechanism for issuing low-level commands to control or query I/O devices. Arguments and results are platform dependent. If <em>arg</em> 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.</p>
<div class="method-source-code" id="ioctl-source">
<pre>static VALUE
rb_io_ioctl(int argc, VALUE *argv, VALUE io)
{
VALUE req, arg;
rb_scan_args(argc, argv, "11", &req, &arg);
return rb_ioctl(io, req, arg);
}</pre>
</div>
</div>
</div>
<div id="method-i-ioflush" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ioflush
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Flushes input and output buffers in kernel.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="ioflush-source">
<pre>static VALUE
console_ioflush(VALUE io)
{
rb_io_t *fptr;
#if defined HAVE_TERMIOS_H || defined HAVE_TERMIO_H
int fd1, fd2;
#endif
GetOpenFile(io, fptr);
#if defined HAVE_TERMIOS_H || defined HAVE_TERMIO_H
fd1 = GetReadFD(fptr);
fd2 = GetWriteFD(fptr);
if (fd2 != -1 && fd1 != fd2) {
if (tcflush(fd1, TCIFLUSH)) rb_sys_fail(0);
if (tcflush(fd2, TCOFLUSH)) rb_sys_fail(0);
}
else {
if (tcflush(fd1, TCIOFLUSH)) rb_sys_fail(0);
}
#endif
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-isatty" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
isatty → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if <em>ios</em> is associated with a terminal device (tty), <code>false</code> otherwise.</p>
<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>).<span class="ruby-identifier">isatty</span> <span class="ruby-comment">#=> false</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"/dev/tty"</span>).<span class="ruby-identifier">isatty</span> <span class="ruby-comment">#=> true</span>
</pre>
<div class="method-source-code" id="isatty-source">
<pre>static VALUE
rb_io_isatty(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (isatty(fptr->fd) == 0)
return Qfalse;
return Qtrue;
}</pre>
</div>
</div>
</div>
<div id="method-i-lineno" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
lineno → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the current line number in <em>ios</em>. The stream must be opened for reading. <a href="IO.html#method-i-lineno"><code>lineno</code></a> counts the number of times <a href="IO.html#method-i-gets"><code>gets</code></a> is called rather than the number of newlines encountered. The two values will differ if <a href="IO.html#method-i-gets"><code>gets</code></a> is called with a separator other than newline.</p>
<p>Methods that use <code>$/</code> like <a href="IO.html#method-i-each"><code>each</code></a>, <a href="IO.html#method-i-lines"><code>lines</code></a> and <a href="IO.html#method-i-readline"><code>readline</code></a> will also increment <a href="IO.html#method-i-lineno"><code>lineno</code></a>.</p>
<p>See also the <code>$.</code> variable.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment">#=> 1</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line two\n"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment">#=> 2</span>
</pre>
<div class="method-source-code" id="lineno-source">
<pre>static VALUE
rb_io_lineno(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
return INT2NUM(fptr->lineno);
}</pre>
</div>
</div>
</div>
<div id="method-i-lineno-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
lineno = integer → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Manually sets the current line number to the given value. <code>$.</code> is updated only on the next read.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">$.</span> <span class="ruby-comment">#=> 1</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> = <span class="ruby-value">1000</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment">#=> 1000</span>
<span class="ruby-identifier">$.</span> <span class="ruby-comment">#=> 1 # lineno of last read</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line two\n"</span>
<span class="ruby-identifier">$.</span> <span class="ruby-comment">#=> 1001 # lineno of last read</span>
</pre>
<div class="method-source-code" id="lineno-3D-source">
<pre>static VALUE
rb_io_set_lineno(VALUE io, VALUE lineno)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
fptr->lineno = NUM2INT(lineno);
return lineno;
}</pre>
</div>
</div>
</div>
<div id="method-i-lines" class="method-detail ">
<div class="method-heading">
<span class="method-name">lines</span><span
class="method-args">(*args)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This is a deprecated alias for <a href="IO.html#method-i-each_line"><code>each_line</code></a>.</p>
<div class="method-source-code" id="lines-source">
<pre>static VALUE
rb_io_lines(int argc, VALUE *argv, VALUE io)
{
rb_warn_deprecated("IO#lines", "#each_line");
if (!rb_block_given_p())
return rb_enumeratorize(io, ID2SYM(rb_intern("each_line")), argc, argv);
return rb_io_each_line(argc, argv, io);
}</pre>
</div>
</div>
</div>
<div id="method-i-noecho" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
noecho {|io| }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Yields <code>self</code> with disabling echo back.</p>
<pre class="ruby"><span class="ruby-constant">STDIN</span>.<span class="ruby-identifier">noecho</span>(<span class="ruby-operator">&</span><span class="ruby-value">:gets</span>)
</pre>
<p>will read and return a line without echo back.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="noecho-source">
<pre>static VALUE
console_noecho(VALUE io)
{
return ttymode(io, rb_yield, io, set_noecho, NULL);
}</pre>
</div>
</div>
</div>
<div id="method-i-nonblock" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
nonblock {|io| } → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
nonblock(boolean) {|io| } → io
</span>
</div>
<div class="method-description">
<p>Yields <code>self</code> in non-blocking mode.</p>
<p>When <code>false</code> is given as an argument, <code>self</code> is yielded in blocking mode. The original mode is restored after the block is executed.</p>
<div class="method-source-code" id="nonblock-source">
<pre>static VALUE
rb_io_nonblock_block(int argc, VALUE *argv, VALUE io)
{
int nb = 1;
rb_io_t *fptr;
int f, restore[2];
GetOpenFile(io, fptr);
if (argc > 0) {
VALUE v;
rb_scan_args(argc, argv, "01", &v);
nb = RTEST(v);
}
f = io_nonblock_mode(fptr->fd);
restore[0] = fptr->fd;
restore[1] = f;
if (!io_nonblock_set(fptr->fd, f, nb))
return rb_yield(io);
return rb_ensure(rb_yield, io, io_nonblock_restore, (VALUE)restore);
}</pre>
</div>
</div>
</div>
<div id="method-i-nonblock-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
nonblock = boolean → boolean
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Enables non-blocking mode on a stream when set to <code>true</code>, and blocking mode when set to <code>false</code>.</p>
<div class="method-source-code" id="nonblock-3D-source">
<pre>static VALUE
rb_io_nonblock_set(VALUE io, VALUE nb)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (RTEST(nb))
rb_io_set_nonblock(fptr);
else
io_nonblock_set(fptr->fd, io_nonblock_mode(fptr->fd), RTEST(nb));
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-nonblock-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
nonblock? → boolean
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if an <a href="IO.html"><code>IO</code></a> object is in non-blocking mode.</p>
<div class="method-source-code" id="nonblock-3F-source">
<pre>static VALUE
rb_io_nonblock_p(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (io_nonblock_mode(fptr->fd) & O_NONBLOCK)
return Qtrue;
return Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-nread" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
nread → int
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns number of bytes that can be read without blocking. Returns zero if no information available.</p>
<div class="method-source-code" id="nread-source">
<pre>static VALUE
io_nread(VALUE io)
{
rb_io_t *fptr;
int len;
ioctl_arg n;
GetOpenFile(io, fptr);
rb_io_check_readable(fptr);
len = rb_io_read_pending(fptr);
if (len > 0) return INT2FIX(len);
if (!FIONREAD_POSSIBLE_P(fptr->fd)) return INT2FIX(0);
if (ioctl(fptr->fd, FIONREAD, &n)) return INT2FIX(0);
if (n > 0) return ioctl_arg2num(n);
return INT2FIX(0);
}</pre>
</div>
</div>
</div>
<div id="method-i-oflush" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
oflush
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Flushes output buffer in kernel.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="oflush-source">
<pre>static VALUE
console_oflush(VALUE io)
{
rb_io_t *fptr;
int fd;
GetOpenFile(io, fptr);
fd = GetWriteFD(fptr);
#if defined HAVE_TERMIOS_H || defined HAVE_TERMIO_H
if (tcflush(fd, TCOFLUSH)) rb_sys_fail(0);
#endif
(void)fd;
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-pathconf" class="method-detail ">
<div class="method-heading">
<span class="method-name">pathconf</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns pathname configuration variable using fpathconf().</p>
<p><em>name</em> should be a constant under <code>Etc</code> which begins with <code>PC_</code>.</p>
<p>The return value is an integer or nil. nil means indefinite limit. (fpathconf() returns -1 but errno is not set.)</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'etc'</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">w</span>.<span class="ruby-identifier">pathconf</span>(<span class="ruby-constant">Etc</span><span class="ruby-operator">::</span><span class="ruby-constant">PC_PIPE_BUF</span>) <span class="ruby-comment">#=> 4096</span>
}
</pre>
<div class="method-source-code" id="pathconf-source">
<pre>static VALUE
io_pathconf(VALUE io, VALUE arg)
{
int name;
long ret;
rb_io_t *fptr;
name = NUM2INT(arg);
GetOpenFile(io, fptr);
errno = 0;
ret = fpathconf(fptr->fd, name);
if (ret == -1) {
if (errno == 0) /* no limit */
return Qnil;
rb_sys_fail("fpathconf");
}
return LONG2NUM(ret);
}</pre>
</div>
</div>
</div>
<div id="method-i-pid" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pid → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the process ID of a child process associated with <em>ios</em>. This will be set by <a href="IO.html#method-c-popen"><code>IO.popen</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">pipe</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">popen</span>(<span class="ruby-string">"-"</span>)
<span class="ruby-keyword">if</span> <span class="ruby-identifier">pipe</span>
<span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">"In parent, child pid is #{pipe.pid}"</span>
<span class="ruby-keyword">else</span>
<span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">"In child, pid is #{$$}"</span>
<span class="ruby-keyword">end</span>
</pre>
<p><em>produces:</em></p>
<pre>In child, pid is 26209
In parent, child pid is 26209</pre>
<div class="method-source-code" id="pid-source">
<pre>static VALUE
rb_io_pid(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!fptr->pid)
return Qnil;
return PIDT2NUM(fptr->pid);
}</pre>
</div>
</div>
</div>
<div id="method-i-pos" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pos → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the current offset (in bytes) of <em>ios</em>.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> <span class="ruby-comment">#=> 17</span>
</pre>
<div class="method-source-code" id="pos-source">
<pre>static VALUE
rb_io_tell(VALUE io)
{
rb_io_t *fptr;
off_t pos;
GetOpenFile(io, fptr);
pos = io_tell(fptr);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
pos -= fptr->rbuf.len;
return OFFT2NUM(pos);
}</pre>
</div>
</div>
</div>
<div id="method-i-pos-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pos = integer → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Seeks to the given position (in bytes) in <em>ios</em>. It is not guaranteed that seeking to the right position when <em>ios</em> is textmode.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> = <span class="ruby-value">17</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line two\n"</span>
</pre>
<div class="method-source-code" id="pos-3D-source">
<pre>static VALUE
rb_io_set_pos(VALUE io, VALUE offset)
{
rb_io_t *fptr;
off_t pos;
pos = NUM2OFFT(offset);
GetOpenFile(io, fptr);
pos = io_seek(fptr, pos, SEEK_SET);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
return OFFT2NUM(pos);
}</pre>
</div>
</div>
</div>
<div id="method-i-pread" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pread(maxlen, offset[, outbuf]) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads <em>maxlen</em> bytes from <em>ios</em> using the pread system call and returns them as a string without modifying the underlying descriptor offset. This is advantageous compared to combining <a href="IO.html#method-i-seek"><code>IO#seek</code></a> and <a href="IO.html#method-i-read"><code>IO#read</code></a> in that it is atomic, allowing multiple threads/process to share the same <a href="IO.html"><code>IO</code></a> object for reading the file at various locations. This bypasses any userspace buffering of the <a href="IO.html"><code>IO</code></a> layer. If the optional <em>outbuf</em> argument is present, it must reference a <a href="String.html"><code>String</code></a>, which will receive the data. Raises <a href="SystemCallError.html"><code>SystemCallError</code></a> on error, <a href="EOFError.html"><code>EOFError</code></a> at end of file and <a href="NotImplementedError.html"><code>NotImplementedError</code></a> if platform does not implement the system call.</p>
<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-string">"This is line one\nThis is line two\n"</span>)
<span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"testfile"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span> <span class="ruby-comment"># => "This is line one\nThis is line two\n"</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">pread</span>(<span class="ruby-value">12</span>, <span class="ruby-value">0</span>) <span class="ruby-comment"># => "This is line"</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">f</span>.<span class="ruby-identifier">pread</span>(<span class="ruby-value">9</span>, <span class="ruby-value">8</span>) <span class="ruby-comment"># => "line one\n"</span>
<span class="ruby-keyword">end</span>
</pre>
<div class="method-source-code" id="pread-source">
<pre>static VALUE
rb_io_pread(int argc, VALUE *argv, VALUE io)
{
VALUE len, offset, str;
rb_io_t *fptr;
ssize_t n;
struct prdwr_internal_arg arg;
int shrinkable;
rb_scan_args(argc, argv, "21", &len, &offset, &str);
arg.count = NUM2SIZET(len);
arg.offset = NUM2OFFT(offset);
shrinkable = io_setstrbuf(&str, (long)arg.count);
if (arg.count == 0) return str;
arg.buf = RSTRING_PTR(str);
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
arg.fd = fptr->fd;
rb_io_check_closed(fptr);
rb_str_locktmp(str);
n = (ssize_t)rb_ensure(pread_internal_call, (VALUE)&arg, rb_str_unlocktmp, str);
if (n < 0) {
rb_sys_fail_path(fptr->pathv);
}
io_set_read_length(str, n, shrinkable);
if (n == 0 && arg.count > 0) {
rb_eof_error();
}
return str;
}</pre>
</div>
</div>
</div>
<div id="method-i-pressed-3F" class="method-detail ">
<div class="method-heading">
<span class="method-name">pressed?</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="pressed-3F-source">
<pre>static VALUE
console_key_pressed_p(VALUE io, VALUE k)
{
int vk = -1;
if (FIXNUM_P(k)) {
vk = NUM2UINT(k);
}
else {
const struct vktable *t;
const char *kn;
if (SYMBOL_P(k)) {
k = rb_sym2str(k);
kn = RSTRING_PTR(k);
}
else {
kn = StringValuePtr(k);
}
t = console_win32_vk(kn, RSTRING_LEN(k));
if (!t || (vk = (short)t->vk) == -1) {
rb_raise(rb_eArgError, "unknown virtual key code: % "PRIsVALUE, k);
}
}
return GetKeyState(vk) & 0x80 ? Qtrue : Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-print" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
print → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
print(obj, ...) → nil
</span>
</div>
<div class="method-description">
<p>Writes the given object(s) to <em>ios</em>. Returns <code>nil</code>.</p>
<p>The stream must be opened for writing. Each given object that isn't a string will be converted by calling its <code>to_s</code> method. When called without arguments, prints the contents of <code>$_</code>.</p>
<p>If the output field separator (<code>$,</code>) is not <code>nil</code>, it is inserted between objects. If the output record separator (<code>$\</code>) is not <code>nil</code>, it is appended to the output.</p>
<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">print</span>(<span class="ruby-string">"This is "</span>, <span class="ruby-value">100</span>, <span class="ruby-string">" percent.\n"</span>)
</pre>
<p><em>produces:</em></p>
<pre>This is 100 percent.</pre>
<div class="method-source-code" id="print-source">
<pre>VALUE
rb_io_print(int argc, const VALUE *argv, VALUE out)
{
int i;
VALUE line;
/* if no argument given, print `$_' */
if (argc == 0) {
argc = 1;
line = rb_lastline_get();
argv = &line;
}
for (i=0; i<argc; i++) {
if (!NIL_P(rb_output_fs) && i>0) {
rb_io_write(out, rb_output_fs);
}
rb_io_write(out, argv[i]);
}
if (argc > 0 && !NIL_P(rb_output_rs)) {
rb_io_write(out, rb_output_rs);
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-printf" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
printf(format_string [, obj, ...]) → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Formats and writes to <em>ios</em>, converting parameters under control of the format string. See <a href="Kernel.html#method-i-sprintf"><code>Kernel#sprintf</code></a> for details.</p>
<div class="method-source-code" id="printf-source">
<pre>VALUE
rb_io_printf(int argc, const VALUE *argv, VALUE out)
{
rb_io_write(out, rb_f_sprintf(argc, argv));
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-putc" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
putc(obj) → obj
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>If <em>obj</em> is <a href="Numeric.html"><code>Numeric</code></a>, write the character whose code is the least-significant byte of <em>obj</em>. If <em>obj</em> is <a href="String.html"><code>String</code></a>, write the first character of <em>obj</em> to <em>ios</em>. Otherwise, raise <a href="TypeError.html"><code>TypeError</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">putc</span> <span class="ruby-string">"A"</span>
<span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">putc</span> <span class="ruby-value">65</span>
</pre>
<p><em>produces:</em></p>
<pre class="ruby"><span class="ruby-constant">AA</span>
</pre>
<div class="method-source-code" id="putc-source">
<pre>static VALUE
rb_io_putc(VALUE io, VALUE ch)
{
VALUE str;
if (RB_TYPE_P(ch, T_STRING)) {
str = rb_str_substr(ch, 0, 1);
}
else {
char c = NUM2CHR(ch);
str = rb_str_new(&c, 1);
}
rb_io_write(io, str);
return ch;
}</pre>
</div>
</div>
</div>
<div id="method-i-puts" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
puts(obj, ...) → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Writes the given object(s) to <em>ios</em>. Writes a newline after any that do not already end with a newline sequence. Returns <code>nil</code>.</p>
<p>The stream must be opened for writing. If called with an array argument, writes each element on a new line. Each given object that isn't a string or array will be converted by calling its <code>to_s</code> method. If called without arguments, outputs a single newline.</p>
<pre class="ruby"><span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">puts</span>(<span class="ruby-string">"this"</span>, <span class="ruby-string">"is"</span>, [<span class="ruby-string">"a"</span>, <span class="ruby-string">"test"</span>])
</pre>
<p><em>produces:</em></p>
<pre class="ruby"><span class="ruby-identifier">this</span>
<span class="ruby-identifier">is</span>
<span class="ruby-identifier">a</span>
<span class="ruby-identifier">test</span>
</pre>
<p>Note that <code>puts</code> always uses newlines and is not affected by the output record separator (<code>$\</code>).</p>
<div class="method-source-code" id="puts-source">
<pre>VALUE
rb_io_puts(int argc, const VALUE *argv, VALUE out)
{
int i, n;
VALUE line, args[2];
/* if no argument given, print newline. */
if (argc == 0) {
rb_io_write(out, rb_default_rs);
return Qnil;
}
for (i=0; i<argc; i++) {
if (RB_TYPE_P(argv[i], T_STRING)) {
line = argv[i];
goto string;
}
if (rb_exec_recursive(io_puts_ary, argv[i], out)) {
continue;
}
line = rb_obj_as_string(argv[i]);
string:
n = 0;
args[n++] = line;
if (RSTRING_LEN(line) == 0 ||
!rb_str_end_with_asciichar(line, '\n')) {
args[n++] = rb_default_rs;
}
rb_io_writev(out, n, args);
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-pwrite" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pwrite(string, offset) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Writes the given string to <em>ios</em> at <em>offset</em> using pwrite() system call. This is advantageous to combining <a href="IO.html#method-i-seek"><code>IO#seek</code></a> and <a href="IO.html#method-i-write"><code>IO#write</code></a> in that it is atomic, allowing multiple threads/process to share the same <a href="IO.html"><code>IO</code></a> object for reading the file at various locations. This bypasses any userspace buffering of the <a href="IO.html"><code>IO</code></a> layer. Returns the number of bytes written. Raises <a href="SystemCallError.html"><code>SystemCallError</code></a> on error and <a href="NotImplementedError.html"><code>NotImplementedError</code></a> if platform does not implement the system call.</p>
<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"out"</span>, <span class="ruby-string">"w"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pwrite</span>(<span class="ruby-string">"ABCDEF"</span>, <span class="ruby-value">3</span>) <span class="ruby-comment">#=> 6</span>
<span class="ruby-keyword">end</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">read</span>(<span class="ruby-string">"out"</span>) <span class="ruby-comment">#=> "\u0000\u0000\u0000ABCDEF"</span>
</pre>
<div class="method-source-code" id="pwrite-source">
<pre>static VALUE
rb_io_pwrite(VALUE io, VALUE str, VALUE offset)
{
rb_io_t *fptr;
ssize_t n;
struct prdwr_internal_arg arg;
VALUE tmp;
if (!RB_TYPE_P(str, T_STRING))
str = rb_obj_as_string(str);
arg.offset = NUM2OFFT(offset);
io = GetWriteIO(io);
GetOpenFile(io, fptr);
rb_io_check_writable(fptr);
arg.fd = fptr->fd;
tmp = rb_str_tmp_frozen_acquire(str);
arg.buf = RSTRING_PTR(tmp);
arg.count = (size_t)RSTRING_LEN(tmp);
n = (ssize_t)rb_thread_io_blocking_region(internal_pwrite_func, &arg, fptr->fd);
if (n < 0) rb_sys_fail_path(fptr->pathv);
rb_str_tmp_frozen_release(str, tmp);
return SSIZET2NUM(n);
}</pre>
</div>
</div>
</div>
<div id="method-i-raw" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
raw(min: nil, time: nil, intr: nil) {|io| }
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Yields <code>self</code> within raw mode, and returns the result of the block.</p>
<pre class="ruby"><span class="ruby-constant">STDIN</span>.<span class="ruby-identifier">raw</span>(<span class="ruby-operator">&</span><span class="ruby-value">:gets</span>)
</pre>
<p>will read and return a line without echo back and line editing.</p>
<p>The parameter <code>min</code> specifies the minimum number of bytes that should be received when a read operation is performed. (default: 1)</p>
<p>The parameter <code>time</code> specifies the timeout in <em>seconds</em> with a precision of 1/10 of a second. (default: 0)</p>
<p>If the parameter <code>intr</code> is <code>true</code>, enables break, interrupt, quit, and suspend special characters.</p>
<p>Refer to the manual page of termios for further details.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="raw-source">
<pre>static VALUE
console_raw(int argc, VALUE *argv, VALUE io)
{
rawmode_arg_t opts, *optp = rawmode_opt(&argc, argv, 0, 0, &opts);
return ttymode(io, rb_yield, io, set_rawmode, optp);
}</pre>
</div>
</div>
</div>
<div id="method-i-raw-21" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
raw!(min: nil, time: nil, intr: nil) → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Enables raw mode, and returns <code>io</code>.</p>
<p>If the terminal mode needs to be back, use <code>io.raw { ... }</code>.</p>
<p>See <a href="IO.html#method-i-raw"><code>IO#raw</code></a> for details on the parameters.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="raw-21-source">
<pre>static VALUE
console_set_raw(int argc, VALUE *argv, VALUE io)
{
conmode t;
rb_io_t *fptr;
int fd;
rawmode_arg_t opts, *optp = rawmode_opt(&argc, argv, 0, 0, &opts);
GetOpenFile(io, fptr);
fd = GetReadFD(fptr);
if (!getattr(fd, &t)) rb_sys_fail(0);
set_rawmode(&t, optp);
if (!setattr(fd, &t)) rb_sys_fail(0);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-read" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
read([length [, outbuf]]) → string, outbuf, or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads <em>length</em> bytes from the I/O stream.</p>
<p><em>length</em> must be a non-negative integer or <code>nil</code>.</p>
<p>If <em>length</em> is a positive integer, <code>read</code> tries to read <em>length</em> bytes without any conversion (binary mode). It returns <code>nil</code> if an EOF is encountered before anything can be read. Fewer than <em>length</em> bytes are returned if an EOF is encountered during the read. In the case of an integer <em>length</em>, the resulting string is always in ASCII-8BIT encoding.</p>
<p>If <em>length</em> is omitted or is <code>nil</code>, it reads until EOF and the encoding conversion is applied, if applicable. A string is returned even if EOF is encountered before any data is read.</p>
<p>If <em>length</em> is zero, it returns an empty string (<code>""</code>).</p>
<p>If the optional <em>outbuf</em> argument is present, it must reference a <a href="String.html"><code>String</code></a>, which will receive the data. The <em>outbuf</em> will contain only the received data after the method call even if it is not empty at the beginning.</p>
<p>When this method is called at end of file, it returns <code>nil</code> or <code>""</code>, depending on <em>length</em>: <code>read</code>, <code>read(nil)</code>, and <code>read(0)</code> return <code>""</code>, <code>read(<em>positive_integer</em>)</code> returns <code>nil</code>.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">16</span>) <span class="ruby-comment">#=> "This is line one"</span>
<span class="ruby-comment"># read whole file</span>
<span class="ruby-identifier">open</span>(<span class="ruby-string">"file"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">data</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span> <span class="ruby-comment"># This returns a string even if the file is empty.</span>
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># iterate over fixed length records</span>
<span class="ruby-identifier">open</span>(<span class="ruby-string">"fixed-record-file"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">while</span> <span class="ruby-identifier">record</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">256</span>)
<span class="ruby-comment"># ...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># iterate over variable length records,</span>
<span class="ruby-comment"># each record is prefixed by its 32-bit length</span>
<span class="ruby-identifier">open</span>(<span class="ruby-string">"variable-record-file"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">f</span><span class="ruby-operator">|</span>
<span class="ruby-keyword">while</span> <span class="ruby-identifier">len</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-value">4</span>)
<span class="ruby-identifier">len</span> = <span class="ruby-identifier">len</span>.<span class="ruby-identifier">unpack</span>(<span class="ruby-string">"N"</span>)[<span class="ruby-value">0</span>] <span class="ruby-comment"># 32-bit length</span>
<span class="ruby-identifier">record</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">read</span>(<span class="ruby-identifier">len</span>) <span class="ruby-comment"># This returns a string even if len is 0.</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>
<p>Note that this method behaves like the fread() function in C. This means it retries to invoke read(2) system calls to read data with the specified length (or until EOF). This behavior is preserved even if <em>ios</em> is in non-blocking mode. (This method is non-blocking flag insensitive as other methods.) If you need the behavior like a single read(2) system call, consider <a href="IO.html#method-i-readpartial"><code>readpartial</code></a>, <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a>, and <a href="IO.html#method-i-sysread"><code>sysread</code></a>.</p>
<div class="method-source-code" id="read-source">
<pre>static VALUE
io_read(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
long n, len;
VALUE length, str;
int shrinkable;
#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
int previous_mode;
#endif
rb_scan_args(argc, argv, "02", &length, &str);
if (NIL_P(length)) {
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
return read_all(fptr, remain_size(fptr), str);
}
len = NUM2LONG(length);
if (len < 0) {
rb_raise(rb_eArgError, "negative length %ld given", len);
}
shrinkable = io_setstrbuf(&str,len);
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
if (len == 0) {
io_set_read_length(str, 0, shrinkable);
return str;
}
READ_CHECK(fptr);
#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
previous_mode = set_binary_mode_with_seek_cur(fptr);
#endif
n = io_fread(str, 0, len, fptr);
io_set_read_length(str, n, shrinkable);
#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32)
if (previous_mode == O_TEXT) {
setmode(fptr->fd, O_TEXT);
}
#endif
if (n == 0) return Qnil;
return str;
}</pre>
</div>
</div>
</div>
<div id="method-i-read_nonblock" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
read_nonblock(maxlen [, options]) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
read_nonblock(maxlen, outbuf [, options]) → outbuf
</span>
</div>
<div class="method-description">
<p>Reads at most <em>maxlen</em> bytes from <em>ios</em> using the read(2) system call after O_NONBLOCK is set for the underlying file descriptor.</p>
<p>If the optional <em>outbuf</em> argument is present, it must reference a <a href="String.html"><code>String</code></a>, which will receive the data. The <em>outbuf</em> will contain only the received data after the method call even if it is not empty at the beginning.</p>
<p><a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> just calls the read(2) system call. It causes all errors the read(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc. The caller should care such errors.</p>
<p>If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a>. So <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> can be used to rescue the exceptions for retrying read_nonblock.</p>
<p><a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> causes <a href="EOFError.html"><code>EOFError</code></a> on EOF.</p>
<p>On some platforms, such as Windows, non-blocking mode is not supported on <a href="IO.html"><code>IO</code></a> objects other than sockets. In such cases, Errno::EBADF will be raised.</p>
<p>If the read byte buffer is not empty, <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> reads from the buffer like readpartial. In this case, the read(2) system call is not called.</p>
<p>When <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> raises an exception kind of <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a>, <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> should not be called until io is readable for avoiding busy loop. This can be done as follows.</p>
<pre class="ruby"><span class="ruby-comment"># emulates blocking read (readpartial).</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">result</span> = <span class="ruby-identifier">io</span>.<span class="ruby-identifier">read_nonblock</span>(<span class="ruby-identifier">maxlen</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">io</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
</pre>
<p>Although <a href="IO.html#method-i-read_nonblock"><code>IO#read_nonblock</code></a> doesn't raise <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. <a href="OpenSSL/Buffering.html#method-i-read_nonblock"><code>OpenSSL::Buffering#read_nonblock</code></a> can raise <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. If <a href="IO.html"><code>IO</code></a> and SSL should be used polymorphically, <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> should be rescued too. See the document of <a href="OpenSSL/Buffering.html#method-i-read_nonblock"><code>OpenSSL::Buffering#read_nonblock</code></a> for sample code.</p>
<p>Note that this method is identical to readpartial except the non-blocking flag is set.</p>
<p>By specifying a keyword argument <em>exception</em> to <code>false</code>, you can indicate that <a href="IO.html#method-i-read_nonblock"><code>read_nonblock</code></a> should not raise an <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> exception, but return the symbol <code>:wait_readable</code> instead. At EOF, it will return nil instead of raising <a href="EOFError.html"><code>EOFError</code></a>.</p>
<div class="method-source-code" id="read_nonblock-source">
<pre><span class="ruby-comment"># File io.rb, line 62</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">read_nonblock</span>(<span class="ruby-identifier">len</span>, <span class="ruby-identifier">buf</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-value">exception:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">__builtin_io_read_nonblock</span>(<span class="ruby-identifier">len</span>, <span class="ruby-identifier">buf</span>, <span class="ruby-identifier">exception</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-readbyte" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
readbyte → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads a byte as with <a href="IO.html#method-i-getbyte"><code>IO#getbyte</code></a>, but raises an <a href="EOFError.html"><code>EOFError</code></a> on end of file.</p>
<div class="method-source-code" id="readbyte-source">
<pre>static VALUE
rb_io_readbyte(VALUE io)
{
VALUE c = rb_io_getbyte(io);
if (NIL_P(c)) {
rb_eof_error();
}
return c;
}</pre>
</div>
</div>
</div>
<div id="method-i-readchar" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
readchar → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads a one-character string from <em>ios</em>. Raises an <a href="EOFError.html"><code>EOFError</code></a> on end of file.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readchar</span> <span class="ruby-comment">#=> "h"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readchar</span> <span class="ruby-comment">#=> "e"</span>
</pre>
<div class="method-source-code" id="readchar-source">
<pre>static VALUE
rb_io_readchar(VALUE io)
{
VALUE c = rb_io_getc(io);
if (NIL_P(c)) {
rb_eof_error();
}
return c;
}</pre>
</div>
</div>
</div>
<div id="method-i-readline" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
readline(sep=$/ [, getline_args]) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readline(limit [, getline_args]) → string
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readline(sep, limit [, getline_args]) → string
</span>
</div>
<div class="method-description">
<p>Reads a line as with <a href="IO.html#method-i-gets"><code>IO#gets</code></a>, but raises an <a href="EOFError.html"><code>EOFError</code></a> on end of file.</p>
<div class="method-source-code" id="readline-source">
<pre>static VALUE
rb_io_readline(int argc, VALUE *argv, VALUE io)
{
VALUE line = rb_io_gets_m(argc, argv, io);
if (NIL_P(line)) {
rb_eof_error();
}
return line;
}</pre>
</div>
</div>
</div>
<div id="method-i-readlines" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
readlines(sep=$/ [, getline_args]) → array
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readlines(limit [, getline_args]) → array
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readlines(sep, limit [, getline_args]) → array
</span>
</div>
<div class="method-description">
<p>Reads all of the lines in <em>ios</em>, and returns them in an array. Lines are separated by the optional <em>sep</em>. If <em>sep</em> is <code>nil</code>, the rest of the stream is returned as a single record. If the first argument is an integer, or an optional second argument is given, the returning string would not be longer than the given value in bytes. The stream must be opened for reading or an <a href="IOError.html"><code>IOError</code></a> will be raised.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>[<span class="ruby-value">0</span>] <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>, <span class="ruby-value">chomp:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readlines</span>[<span class="ruby-value">0</span>] <span class="ruby-comment">#=> "This is line one"</span>
</pre>
<p>See <a href="IO.html#method-c-readlines"><code>IO.readlines</code></a> for details about getline_args.</p>
<div class="method-source-code" id="readlines-source">
<pre>static VALUE
rb_io_readlines(int argc, VALUE *argv, VALUE io)
{
struct getline_arg args;
prepare_getline_args(argc, argv, &args, io);
return io_readlines(&args, io);
}</pre>
</div>
</div>
</div>
<div id="method-i-readpartial" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
readpartial(maxlen) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
readpartial(maxlen, outbuf) → outbuf
</span>
</div>
<div class="method-description">
<p>Reads at most <em>maxlen</em> bytes from the I/O stream. It blocks only if <em>ios</em> has no data immediately available. It doesn't block if some data available.</p>
<p>If the optional <em>outbuf</em> argument is present, it must reference a <a href="String.html"><code>String</code></a>, which will receive the data. The <em>outbuf</em> will contain only the received data after the method call even if it is not empty at the beginning.</p>
<p>It raises <a href="EOFError.html"><code>EOFError</code></a> on end of file.</p>
<p>readpartial is designed for streams such as pipe, socket, tty, etc. It blocks only when no data immediately available. This means that it blocks only when following all conditions hold.</p>
<ul><li>
<p>the byte buffer in the <a href="IO.html"><code>IO</code></a> object is empty.</p>
</li><li>
<p>the content of the stream is empty.</p>
</li><li>
<p>the stream is not reached to EOF.</p>
</li></ul>
<p>When readpartial blocks, it waits data or EOF on the stream. If some data is reached, readpartial returns with the data. If EOF is reached, readpartial raises <a href="EOFError.html"><code>EOFError</code></a>.</p>
<p>When readpartial doesn't blocks, it returns or raises immediately. If the byte buffer is not empty, it returns the data in the buffer. Otherwise if the stream has some content, it returns the data in the stream. Otherwise if the stream is reached to EOF, it raises <a href="EOFError.html"><code>EOFError</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span> <span class="ruby-comment"># buffer pipe content</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"abc"</span> <span class="ruby-comment"># "" "abc".</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>) <span class="ruby-comment">#=> "abc" "" ""</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>) <span class="ruby-comment"># blocks because buffer and pipe is empty.</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span> <span class="ruby-comment"># buffer pipe content</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"abc"</span> <span class="ruby-comment"># "" "abc"</span>
<span class="ruby-identifier">w</span>.<span class="ruby-identifier">close</span> <span class="ruby-comment"># "" "abc" EOF</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>) <span class="ruby-comment">#=> "abc" "" EOF</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>) <span class="ruby-comment"># raises EOFError</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span> <span class="ruby-comment"># buffer pipe content</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"abc\ndef\n"</span> <span class="ruby-comment"># "" "abc\ndef\n"</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "abc\n" "def\n" ""</span>
<span class="ruby-identifier">w</span> <span class="ruby-operator"><<</span> <span class="ruby-string">"ghi\n"</span> <span class="ruby-comment"># "def\n" "ghi\n"</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>) <span class="ruby-comment">#=> "def\n" "" "ghi\n"</span>
<span class="ruby-identifier">r</span>.<span class="ruby-identifier">readpartial</span>(<span class="ruby-value">4096</span>) <span class="ruby-comment">#=> "ghi\n" "" ""</span>
</pre>
<p>Note that readpartial behaves similar to sysread. The differences are:</p>
<ul><li>
<p>If the byte buffer is not empty, read from the byte buffer instead of “sysread for buffered <a href="IO.html"><code>IO</code></a> (<a href="IOError.html"><code>IOError</code></a>)”.</p>
</li><li>
<p>It doesn't cause Errno::EWOULDBLOCK and Errno::EINTR. When readpartial meets EWOULDBLOCK and EINTR by read system call, readpartial retry the system call.</p>
</li></ul>
<p>The latter means that readpartial is nonblocking-flag insensitive. It blocks on the situation <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a> causes Errno::EWOULDBLOCK as if the fd is blocking mode.</p>
<div class="method-source-code" id="readpartial-source">
<pre>static VALUE
io_readpartial(int argc, VALUE *argv, VALUE io)
{
VALUE ret;
ret = io_getpartial(argc, argv, io, Qnil, 0);
if (NIL_P(ret))
rb_eof_error();
return ret;
}</pre>
</div>
</div>
</div>
<div id="method-i-ready-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ready? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns true if input available without blocking, or false.</p>
<div class="method-source-code" id="ready-3F-source">
<pre>static VALUE
io_ready_p(VALUE io)
{
rb_io_t *fptr;
struct timeval tv = {0, 0};
GetOpenFile(io, fptr);
rb_io_check_readable(fptr);
if (rb_io_read_pending(fptr)) return Qtrue;
if (wait_for_single_fd(fptr, RB_WAITFD_IN, &tv))
return Qtrue;
return Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-reopen" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
reopen(other_IO) → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
reopen(path, mode [, opt]) → ios
</span>
</div>
<div class="method-description">
<p>Reassociates <em>ios</em> with the I/O stream given in <em>other_IO</em> or to a new stream opened on <em>path</em>. This may dynamically change the actual class of this stream. The <code>mode</code> and <code>opt</code> parameters accept the same values as <a href="IO.html#method-c-open"><code>IO.open</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">f1</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f2</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f2</span>.<span class="ruby-identifier">readlines</span>[<span class="ruby-value">0</span>] <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">f2</span>.<span class="ruby-identifier">reopen</span>(<span class="ruby-identifier">f1</span>) <span class="ruby-comment">#=> #<File:testfile></span>
<span class="ruby-identifier">f2</span>.<span class="ruby-identifier">readlines</span>[<span class="ruby-value">0</span>] <span class="ruby-comment">#=> "This is line one\n"</span>
</pre>
<div class="method-source-code" id="reopen-source">
<pre>static VALUE
rb_io_reopen(int argc, VALUE *argv, VALUE file)
{
VALUE fname, nmode, opt;
int oflags;
rb_io_t *fptr;
if (rb_scan_args(argc, argv, "11:", &fname, &nmode, &opt) == 1) {
VALUE tmp = rb_io_check_io(fname);
if (!NIL_P(tmp)) {
return io_reopen(file, tmp);
}
}
FilePathValue(fname);
rb_io_taint_check(file);
fptr = RFILE(file)->fptr;
if (!fptr) {
fptr = RFILE(file)->fptr = ZALLOC(rb_io_t);
}
if (!NIL_P(nmode) || !NIL_P(opt)) {
int fmode;
convconfig_t convconfig;
rb_io_extract_modeenc(&nmode, 0, opt, &oflags, &fmode, &convconfig);
if (IS_PREP_STDIO(fptr) &&
((fptr->mode & FMODE_READWRITE) & (fmode & FMODE_READWRITE)) !=
(fptr->mode & FMODE_READWRITE)) {
rb_raise(rb_eArgError,
"%s can't change access mode from \"%s\" to \"%s\"",
PREP_STDIO_NAME(fptr), rb_io_fmode_modestr(fptr->mode),
rb_io_fmode_modestr(fmode));
}
fptr->mode = fmode;
fptr->encs = convconfig;
}
else {
oflags = rb_io_fmode_oflags(fptr->mode);
}
fptr->pathv = fname;
if (fptr->fd < 0) {
fptr->fd = rb_sysopen(fptr->pathv, oflags, 0666);
fptr->stdio_file = 0;
return file;
}
if (fptr->mode & FMODE_WRITABLE) {
if (io_fflush(fptr) < 0)
rb_sys_fail(0);
}
fptr->rbuf.off = fptr->rbuf.len = 0;
if (fptr->stdio_file) {
int e = rb_freopen(rb_str_encode_ospath(fptr->pathv),
rb_io_oflags_modestr(oflags),
fptr->stdio_file);
if (e) rb_syserr_fail_path(e, fptr->pathv);
fptr->fd = fileno(fptr->stdio_file);
rb_fd_fix_cloexec(fptr->fd);
#ifdef USE_SETVBUF
if (setvbuf(fptr->stdio_file, NULL, _IOFBF, 0) != 0)
rb_warn("setvbuf() can't be honoured for %"PRIsVALUE, fptr->pathv);
#endif
if (fptr->stdio_file == stderr) {
if (setvbuf(fptr->stdio_file, NULL, _IONBF, BUFSIZ) != 0)
rb_warn("setvbuf() can't be honoured for %"PRIsVALUE, fptr->pathv);
}
else if (fptr->stdio_file == stdout && isatty(fptr->fd)) {
if (setvbuf(fptr->stdio_file, NULL, _IOLBF, BUFSIZ) != 0)
rb_warn("setvbuf() can't be honoured for %"PRIsVALUE, fptr->pathv);
}
}
else {
int tmpfd = rb_sysopen(fptr->pathv, oflags, 0666);
int err = 0;
if (rb_cloexec_dup2(tmpfd, fptr->fd) < 0)
err = errno;
(void)close(tmpfd);
if (err) {
rb_syserr_fail_path(err, fptr->pathv);
}
}
return file;
}</pre>
</div>
</div>
</div>
<div id="method-i-rewind" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
rewind → 0
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Positions <em>ios</em> to the beginning of input, resetting <a href="IO.html#method-i-lineno"><code>lineno</code></a> to zero.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readline</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">rewind</span> <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">lineno</span> <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readline</span> <span class="ruby-comment">#=> "This is line one\n"</span>
</pre>
<p>Note that it cannot be used with streams such as pipes, ttys, and sockets.</p>
<div class="method-source-code" id="rewind-source">
<pre>static VALUE
rb_io_rewind(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (io_seek(fptr, 0L, 0) < 0 && errno) rb_sys_fail_path(fptr->pathv);
if (io == ARGF.current_file) {
ARGF.lineno -= fptr->lineno;
}
fptr->lineno = 0;
if (fptr->readconv) {
clear_readconv(fptr);
}
return INT2FIX(0);
}</pre>
</div>
</div>
</div>
<div id="method-i-scroll_backward" class="method-detail ">
<div class="method-heading">
<span class="method-name">scroll_backward</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="scroll_backward-source">
<pre>static VALUE
console_scroll_backward(VALUE io, VALUE val)
{
return console_scroll(io, -NUM2INT(val));
}</pre>
</div>
</div>
</div>
<div id="method-i-scroll_forward" class="method-detail ">
<div class="method-heading">
<span class="method-name">scroll_forward</span><span
class="method-args">(p1)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="scroll_forward-source">
<pre>static VALUE
console_scroll_forward(VALUE io, VALUE val)
{
return console_scroll(io, +NUM2INT(val));
}</pre>
</div>
</div>
</div>
<div id="method-i-seek" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
seek(amount, whence=IO::SEEK_SET) → 0
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Seeks to a given offset <em>anInteger</em> in the stream according to the value of <em>whence</em>:</p>
<pre>:CUR or IO::SEEK_CUR | Seeks to _amount_ plus current position
----------------------+--------------------------------------------------
:END or IO::SEEK_END | Seeks to _amount_ plus end of stream (you
| probably want a negative value for _amount_)
----------------------+--------------------------------------------------
:SET or IO::SEEK_SET | Seeks to the absolute location given by _amount_</pre>
<p>Example:</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">seek</span>(<span class="ruby-value">-13</span>, <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">SEEK_END</span>) <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">readline</span> <span class="ruby-comment">#=> "And so on...\n"</span>
</pre>
<div class="method-source-code" id="seek-source">
<pre>static VALUE
rb_io_seek_m(int argc, VALUE *argv, VALUE io)
{
VALUE offset, ptrname;
int whence = SEEK_SET;
if (rb_scan_args(argc, argv, "11", &offset, &ptrname) == 2) {
whence = interpret_seek_whence(ptrname);
}
return rb_io_seek(io, offset, whence);
}</pre>
</div>
</div>
</div>
<div id="method-i-set_encoding" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
set_encoding(ext_enc) → io
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
set_encoding("ext_enc:int_enc") → io
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
set_encoding(ext_enc, int_enc) → io
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
set_encoding("ext_enc:int_enc", opt) → io
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
set_encoding(ext_enc, int_enc, opt) → io
</span>
</div>
<div class="method-description">
<p>If single argument is specified, read string from io is tagged with the encoding specified. If encoding is a colon separated two encoding names “A:B”, the read string is converted from encoding A (external encoding) to encoding B (internal encoding), then tagged with B. If two arguments are specified, those must be encoding objects or encoding names, and the first one is the external encoding, and the second one is the internal encoding. If the external encoding and the internal encoding is specified, optional hash argument specify the conversion option.</p>
<div class="method-source-code" id="set_encoding-source">
<pre>static VALUE
rb_io_set_encoding(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
VALUE v1, v2, opt;
if (!RB_TYPE_P(io, T_FILE)) {
return rb_funcallv(io, id_set_encoding, argc, argv);
}
argc = rb_scan_args(argc, argv, "11:", &v1, &v2, &opt);
GetOpenFile(io, fptr);
io_encoding_set(fptr, v1, v2, opt);
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-set_encoding_by_bom" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
set_encoding_by_bom → encoding or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Checks if <code>ios</code> starts with a BOM, and then consumes it and sets the external encoding. Returns the result encoding if found, or nil. If <code>ios</code> is not binmode or its encoding has been set already, an exception will be raised.</p>
<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"bom.txt"</span>, <span class="ruby-string">"\u{FEFF}abc"</span>)
<span class="ruby-identifier">ios</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"bom.txt"</span>, <span class="ruby-string">"rb"</span>)
<span class="ruby-identifier">ios</span>.<span class="ruby-identifier">set_encoding_by_bom</span> <span class="ruby-comment">#=> #<Encoding:UTF-8></span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"nobom.txt"</span>, <span class="ruby-string">"abc"</span>)
<span class="ruby-identifier">ios</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"nobom.txt"</span>, <span class="ruby-string">"rb"</span>)
<span class="ruby-identifier">ios</span>.<span class="ruby-identifier">set_encoding_by_bom</span> <span class="ruby-comment">#=> nil</span>
</pre>
<div class="method-source-code" id="set_encoding_by_bom-source">
<pre>static VALUE
rb_io_set_encoding_by_bom(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!(fptr->mode & FMODE_BINMODE)) {
rb_raise(rb_eArgError, "ASCII incompatible encoding needs binmode");
}
if (fptr->encs.enc2) {
rb_raise(rb_eArgError, "encoding conversion is set");
}
else if (fptr->encs.enc && fptr->encs.enc != rb_ascii8bit_encoding()) {
rb_raise(rb_eArgError, "encoding is set to %s already",
rb_enc_name(fptr->encs.enc));
}
if (!io_set_encoding_by_bom(io)) return Qnil;
return rb_enc_from_encoding(fptr->encs.enc);
}</pre>
</div>
</div>
</div>
<div id="method-i-stat" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
stat → stat
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns status information for <em>ios</em> as an object of type <a href="File/Stat.html"><code>File::Stat</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">s</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">stat</span>
<span class="ruby-string">"%o"</span> <span class="ruby-operator">%</span> <span class="ruby-identifier">s</span>.<span class="ruby-identifier">mode</span> <span class="ruby-comment">#=> "100644"</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">blksize</span> <span class="ruby-comment">#=> 4096</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">atime</span> <span class="ruby-comment">#=> Wed Apr 09 08:53:54 CDT 2003</span>
</pre>
<div class="method-source-code" id="stat-source">
<pre>static VALUE
rb_io_stat(VALUE obj)
{
rb_io_t *fptr;
struct stat st;
GetOpenFile(obj, fptr);
if (fstat(fptr->fd, &st) == -1) {
rb_sys_fail_path(fptr->pathv);
}
return rb_stat_new(&st);
}</pre>
</div>
</div>
</div>
<div id="method-i-sync" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
sync → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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 <a href="IO.html#method-i-fsync"><code>IO#fsync</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> <span class="ruby-comment">#=> false</span>
</pre>
<div class="method-source-code" id="sync-source">
<pre>static VALUE
rb_io_sync(VALUE io)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
return (fptr->mode & FMODE_SYNC) ? Qtrue : Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-sync-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
sync = boolean → boolean
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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 <a href="IO.html#method-i-fsync"><code>IO#fsync</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
</pre>
<div class="method-source-code" id="sync-3D-source">
<pre>static VALUE
rb_io_set_sync(VALUE io, VALUE sync)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
if (RTEST(sync)) {
fptr->mode |= FMODE_SYNC;
}
else {
fptr->mode &= ~FMODE_SYNC;
}
return sync;
}</pre>
</div>
</div>
</div>
<div id="method-i-sysread" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
sysread(maxlen[, outbuf]) → string
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Reads <em>maxlen</em> 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.</p>
<p>If the optional <em>outbuf</em> argument is present, it must reference a <a href="String.html"><code>String</code></a>, which will receive the data. The <em>outbuf</em> will contain only the received data after the method call even if it is not empty at the beginning.</p>
<p>Raises <a href="SystemCallError.html"><code>SystemCallError</code></a> on error and <a href="EOFError.html"><code>EOFError</code></a> at end of file.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sysread</span>(<span class="ruby-value">16</span>) <span class="ruby-comment">#=> "This is line one"</span>
</pre>
<div class="method-source-code" id="sysread-source">
<pre>static VALUE
rb_io_sysread(int argc, VALUE *argv, VALUE io)
{
VALUE len, str;
rb_io_t *fptr;
long n, ilen;
struct io_internal_read_struct iis;
int shrinkable;
rb_scan_args(argc, argv, "11", &len, &str);
ilen = NUM2LONG(len);
shrinkable = io_setstrbuf(&str, ilen);
if (ilen == 0) return str;
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
if (READ_DATA_BUFFERED(fptr)) {
rb_raise(rb_eIOError, "sysread for buffered IO");
}
/*
* FIXME: removing rb_thread_wait_fd() here changes sysread semantics
* on non-blocking IOs. However, it's still currently possible
* for sysread to raise Errno::EAGAIN if another thread read()s
* the IO after we return from rb_thread_wait_fd() but before
* we call read()
*/
rb_thread_wait_fd(fptr->fd);
rb_io_check_closed(fptr);
io_setstrbuf(&str, ilen);
iis.fd = fptr->fd;
iis.nonblock = 1; /* for historical reasons, maybe (see above) */
iis.buf = RSTRING_PTR(str);
iis.capa = ilen;
n = read_internal_locktmp(str, &iis);
if (n < 0) {
rb_sys_fail_path(fptr->pathv);
}
io_set_read_length(str, n, shrinkable);
if (n == 0 && ilen > 0) {
rb_eof_error();
}
return str;
}</pre>
</div>
</div>
</div>
<div id="method-i-sysseek" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
sysseek(offset, whence=IO::SEEK_SET) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Seeks to a given <em>offset</em> in the stream according to the value of <em>whence</em> (see <a href="IO.html#method-i-seek"><code>IO#seek</code></a> for values of <em>whence</em>). Returns the new offset into the file.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sysseek</span>(<span class="ruby-value">-13</span>, <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">SEEK_END</span>) <span class="ruby-comment">#=> 53</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">sysread</span>(<span class="ruby-value">10</span>) <span class="ruby-comment">#=> "And so on."</span>
</pre>
<div class="method-source-code" id="sysseek-source">
<pre>static VALUE
rb_io_sysseek(int argc, VALUE *argv, VALUE io)
{
VALUE offset, ptrname;
int whence = SEEK_SET;
rb_io_t *fptr;
off_t pos;
if (rb_scan_args(argc, argv, "11", &offset, &ptrname) == 2) {
whence = interpret_seek_whence(ptrname);
}
pos = NUM2OFFT(offset);
GetOpenFile(io, fptr);
if ((fptr->mode & FMODE_READABLE) &&
(READ_DATA_BUFFERED(fptr) || READ_CHAR_PENDING(fptr))) {
rb_raise(rb_eIOError, "sysseek for buffered IO");
}
if ((fptr->mode & FMODE_WRITABLE) && fptr->wbuf.len) {
rb_warn("sysseek for buffered IO");
}
errno = 0;
pos = lseek(fptr->fd, pos, whence);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
return OFFT2NUM(pos);
}</pre>
</div>
</div>
</div>
<div id="method-i-syswrite" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
syswrite(string) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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 <a href="SystemCallError.html"><code>SystemCallError</code></a> on error.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"out"</span>, <span class="ruby-string">"w"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">syswrite</span>(<span class="ruby-string">"ABCDEF"</span>) <span class="ruby-comment">#=> 6</span>
</pre>
<div class="method-source-code" id="syswrite-source">
<pre>static VALUE
rb_io_syswrite(VALUE io, VALUE str)
{
VALUE tmp;
rb_io_t *fptr;
long n, len;
const char *ptr;
if (!RB_TYPE_P(str, T_STRING))
str = rb_obj_as_string(str);
io = GetWriteIO(io);
GetOpenFile(io, fptr);
rb_io_check_writable(fptr);
if (fptr->wbuf.len) {
rb_warn("syswrite for buffered IO");
}
tmp = rb_str_tmp_frozen_acquire(str);
RSTRING_GETMEM(tmp, ptr, len);
n = rb_write_internal(fptr->fd, ptr, len);
if (n < 0) rb_sys_fail_path(fptr->pathv);
rb_str_tmp_frozen_release(str, tmp);
return LONG2FIX(n);
}</pre>
</div>
</div>
</div>
<div id="method-i-tell" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
tell → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the current offset (in bytes) of <em>ios</em>.</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>)
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> <span class="ruby-comment">#=> 0</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">gets</span> <span class="ruby-comment">#=> "This is line one\n"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">pos</span> <span class="ruby-comment">#=> 17</span>
</pre>
<div class="method-source-code" id="tell-source">
<pre>static VALUE
rb_io_tell(VALUE io)
{
rb_io_t *fptr;
off_t pos;
GetOpenFile(io, fptr);
pos = io_tell(fptr);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
pos -= fptr->rbuf.len;
return OFFT2NUM(pos);
}</pre>
</div>
</div>
</div>
<div id="method-i-to_i" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">to_i</span><span
class="method-args">()</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="IO.html#method-i-fileno">fileno</a>
</div>
</div>
<div id="method-i-to_io" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
to_io → ios
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <em>ios</em>.</p>
<div class="method-source-code" id="to_io-source">
<pre>static VALUE
rb_io_to_io(VALUE io)
{
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-tty-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
tty? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if <em>ios</em> is associated with a terminal device (tty), <code>false</code> otherwise.</p>
<pre class="ruby"><span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>).<span class="ruby-identifier">isatty</span> <span class="ruby-comment">#=> false</span>
<span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"/dev/tty"</span>).<span class="ruby-identifier">isatty</span> <span class="ruby-comment">#=> true</span>
</pre>
<div class="method-source-code" id="tty-3F-source">
<pre>static VALUE
rb_io_isatty(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (isatty(fptr->fd) == 0)
return Qfalse;
return Qtrue;
}</pre>
</div>
</div>
</div>
<div id="method-i-ungetbyte" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ungetbyte(string) → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
ungetbyte(integer) → nil
</span>
</div>
<div class="method-description">
<p>Pushes back bytes (passed as a parameter) onto <em>ios</em>, such that a subsequent buffered read will return it. Only one byte may be pushed back before a subsequent read operation (that is, you will be able to read only the last of several bytes that have been pushed back). Has no effect with unbuffered reads (such as <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a>).</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>) <span class="ruby-comment">#=> #<File:testfile></span>
<span class="ruby-identifier">b</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">getbyte</span> <span class="ruby-comment">#=> 0x38</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetbyte</span>(<span class="ruby-identifier">b</span>) <span class="ruby-comment">#=> nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getbyte</span> <span class="ruby-comment">#=> 0x38</span>
</pre>
<div class="method-source-code" id="ungetbyte-source">
<pre>VALUE
rb_io_ungetbyte(VALUE io, VALUE b)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
switch (TYPE(b)) {
case T_NIL:
return Qnil;
case T_FIXNUM:
case T_BIGNUM: ;
VALUE v = rb_int_modulo(b, INT2FIX(256));
unsigned char c = NUM2INT(v) & 0xFF;
b = rb_str_new((const char *)&c, 1);
break;
default:
SafeStringValue(b);
}
io_ungetbyte(b, fptr);
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-ungetc" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ungetc(string) → nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Pushes back one character (passed as a parameter) onto <em>ios</em>, such that a subsequent buffered character 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 <a href="IO.html#method-i-sysread"><code>IO#sysread</code></a>).</p>
<pre class="ruby"><span class="ruby-identifier">f</span> = <span class="ruby-constant">File</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"testfile"</span>) <span class="ruby-comment">#=> #<File:testfile></span>
<span class="ruby-identifier">c</span> = <span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span> <span class="ruby-comment">#=> "8"</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">ungetc</span>(<span class="ruby-identifier">c</span>) <span class="ruby-comment">#=> nil</span>
<span class="ruby-identifier">f</span>.<span class="ruby-identifier">getc</span> <span class="ruby-comment">#=> "8"</span>
</pre>
<div class="method-source-code" id="ungetc-source">
<pre>VALUE
rb_io_ungetc(VALUE io, VALUE c)
{
rb_io_t *fptr;
long len;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
if (NIL_P(c)) return Qnil;
if (FIXNUM_P(c)) {
c = rb_enc_uint_chr(FIX2UINT(c), io_read_encoding(fptr));
}
else if (RB_TYPE_P(c, T_BIGNUM)) {
c = rb_enc_uint_chr(NUM2UINT(c), io_read_encoding(fptr));
}
else {
SafeStringValue(c);
}
if (NEED_READCONV(fptr)) {
SET_BINARY_MODE(fptr);
len = RSTRING_LEN(c);
#if SIZEOF_LONG > SIZEOF_INT
if (len > INT_MAX)
rb_raise(rb_eIOError, "ungetc failed");
#endif
make_readconv(fptr, (int)len);
if (fptr->cbuf.capa - fptr->cbuf.len < len)
rb_raise(rb_eIOError, "ungetc failed");
if (fptr->cbuf.off < len) {
MEMMOVE(fptr->cbuf.ptr+fptr->cbuf.capa-fptr->cbuf.len,
fptr->cbuf.ptr+fptr->cbuf.off,
char, fptr->cbuf.len);
fptr->cbuf.off = fptr->cbuf.capa-fptr->cbuf.len;
}
fptr->cbuf.off -= (int)len;
fptr->cbuf.len += (int)len;
MEMMOVE(fptr->cbuf.ptr+fptr->cbuf.off, RSTRING_PTR(c), char, len);
}
else {
NEED_NEWLINE_DECORATOR_ON_READ_CHECK(fptr);
io_ungetbyte(c, fptr);
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-wait" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
wait(timeout = nil, mode = :read) → IO, true or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Waits until <a href="IO.html"><code>IO</code></a> is readable or writable without blocking and returns <code>self</code>, or <code>nil</code> when times out. Returns <code>true</code> immediately when buffered data is available. Optional parameter <code>mode</code> is one of <code>:read</code>, <code>:write</code>, or <code>:read_write</code>.</p>
<div class="method-source-code" id="wait-source">
<pre>static VALUE
io_wait_readwrite(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
struct timeval timerec;
struct timeval *tv = NULL;
int event = 0;
int i;
GetOpenFile(io, fptr);
for (i = 0; i < argc; ++i) {
if (SYMBOL_P(argv[i])) {
event |= wait_mode_sym(argv[i]);
}
else {
*(tv = &timerec) = rb_time_interval(argv[i]);
}
}
/* rb_time_interval() and might_mode() might convert the argument */
rb_io_check_closed(fptr);
if (!event) event = RB_WAITFD_IN;
if ((event & RB_WAITFD_IN) && rb_io_read_pending(fptr))
return Qtrue;
if (wait_for_single_fd(fptr, event, tv))
return io;
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-wait_readable" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
wait_readable → IO, true or nil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
wait_readable(timeout) → IO, true or nil
</span>
</div>
<div class="method-description">
<p>Waits until <a href="IO.html"><code>IO</code></a> is readable without blocking and returns <code>self</code>, or <code>nil</code> when times out. Returns <code>true</code> immediately when buffered data is available.</p>
<div class="method-source-code" id="wait_readable-source">
<pre>static VALUE
io_wait_readable(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
struct timeval timerec;
struct timeval *tv;
GetOpenFile(io, fptr);
rb_io_check_readable(fptr);
tv = get_timeout(argc, argv, &timerec);
if (rb_io_read_pending(fptr)) return Qtrue;
if (wait_for_single_fd(fptr, RB_WAITFD_IN, tv)) {
return io;
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-wait_writable" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
wait_writable → IO
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
wait_writable(timeout) → IO or nil
</span>
</div>
<div class="method-description">
<p>Waits until <a href="IO.html"><code>IO</code></a> is writable without blocking and returns <code>self</code> or <code>nil</code> when times out.</p>
<div class="method-source-code" id="wait_writable-source">
<pre>static VALUE
io_wait_writable(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
struct timeval timerec;
struct timeval *tv;
GetOpenFile(io, fptr);
rb_io_check_writable(fptr);
tv = get_timeout(argc, argv, &timerec);
if (wait_for_single_fd(fptr, RB_WAITFD_OUT, tv)) {
return io;
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-winsize" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
winsize → [rows, columns]
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns console size.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="winsize-source">
<pre>static VALUE
console_winsize(VALUE io)
{
rb_io_t *fptr;
int fd;
rb_console_size_t ws;
GetOpenFile(io, fptr);
fd = GetWriteFD(fptr);
if (!getwinsize(fd, &ws)) rb_sys_fail(0);
return rb_assoc_new(INT2NUM(winsize_row(&ws)), INT2NUM(winsize_col(&ws)));
}</pre>
</div>
</div>
</div>
<div id="method-i-winsize-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
winsize = [rows, columns]
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Tries to set console size. The effect depends on the platform and the running environment.</p>
<p>You must require 'io/console' to use this method.</p>
<div class="method-source-code" id="winsize-3D-source">
<pre>static VALUE
console_set_winsize(VALUE io, VALUE size)
{
rb_io_t *fptr;
rb_console_size_t ws;
#if defined _WIN32
HANDLE wh;
int newrow, newcol;
BOOL ret;
#endif
VALUE row, col, xpixel, ypixel;
const VALUE *sz;
int fd;
long sizelen;
GetOpenFile(io, fptr);
size = rb_Array(size);
if ((sizelen = RARRAY_LEN(size)) != 2 && sizelen != 4) {
rb_raise(rb_eArgError,
"wrong number of arguments (given %ld, expected 2 or 4)",
sizelen);
}
sz = RARRAY_CONST_PTR(size);
row = sz[0], col = sz[1], xpixel = ypixel = Qnil;
if (sizelen == 4) xpixel = sz[2], ypixel = sz[3];
fd = GetWriteFD(fptr);
#if defined TIOCSWINSZ
ws.ws_row = ws.ws_col = ws.ws_xpixel = ws.ws_ypixel = 0;
#define SET(m) ws.ws_##m = NIL_P(m) ? 0 : (unsigned short)NUM2UINT(m)
SET(row);
SET(col);
SET(xpixel);
SET(ypixel);
#undef SET
if (!setwinsize(fd, &ws)) rb_sys_fail(0);
#elif defined _WIN32
wh = (HANDLE)rb_w32_get_osfhandle(fd);
#define SET(m) new##m = NIL_P(m) ? 0 : (unsigned short)NUM2UINT(m)
SET(row);
SET(col);
#undef SET
if (!NIL_P(xpixel)) (void)NUM2UINT(xpixel);
if (!NIL_P(ypixel)) (void)NUM2UINT(ypixel);
if (!GetConsoleScreenBufferInfo(wh, &ws)) {
rb_syserr_fail(LAST_ERROR, "GetConsoleScreenBufferInfo");
}
ws.dwSize.X = newcol;
ret = SetConsoleScreenBufferSize(wh, ws.dwSize);
ws.srWindow.Left = 0;
ws.srWindow.Top = 0;
ws.srWindow.Right = newcol-1;
ws.srWindow.Bottom = newrow-1;
if (!SetConsoleWindowInfo(wh, TRUE, &ws.srWindow)) {
rb_syserr_fail(LAST_ERROR, "SetConsoleWindowInfo");
}
/* retry when shrinking buffer after shrunk window */
if (!ret && !SetConsoleScreenBufferSize(wh, ws.dwSize)) {
rb_syserr_fail(LAST_ERROR, "SetConsoleScreenBufferInfo");
}
/* remove scrollbar if possible */
if (!SetConsoleWindowInfo(wh, TRUE, &ws.srWindow)) {
rb_syserr_fail(LAST_ERROR, "SetConsoleWindowInfo");
}
#endif
return io;
}</pre>
</div>
</div>
</div>
<div id="method-i-write" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
write(string, ...) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Writes the given strings to <em>ios</em>. The stream must be opened for writing. Arguments that are not a string will be converted to a string using <code>to_s</code>. Returns the number of bytes written in total.</p>
<pre class="ruby"><span class="ruby-identifier">count</span> = <span class="ruby-identifier">$stdout</span>.<span class="ruby-identifier">write</span>(<span class="ruby-string">"This is"</span>, <span class="ruby-string">" a test\n"</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-node">"That was #{count} bytes of data"</span>
</pre>
<p><em>produces:</em></p>
<pre>This is a test
That was 15 bytes of data</pre>
<div class="method-source-code" id="write-source">
<pre>static VALUE
io_write_m(int argc, VALUE *argv, VALUE io)
{
if (argc != 1) {
return io_writev(argc, argv, io);
}
else {
VALUE str = argv[0];
return io_write(io, str, 0);
}
}</pre>
</div>
</div>
</div>
<div id="method-i-write_nonblock" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
write_nonblock(string) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
write_nonblock(string [, options]) → integer
</span>
</div>
<div class="method-description">
<p>Writes the given string to <em>ios</em> using the write(2) system call after O_NONBLOCK is set for the underlying file descriptor.</p>
<p>It returns the number of bytes written.</p>
<p><a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> just calls the write(2) system call. It causes all errors the write(2) system call causes: Errno::EWOULDBLOCK, Errno::EINTR, etc. The result may also be smaller than string.length (partial write). The caller should care such errors and partial write.</p>
<p>If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>. So <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> can be used to rescue the exceptions for retrying write_nonblock.</p>
<pre class="ruby"><span class="ruby-comment"># Creates a pipe.</span>
<span class="ruby-identifier">r</span>, <span class="ruby-identifier">w</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">pipe</span>
<span class="ruby-comment"># write_nonblock writes only 65536 bytes and return 65536.</span>
<span class="ruby-comment"># (The pipe size is 65536 bytes on this environment.)</span>
<span class="ruby-identifier">s</span> = <span class="ruby-string">"a"</span> <span class="ruby-operator">*</span> <span class="ruby-value">100000</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">w</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-identifier">s</span>) <span class="ruby-comment">#=> 65536</span>
<span class="ruby-comment"># write_nonblock cannot write a byte and raise EWOULDBLOCK (EAGAIN).</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">w</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-string">"b"</span>) <span class="ruby-comment"># Resource temporarily unavailable (Errno::EAGAIN)</span>
</pre>
<p>If the write buffer is not empty, it is flushed at first.</p>
<p>When <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> raises an exception kind of <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a>, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> should not be called until io is writable for avoiding busy loop. This can be done as follows.</p>
<pre class="ruby"><span class="ruby-keyword">begin</span>
<span class="ruby-identifier">result</span> = <span class="ruby-identifier">io</span>.<span class="ruby-identifier">write_nonblock</span>(<span class="ruby-identifier">string</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitWritable</span>, <span class="ruby-constant">Errno</span><span class="ruby-operator">::</span><span class="ruby-constant">EINTR</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>(<span class="ruby-keyword">nil</span>, [<span class="ruby-identifier">io</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
</pre>
<p>Note that this doesn't guarantee to write all data in string. The length written is reported as result and it should be checked later.</p>
<p>On some platforms such as Windows, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> is not supported according to the kind of the <a href="IO.html"><code>IO</code></a> object. In such cases, <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> raises <code>Errno::EBADF</code>.</p>
<p>By specifying a keyword argument <em>exception</em> to <code>false</code>, you can indicate that <a href="IO.html#method-i-write_nonblock"><code>write_nonblock</code></a> should not raise an <a href="IO/WaitWritable.html"><code>IO::WaitWritable</code></a> exception, but return the symbol <code>:wait_writable</code> instead.</p>
<div class="method-source-code" id="write_nonblock-source">
<pre><span class="ruby-comment"># File io.rb, line 120</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">write_nonblock</span>(<span class="ruby-identifier">buf</span>, <span class="ruby-value">exception:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">__builtin_io_write_nonblock</span>(<span class="ruby-identifier">buf</span>, <span class="ruby-identifier">exception</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>