Class: IO

Inherits:
NSObject show all
Includes:
Enumerable, File::Constants

Direct Known Subclasses

File

Defined Under Namespace

Modules: WaitReadable, WaitWritable

Constant Summary

SEEK_SET
SEEK_CUR
SEEK_END

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Enumerable

#_count, #all?, #any?, #collect, #collect_concat, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #find, #find_all, #find_index, #first, #flat_map, #grep, #group_by, #include?, #inject, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #select, #sort, #sort_by, #take, #take_while, #to_a, #zip

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_dup, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, #nil?, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

- (IO) new(fd, mode)

Returns a new IO object (a stream) for the given IO object or integer file descriptor and mode string. See also IO.sysopen and IO.for_fd.

Parameters

fd

numeric file descriptor

mode

file mode. a string or an integer

opt

hash for specifying mode by name.

Mode

When mode is an integer it must be combination of the modes defined in File::Constants.

When mode is a string it must be in one of the following forms:

  • "fmode",

  • "fmode:extern",

  • "fmode:extern:intern".

extern is the external encoding name for the IO. intern is the internal encoding. fmode must be combination of the directives. See the description of class IO for a description of the directives.

When the mode of original IO is read only, the mode cannot be changed to be writable. Similarly, the mode cannot be changed from write only to readable. If such a wrong change is directed, timing where the error actually occurs is different according to the platform.

Also opt can have same keys in String#encode for controlling conversion between the external encoding and the internal encoding.

Example1

fd = IO.sysopen("/dev/tty", "w")
a = IO.new(fd,"w")
$stderr.puts "Hello"
a.puts "World"

produces:

Hello
World

Returns:

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) alloc

+ (String) binread(name, [length [, offset]])

Opens the file, optionally seeks to the given offset, then returns length bytes (defaulting to the rest of the file). binread ensures the file is closed before returning. The open mode would be "rb:ASCII-8BIT".

IO.binread("testfile")           #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
IO.binread("testfile", 20)       #=> "This is line one\nThi"
IO.binread("testfile", 20, 10)   #=> "ne one\nThis is line "

Returns:

+ (Object) copy_stream(src, dst) + (Object) copy_stream(src, dst, copy_length) + (Object) copy_stream(src, dst, copy_length, src_offset)

IO.copy_stream copies src to dst. src and dst is either a filename or an IO.

This method returns the number of bytes copied.

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 IO. The end position of the copy is the end of file.

If copy_length is given, No more than copy_length bytes are copied.

If src_offset is given, it specifies the start position of the copy.

When src_offset is specified and src is an IO, IO.copy_stream doesn't move the current file offset.

+ (IO) for_fd(fd, mode)

Synonym for IO.new.

Returns:

+ (nil) foreach(name, sep = $/[, open_args]) {|line| ... } + (nil) foreach(name, limit[, open_args]) {|line| ... } + (nil) foreach(name, sep, limit[, open_args]) {|line| ... } + (Enumerator) foreach(...)

Executes the block for every line in the named I/O port, where lines are separated by sep.

If no block is given, an enumerator is returned instead.

IO.foreach("testfile") {|x| print "GOT ", x }

produces:

GOT This is line one
GOT This is line two
GOT This is line three
GOT And so on...

If the last argument is a hash, it's the keyword argument to open. See IO.read for detail.

Overloads:

  • + foreach {|line| ... }

    Yields:

    • (line)

    Returns:

    • (nil)
  • + foreach {|line| ... }

    Yields:

    • (line)

    Returns:

    • (nil)
  • + foreach {|line| ... }

    Yields:

    • (line)

    Returns:

    • (nil)
  • + foreach

    Returns:

+ (IO) for_fd(fd, mode)

Synonym for IO.new.

Returns:

+ (Object) open

call-seq:

IO.open(fd, mode_string="r" )               -> io
IO.open(fd, mode_string="r" ) {|io| block } -> obj

With no associated block, open is a synonym for IO.new. If the optional code block is given, it will be passed io as an argument, and the IO object will automatically be closed when the block terminates. In this instance, IO.open returns the value of the block.

+ (Array) pipe + (Array) pipe(ext_enc) + (Array) pipe("ext_enc:int_enc"[, opt]) + (Array) pipe(ext_enc, int_enc[, opt])

IO.pipe(...) {|read_io, write_io| ... }

Creates a pair of pipe endpoints (connected to each other) and returns them as a two-element array of IO objects: [ read_io, write_io ].

If a block is given, the block is called and returns the value of the block. read_io and write_io 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.

Not available on all platforms.

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.

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 rd.read will never return if it does not first issue a wr.close.

rd, wr = IO.pipe

if fork
  wr.close
  puts "Parent got: <#{rd.read}>"
  rd.close
  Process.wait
else
  rd.close
  puts "Sending message to parent"
  wr.write "Hi Dad"
  wr.close
end

produces:

Sending message to parent
Parent got: <Hi Dad>

Overloads:

+ (IO) popen(cmd, mode = "r") + (Object) popen(cmd, mode = "r") {|io| ... }

Runs the specified command as a subprocess; the subprocess's standard input and output will be connected to the returned IO object. If cmd is a String "-", then a new instance of Ruby is started as the subprocess. If cmd is an Array of String, then it will be used as the subprocess's argv bypassing a shell. The array can contains a hash at first for environments and a hash at last for options similar to spawn. The default mode for the new file object is "r", but mode may be set to any of the modes listed in the description for class IO.

Raises exceptions which IO.pipe and Kernel.spawn raise.

If a block is given, Ruby will run the command as a child connected to Ruby with a pipe. Ruby's end of the pipe will be passed as a parameter to the block. At the end of block, Ruby close the pipe and sets $?. In this case IO.popen returns the value of the block.

If a block is given with a cmd of "-", 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 nil, and the child's standard in and standard out will be connected to the parent through the pipe. Not available on all platforms.

f = IO.popen("uname")
p f.readlines
f.close
puts "Parent is #{Process.pid}"
IO.popen("date") { |f| puts f.gets }
IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
p $?
IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
  f.puts "bar"; f.close_write; puts f.gets
}

produces:

["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;

Overloads:

  • + popen

    Returns:

  • + popen {|io| ... }

    Yields:

    • (io)

    Returns:

+ (String) read(name, [length [, offset]]) + (String) read(name, [length [, offset]], open_args)

Opens the file, optionally seeks to the given offset, then returns length bytes (defaulting to the rest of the file). read ensures the file is closed before returning.

If the last argument is a hash, it specifies option for internal open(). The key would be the following. open_args: is exclusive to others.

encoding: string or encoding

 specifies encoding of the read string.  encoding will be ignored
 if length is specified.

mode: string

 specifies mode argument for open().  it should start with "r"
 otherwise it would cause error.

open_args: array of strings

 specifies arguments for open() as an array.

  IO.read("testfile")           #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
  IO.read("testfile", 20)       #=> "This is line one\nThi"
  IO.read("testfile", 20, 10)   #=> "ne one\nThis is line "

Overloads:

+ (Array) readlines(name, sep = $/) + (Array) readlines(name, limit) + (Array) readlines(name, sep, limit)

Reads the entire file specified by name as individual lines, and returns those lines in an array. Lines are separated by sep.

a = IO.readlines("testfile")
a[0]   #=> "This is line one\n"

If the last argument is a hash, it's the keyword argument to open. See IO.read for detail.

Overloads:

  • + readlines

    Returns:

  • + readlines

    Returns:

  • + readlines

    Returns:

+ (Object) select(read_array)

[, error_array

[, timeout]]] )-> array  or  nil

See Kernel#select.

+ (Fixnum) sysopen(path, [mode, [perm]])

Opens the given path, returning the underlying file descriptor as a Fixnum.

IO.sysopen("testfile")   #=> 3

Returns:

+ (IO?) try_convert(obj)

Try to convert obj into an IO, using to_io method. Returns converted IO or nil if obj cannot be converted for any reason.

IO.try_convert(STDOUT)     #=> STDOUT
IO.try_convert("STDOUT")   #=> nil

require 'zlib'
f = open("/tmp/zz.gz")       #=> #<File:/tmp/zz.gz>
z = Zlib::GzipReader.open(f) #=> #<Zlib::GzipReader:0x81d8744>
IO.try_convert(z)            #=> #<File:/tmp/zz.gz>

Returns:

  • (IO, nil)

Instance Method Details

- (IO) <<(obj)

String Output---Writes obj to ios. obj will be converted to a string using to_s.

$stdout << "Hello " << "world!\n"

produces:

Hello world!

Returns:

- (IO) binmode

Puts ios into binary mode. Once a stream is in binary mode, it cannot be reset to nonbinary mode.

  • newline conversion disabled

  • encoding conversion disabled

  • content is treated as ASCII-8BIT

Returns:

- (Boolean) binmode?

Returns true if ios is binmode.

Returns:

  • (Boolean)

Returns:

  • (Boolean)

- (IO) bytes {|byte| ... } - (Enumerator) bytes

ios.each_byte {|byte| block } -> ios

ios.each_byte                  -> an_enumerator

Calls the given block once for each byte (0..255) in ios, passing the byte as an argument. The stream must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
checksum = 0
f.each_byte {|x| checksum ^= x }   #=> #<File:testfile>
checksum                           #=> 12

Overloads:

  • - bytes {|byte| ... }

    Yields:

    • (byte)

    Returns:

  • - bytes

    Returns:

- (IO) chars {|c| ... } - (Enumerator) chars

ios.each_char {|c| block } -> ios

ios.each_char               -> an_enumerator

Calls the given block once for each character in ios, passing the character as an argument. The stream must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
f.each_char {|c| print c, ' ' }   #=> #<File:testfile>

Overloads:

  • - chars {|c| ... }

    Yields:

    • (c)

    Returns:

  • - chars

    Returns:

- (nil) close

Closes ios and flushes any pending writes to the operating system. The stream is unavailable for any further data operations; an IOError is raised if such an attempt is made. I/O streams are automatically closed when they are claimed by the garbage collector.

If ios is opened by IO.popen, close sets $?.

Returns:

  • (nil)

- (Boolean) close_on_exec=(bool)

Sets a close-on-exec flag.

f = open("/dev/null")
f.close_on_exec = true
system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
f.closed?                #=> false

Returns:

  • (Boolean)

- (Boolean) close_on_exec?

Returns true if ios will be closed on exec.

f = open("/dev/null")
f.close_on_exec?                 #=> false
f.close_on_exec = true
f.close_on_exec?                 #=> true
f.close_on_exec = false
f.close_on_exec?                 #=> false

Returns:

  • (Boolean)

Returns:

  • (Boolean)

- (nil) close_read

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 IOError if the stream is not duplexed.

f = IO.popen("/bin/sh","r+")
f.close_read
f.readlines

produces:

prog.rb:3:in `readlines': not opened for reading (IOError)
  from prog.rb:3

Returns:

  • (nil)

- (nil) close_write

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 IOError if the stream is not duplexed.

f = IO.popen("/bin/sh","r+")
f.close_write
f.print "nowhere"

produces:

prog.rb:3:in `write': not opened for writing (IOError)
  from prog.rb:3:in `print'
  from prog.rb:3

Returns:

  • (nil)

- (Boolean) closed?

Returns true if ios is completely closed (for duplex streams, both reader and writer), false otherwise.

f = File.new("testfile")
f.close         #=> nil
f.closed?       #=> true
f = IO.popen("/bin/sh","r+")
f.close_write   #=> nil
f.closed?       #=> false
f.close_read    #=> nil
f.closed?       #=> true

Returns:

  • (Boolean)

Returns:

  • (Boolean)

- (IO) each(sep = $/) {|line| ... } - (IO) each(limit) {|line| ... } - (IO) each(sep, limit) {|line| ... } - (Enumerator) each(...)

ios.each_line(sep=$/) {|line| block } -> ios

ios.each_line(limit) {|line| block }     -> ios
ios.each_line(sep,limit) {|line| block } -> ios
ios.each_line(...)                       -> an_enumerator

ios.lines(sep=$/) {|line| block }        -> ios
ios.lines(limit) {|line| block }         -> ios
ios.lines(sep,limit) {|line| block }     -> ios
ios.lines(...)                           -> an_enumerator

Executes the block for every line in ios, where lines are separated by sep. ios must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
f.each {|line| puts "#{f.lineno}: #{line}" }

produces:

1: This is line one
2: This is line two
3: This is line three
4: And so on...

Overloads:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each

    Returns:

- (IO) bytes {|byte| ... } - (Enumerator) bytes

ios.each_byte {|byte| block } -> ios

ios.each_byte                  -> an_enumerator

Calls the given block once for each byte (0..255) in ios, passing the byte as an argument. The stream must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
checksum = 0
f.each_byte {|x| checksum ^= x }   #=> #<File:testfile>
checksum                           #=> 12

Overloads:

  • - bytes {|byte| ... }

    Yields:

    • (byte)

    Returns:

  • - bytes

    Returns:

- (IO) chars {|c| ... } - (Enumerator) chars

ios.each_char {|c| block } -> ios

ios.each_char               -> an_enumerator

Calls the given block once for each character in ios, passing the character as an argument. The stream must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
f.each_char {|c| print c, ' ' }   #=> #<File:testfile>

Overloads:

  • - chars {|c| ... }

    Yields:

    • (c)

    Returns:

  • - chars

    Returns:

- (IO) each(sep = $/) {|line| ... } - (IO) each(limit) {|line| ... } - (IO) each(sep, limit) {|line| ... } - (Enumerator) each(...)

ios.each_line(sep=$/) {|line| block } -> ios

ios.each_line(limit) {|line| block }     -> ios
ios.each_line(sep,limit) {|line| block } -> ios
ios.each_line(...)                       -> an_enumerator

ios.lines(sep=$/) {|line| block }        -> ios
ios.lines(limit) {|line| block }         -> ios
ios.lines(sep,limit) {|line| block }     -> ios
ios.lines(...)                           -> an_enumerator

Executes the block for every line in ios, where lines are separated by sep. ios must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
f.each {|line| puts "#{f.lineno}: #{line}" }

produces:

1: This is line one
2: This is line two
3: This is line three
4: And so on...

Overloads:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each

    Returns:

- (Boolean) eof - (Boolean) eof?

Returns true if ios is at end of file that means there are no more data to read. The stream must be opened for reading or an IOError will be raised.

f = File.new("testfile")
dummy = f.readlines
f.eof   #=> true

If ios is a stream such as pipe or socket, IO#eof? blocks until the other end sends some data or closes it.

r, w = IO.pipe
Thread.new { sleep 1; w.close }
r.eof?  #=> true after 1 second blocking

r, w = IO.pipe
Thread.new { sleep 1; w.puts "a" }
r.eof?  #=> false after 1 second blocking

r, w = IO.pipe
r.eof?  # blocks forever

Note that IO#eof? reads data to the input byte buffer. So IO#sysread may not behave as you intend with IO#eof?, unless you call IO#rewind first (which is not available for some streams).

Overloads:

  • - eof

    Returns:

    • (Boolean)
  • - eof?

    Returns:

    • (Boolean)

- (Boolean) eof - (Boolean) eof?

Returns true if ios is at end of file that means there are no more data to read. The stream must be opened for reading or an IOError will be raised.

f = File.new("testfile")
dummy = f.readlines
f.eof   #=> true

If ios is a stream such as pipe or socket, IO#eof? blocks until the other end sends some data or closes it.

r, w = IO.pipe
Thread.new { sleep 1; w.close }
r.eof?  #=> true after 1 second blocking

r, w = IO.pipe
Thread.new { sleep 1; w.puts "a" }
r.eof?  #=> false after 1 second blocking

r, w = IO.pipe
r.eof?  # blocks forever

Note that IO#eof? reads data to the input byte buffer. So IO#sysread may not behave as you intend with IO#eof?, unless you call IO#rewind first (which is not available for some streams).

Overloads:

  • - eof

    Returns:

    • (Boolean)
  • - eof?

    Returns:

    • (Boolean)

Returns:

  • (Boolean)

- (Encoding) external_encoding

Returns the Encoding object that represents the encoding of the file. If io is write mode and no encoding is specified, returns nil.

Returns:

- (Integer) fcntl(integer_cmd, arg)

Provides a mechanism for issuing low-level commands to control or query file-oriented I/O streams. Arguments and results are platform dependent. If arg is a number, its value is passed directly. If it is a string, it is interpreted as a binary sequence of bytes (Array#pack might be a useful way to build this string). On Unix platforms, see fcntl(2) for details. Not implemented on all platforms.

Returns:

- (Fixnum) fileno - (Fixnum) to_i Also known as: to_i

Returns an integer representing the numeric file descriptor for ios.

$stdin.fileno    #=> 0
$stdout.fileno   #=> 1

Overloads:

- (IO) flush

Flushes any buffered data within ios to the underlying operating system (note that this is Ruby internal buffering only; the OS may buffer the data as well).

$stdout.print "no newline"
$stdout.flush

produces:

no newline

Returns:

- (0?) fsync

Immediately writes all buffered data in ios to disk. Note that fsync differs from using IO#sync=. The latter ensures that data is flushed from Ruby's buffers, but doesn't not guarantee that the underlying operating system actually writes it to disk.

NotImplementedError is raised if the underlying operating system does not support fsync(2).

Returns:

  • (0, nil)

- (Fixnum?) getbyte

Gets the next 8-bit byte (0..255) from ios. Returns nil if called at end of file.

f = File.new("testfile")
f.getbyte   #=> 84
f.getbyte   #=> 104

Returns:

- (String?) getc

Reads a one-character string from ios. Returns nil if called at end of file.

f = File.new("testfile")
f.getc   #=> "h"
f.getc   #=> "e"

Returns:

- (String?) gets(sep = $/) - (String?) gets(limit) - (String?) gets(sep, limit)

Reads the next "line" from the I/O stream; lines are separated by sep. A separator of nil 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 IOError will be raised. The line read in will be returned and also assigned to $_. Returns nil 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.

File.new("testfile").gets   #=> "This is line one\n"
$_                          #=> "This is line one\n"

Overloads:

  • - gets

    Returns:

  • - gets

    Returns:

  • - gets

    Returns:

- (Object) initialize_copy

:nodoc:

- (String) inspect

Return a string describing this IO object.

Returns:

- (Encoding) internal_encoding

Returns the Encoding of the internal string if conversion is specified. Otherwise returns nil.

Returns:

- (Integer) ioctl(integer_cmd, arg)

Provides a mechanism for issuing low-level commands to control or query I/O devices. Arguments and results are platform dependent. If arg 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 ioctl(2) for details. Not implemented on all platforms.

Returns:

- (Boolean) isatty - (Boolean) tty?

Returns true if ios is associated with a terminal device (tty), false otherwise.

File.new("testfile").isatty   #=> false
File.new("/dev/tty").isatty   #=> true

Overloads:

  • - isatty

    Returns:

    • (Boolean)
  • - tty?

    Returns:

    • (Boolean)

- (Integer) lineno

Returns the current line number in ios. The stream must be opened for reading. lineno counts the number of times gets is called, rather than the number of newlines encountered. The two values will differ if gets is called with a separator other than newline. See also the $. variable.

f = File.new("testfile")
f.lineno   #=> 0
f.gets     #=> "This is line one\n"
f.lineno   #=> 1
f.gets     #=> "This is line two\n"
f.lineno   #=> 2

Returns:

- (Integer) lineno=(integer)

Manually sets the current line number to the given value. $. is updated only on the next read.

f = File.new("testfile")
f.gets                     #=> "This is line one\n"
$.                         #=> 1
f.lineno = 1000
f.lineno                   #=> 1000
$.                         #=> 1         # lineno of last read
f.gets                     #=> "This is line two\n"
$.                         #=> 1001      # lineno of last read

Returns:

- (IO) each(sep = $/) {|line| ... } - (IO) each(limit) {|line| ... } - (IO) each(sep, limit) {|line| ... } - (Enumerator) each(...)

ios.each_line(sep=$/) {|line| block } -> ios

ios.each_line(limit) {|line| block }     -> ios
ios.each_line(sep,limit) {|line| block } -> ios
ios.each_line(...)                       -> an_enumerator

ios.lines(sep=$/) {|line| block }        -> ios
ios.lines(limit) {|line| block }         -> ios
ios.lines(sep,limit) {|line| block }     -> ios
ios.lines(...)                           -> an_enumerator

Executes the block for every line in ios, where lines are separated by sep. ios must be opened for reading or an IOError will be raised.

If no block is given, an enumerator is returned instead.

f = File.new("testfile")
f.each {|line| puts "#{f.lineno}: #{line}" }

produces:

1: This is line one
2: This is line two
3: This is line three
4: And so on...

Overloads:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each {|line| ... }

    Yields:

    • (line)

    Returns:

  • - each

    Returns:

- (Fixnum) pid

Returns the process ID of a child process associated with ios. This will be set by IO.popen.

pipe = IO.popen("-")
if pipe
  $stderr.puts "In parent, child pid is #{pipe.pid}"
else
  $stderr.puts "In child, pid is #{$$}"
end

produces:

In child, pid is 26209
In parent, child pid is 26209

Returns:

- (Integer) pos - (Integer) tell

Returns the current offset (in bytes) of ios.

f = File.new("testfile")
f.pos    #=> 0
f.gets   #=> "This is line one\n"
f.pos    #=> 17

Overloads:

- (Integer) pos=(integer)

Seeks to the given position (in bytes) in ios.

f = File.new("testfile")
f.pos = 17
f.gets   #=> "This is line two\n"

Returns:

- (nil) print - (nil) print(obj, ...)

Writes the given object(s) to ios. The stream must be opened for writing. If the output field separator ($,) is not nil, it will be inserted between each object. If the output record separator ($\) is not nil, it will be appended to the output. If no arguments are given, prints $_. Objects that aren't strings will be converted by calling their to_s method. With no argument, prints the contents of the variable $_. Returns nil.

$stdout.print("This is ", 100, " percent.\n")

produces:

This is 100 percent.

Overloads:

  • - print

    Returns:

    • (nil)
  • - print

    Returns:

    • (nil)

- (nil) printf(format_string[, obj, ...])

Formats and writes to ios, converting parameters under control of the format string. See Kernel#sprintf for details.

Returns:

  • (nil)

- (Object) putc(obj)

If obj is Numeric, write the character whose code is the least-significant byte of obj, otherwise write the first byte of the string representation of obj to ios. Note: This method is not safe for use with multi-byte characters as it will truncate them.

$stdout.putc "A"
$stdout.putc 65

produces:

AA

Returns:

- (nil) puts(obj, ...)

Writes the given objects to ios as with IO#print. Writes a record separator (typically a newline) after any that do not already end with a newline sequence. If called with an array argument, writes each element on a new line. If called without arguments, outputs a single record separator.

$stdout.puts("this", "is", "a", "test")

produces:

this
is
a
test

Returns:

  • (nil)

- (String?) read([length [, buffer]])

Reads length bytes from the I/O stream.

length must be a non-negative integer or nil.

If length is a positive integer, it try to read length bytes without any conversion (binary mode). It returns nil or a string whose length is 1 to length bytes. nil means it met EOF at beginning. The 1 to length-1 bytes string means it met EOF after reading the result. The length bytes string means it doesn't meet EOF. The resulted string is always ASCII-8BIT encoding.

If length is omitted or is nil, it reads until EOF and the encoding conversion is applied. It returns a string even if EOF is met at beginning.

If length is zero, it returns "".

If the optional buffer argument is present, it must reference a String, which will receive the data.

At end of file, it returns nil or "" depend on length. ios.read() and ios.read(nil) returns "". ios.read(positive-integer) returns nil.

f = File.new("testfile")
f.read(16)   #=> "This is line one"

# reads whole file
open("file") {|f|
  data = f.read # This returns a string even if the file is empty.
  ...
}

# iterate over fixed length records.
open("fixed-record-file") {|f|
  while record = f.read(256)
    ...
  end
}

# iterate over variable length records.
# record is prefixed by 32-bit length.
open("variable-record-file") {|f|
  while len = f.read(4)
    len = len.unpack("N")[0] # 32-bit length
    record = f.read(len) # This returns a string even if len is 0.
  end
}

Note that this method behaves like fread() function in C. If you need the behavior like read(2) system call, consider readpartial, read_nonblock and sysread.

Returns:

- (String) read_nonblock(maxlen) - (Object) read_nonblock(maxlen, outbuf)

Reads at most maxlen bytes from ios using the read(2) system call after O_NONBLOCK is set for the underlying file descriptor.

If the optional outbuf argument is present, it must reference a String, which will receive the data.

read_nonblock 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.

If the exception is Errno::EWOULDBLOCK or Errno::AGAIN, it is extended by IO::WaitReadable. So IO::WaitReadable can be used to rescue the exceptions for retrying read_nonblock.

read_nonblock causes EOFError on EOF.

If the read byte buffer is not empty, read_nonblock reads from the buffer like readpartial. In this case, the read(2) system call is not called.

When read_nonblock raises an exception kind of IO::WaitReadable, read_nonblock should not be called until io is readable for avoiding busy loop. This can be done as follows.

# emulates blocking read (readpartial).
begin
  result = io.read_nonblock(maxlen)
rescue IO::WaitReadable
  IO.select([io])
  retry
end

Although IO#read_nonblock doesn't raise IO::WaitWritable. OpenSSL::Buffering#read_nonblock can raise IO::WaitWritable. If IO and SSL should be used polymorphically, IO::WaitWritable should be rescued too. See the document of OpenSSL::Buffering#read_nonblock for sample code.

Note that this method is identical to readpartial except the non-blocking flag is set.

Overloads:

  • - read_nonblock

    Returns:

- (Fixnum) readbyte

Reads a byte as with IO#getbyte, but raises an EOFError on end of file.

Returns:

- (String) readchar

Reads a one-character string from ios. Raises an EOFError on end of file.

f = File.new("testfile")
f.readchar   #=> "h"
f.readchar   #=> "e"

Returns:

- (String) readline(sep = $/) - (String) readline(limit) - (String) readline(sep, limit)

Reads a line as with IO#gets, but raises an EOFError on end of file.

Overloads:

- (Array) readlines(sep = $/) - (Array) readlines(limit) - (Array) readlines(sep, limit)

Reads all of the lines in ios, and returns them in anArray. Lines are separated by the optional sep. If sep is nil, the rest of the stream is returned as a single record. 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. The stream must be opened for reading or an IOError will be raised.

f = File.new("testfile")
f.readlines[0]   #=> "This is line one\n"

Overloads:

  • - readlines

    Returns:

  • - readlines

    Returns:

  • - readlines

    Returns:

- (String) readpartial(maxlen) - (Object) readpartial(maxlen, outbuf)

Reads at most maxlen bytes from the I/O stream. It blocks only if ios has no data immediately available. It doesn't block if some data available. If the optional outbuf argument is present, it must reference a String, which will receive the data. It raises EOFError on end of file.

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.

  • the byte buffer in the IO object is empty.

  • the content of the stream is empty.

  • the stream is not reached to EOF.

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 EOFError.

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 EOFError.

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc".
r.readpartial(4096)      #=> "abc"       ""              ""
r.readpartial(4096)      # blocks because buffer and pipe is empty.

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc"
w.close                  #               ""              "abc" EOF
r.readpartial(4096)      #=> "abc"       ""              EOF
r.readpartial(4096)      # raises EOFError

r, w = IO.pipe           #               buffer          pipe content
w << "abc\ndef\n"        #               ""              "abc\ndef\n"
r.gets                   #=> "abc\n"     "def\n"         ""
w << "ghi\n"             #               "def\n"         "ghi\n"
r.readpartial(4096)      #=> "def\n"     ""              "ghi\n"
r.readpartial(4096)      #=> "ghi\n"     ""              ""

Note that readpartial behaves similar to sysread. The differences are:

  • If the byte buffer is not empty, read from the byte buffer instead of "sysread for buffered IO (IOError)".

  • It doesn't cause Errno::EWOULDBLOCK and Errno::EINTR. When readpartial meets EWOULDBLOCK and EINTR by read system call, readpartial retry the system call.

The later means that readpartial is nonblocking-flag insensitive. It blocks on the situation IO#sysread causes Errno::EWOULDBLOCK as if the fd is blocking mode.

Overloads:

  • - readpartial

    Returns:

- (IO) reopen(other_IO) - (IO) reopen(path, mode_str)

Reassociates ios with the I/O stream given in other_IO or to a new stream opened on path. This may dynamically change the actual class of this stream.

f1 = File.new("testfile")
f2 = File.new("testfile")
f2.readlines[0]   #=> "This is line one\n"
f2.reopen(f1)     #=> #<File:testfile>
f2.readlines[0]   #=> "This is line one\n"

Overloads:

  • - reopen

    Returns:

  • - reopen

    Returns:

- (0) rewind

Positions ios to the beginning of input, resetting lineno to zero.

f = File.new("testfile")
f.readline   #=> "This is line one\n"
f.rewind     #=> 0
f.lineno     #=> 0
f.readline   #=> "This is line one\n"

Note that it cannot be used with streams such as pipes, ttys, and sockets.

Returns:

  • (0)

- (0) seek(amount, whence = IO::SEEK_SET)

Seeks to a given offset anInteger in the stream according to the value of whence:

IO::SEEK_CUR  | Seeks to _amount_ plus current position
--------------+----------------------------------------------------
IO::SEEK_END  | Seeks to _amount_ plus end of stream (you probably
              | want a negative value for _amount_)
--------------+----------------------------------------------------
IO::SEEK_SET  | Seeks to the absolute location given by _amount_

Example:

f = File.new("testfile")
f.seek(-13, IO::SEEK_END)   #=> 0
f.readline                  #=> "And so on...\n"

Returns:

  • (0)

- (IO) set_encoding(ext_enc) - (IO) set_encoding("ext_enc:int_enc") - (IO) set_encoding(ext_enc, int_enc) - (IO) set_encoding("ext_enc:int_enc", opt) - (IO) set_encoding(ext_enc, int_enc, opt)

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.

Overloads:

  • - set_encoding

    Returns:

  • - set_encoding

    Returns:

  • - set_encoding

    Returns:

  • - set_encoding

    Returns:

  • - set_encoding

    Returns:

- (File::Stat) stat

Returns status information for ios as an object of type File::Stat.

f = File.new("testfile")
s = f.stat
"%o" % s.mode   #=> "100644"
s.blksize       #=> 4096
s.atime         #=> Wed Apr 09 08:53:54 CDT 2003

Returns:

- (Boolean) sync

Returns the current "sync mode" of ios. When sync mode is true, all output is immediately flushed to the underlying operating system and is not buffered by Ruby internally. See also IO#fsync.

f = File.new("testfile")
f.sync   #=> false

Returns:

  • (Boolean)

- (Boolean) sync=(boolean)

Sets the "sync mode" to true or false. 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 IO#fsync.

f = File.new("testfile")
f.sync = true

(produces no output)

Returns:

  • (Boolean)

- (String) sysread(integer[, outbuf])

Reads integer bytes from ios using a low-level read and returns them as a string. Do not mix with other methods that read from ios or you may get unpredictable results. If the optional outbuf argument is present, it must reference a String, which will receive the data. Raises SystemCallError on error and EOFError at end of file.

f = File.new("testfile")
f.sysread(16)   #=> "This is line one"

Returns:

- (0) seek(amount, whence = IO::SEEK_SET)

Seeks to a given offset anInteger in the stream according to the value of whence:

IO::SEEK_CUR  | Seeks to _amount_ plus current position
--------------+----------------------------------------------------
IO::SEEK_END  | Seeks to _amount_ plus end of stream (you probably
              | want a negative value for _amount_)
--------------+----------------------------------------------------
IO::SEEK_SET  | Seeks to the absolute location given by _amount_

Example:

f = File.new("testfile")
f.seek(-13, IO::SEEK_END)   #=> 0
f.readline                  #=> "And so on...\n"

Returns:

  • (0)

- (Integer) syswrite(string)

Writes the given string to ios using a low-level write. Returns the number of bytes written. Do not mix with other methods that write to ios or you may get unpredictable results. Raises SystemCallError on error.

f = File.new("out", "w")
f.syswrite("ABCDEF")   #=> 6

Returns:

- (Integer) pos - (Integer) tell

Returns the current offset (in bytes) of ios.

f = File.new("testfile")
f.pos    #=> 0
f.gets   #=> "This is line one\n"
f.pos    #=> 17

Overloads:

- (IO) to_io

Returns ios.

Returns:

- (Boolean) isatty - (Boolean) tty?

Returns true if ios is associated with a terminal device (tty), false otherwise.

File.new("testfile").isatty   #=> false
File.new("/dev/tty").isatty   #=> true

Overloads:

  • - isatty

    Returns:

    • (Boolean)
  • - tty?

    Returns:

    • (Boolean)

Returns:

  • (Boolean)

- (nil) ungetbyte(string) - (nil) ungetbyte(integer)

Pushes back bytes (passed as a parameter) onto ios, 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 IO#sysread).

f = File.new("testfile")   #=> #<File:testfile>
b = f.getbyte              #=> 0x38
f.ungetbyte(b)             #=> nil
f.getbyte                  #=> 0x38

Overloads:

  • - ungetbyte

    Returns:

    • (nil)
  • - ungetbyte

    Returns:

    • (nil)

- (nil) ungetc(string)

Pushes back one character (passed as a parameter) onto ios, 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 IO#sysread).

f = File.new("testfile")   #=> #<File:testfile>
c = f.getc                 #=> "8"
f.ungetc(c)                #=> nil
f.getc                     #=> "8"

Returns:

  • (nil)

- (Integer) write(string)

Writes the given string to ios. The stream must be opened for writing. If the argument is not a string, it will be converted to a string using to_s. Returns the number of bytes written.

count = $stdout.write("This is a test\n")
puts "That was #{count} bytes of data"

produces:

This is a test
That was 15 bytes of data

Returns:

- (Integer) write_nonblock(string)

Writes the given string to ios using the write(2) system call after O_NONBLOCK is set for the underlying file descriptor.

It returns the number of bytes written.

write_nonblock 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.

If the exception is Errno::EWOULDBLOCK or Errno::AGAIN, it is extended by IO::WaitWritable. So IO::WaitWritable can be used to rescue the exceptions for retrying write_nonblock.

# Creates a pipe.
r, w = IO.pipe

# write_nonblock writes only 65536 bytes and return 65536.
# (The pipe size is 65536 bytes on this environment.)
s = "a" * 100000
p w.write_nonblock(s)     #=> 65536

# write_nonblock cannot write a byte and raise EWOULDBLOCK (EAGAIN).
p w.write_nonblock("b")   # Resource temporarily unavailable (Errno::EAGAIN)

If the write buffer is not empty, it is flushed at first.

When write_nonblock raises an exception kind of IO::WaitWritable, write_nonblock should not be called until io is writable for avoiding busy loop. This can be done as follows.

begin
  result = io.write_nonblock(string)
rescue IO::WaitWritable, Errno::EINTR
  IO.select(nil, [io])
  retry
end

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.

On some platforms such as Windows, write_nonblock is not supported according to the kind of the IO object. In such cases, write_nonblock raises Errno::EBADF.

Returns: