IO

The IO class provides the basic IO feature.

SuperClass:

Object

Included Modules:

Enumerable

Class Methods:

foreach(path[, rs])

Iterates over each line from the IO port specified by path. It works like:

port = open(path)
begin
  port.each_line {
    ...
  }
ensure
  port.close
end

Lines are separated by the value of the optional argument rs, which default value is defined by the variable $/.

new(fd[,mode])

Creates a stream associated with the file descriptor fd.

popen(command [, mode])

Performs the command as a sub-process, and associates pipes to the standard input/output of the sub-process. The mode argument specifies the mode for the opened IO port, which is either "r", "r+", "w", "w+", "a", "a+". If mode omitted, the default is "r"

If the command name is "-", Ruby forks, and create pipe-line to the child process.

pipe

Opens a pair of connected pipes like the corresponding system call, and returns them in the array of two elements (read-side first, write-side next).

readlines(path[, rs])

Reads entire lines from the IO port specified by path and returns an array containing the lines read. It works like:

port = open(path)
begin
  port.each_line {
    ...
  }
ensure
  port.close
end

Lines are separated by the value of the optional argument rs, which default value is defined by the variable $/.

select(reads[, writes[, excepts[, timeout]]])

Calls select(2) system call. Reads, writes, excepts are specified arrays containing instances of the IO class (or its subclass), or nil.

The timeout must be either an integer, Float, Time, or nil. If the timeout is nil, select would not time out.

select returns nil in case of timeout, otherwise returns an array of 3 elements, which are subset of argument arrays.

Methods:

self << object

Output object to the IO port. If object is not a string, it will be converted into the string using to_s. This method returns self, so that the code below works:

$stdout << 1 << " is a " << Fixnum << "\n"

binmode

Changes the stream into binary mode. This is useful only under MSDOS. There's no way to reset to ascii mode except re-opening the stream.

close

Closes the IO port. All operations on the closed IO port will raise an exception. IO ports are automatically closed when they are garbage-collected.

closed?

Returns true if the IO port closed.

each([rs]) {|line|...}

each_line([rs]) {|line|...}

Iterates over each line from the IO port. The IO port must be opened in read-mode. (See open)

Lines are separated by the value of the optional argument rs, which default value is defined by the variable $/.

each_byte {|ch|...}

Reads byte by byte from the IO port. The IO port must be opened in read-mode. (See open)

eof

eof?

Returns true it the stream reaches end of file.

fcntl(cmd, arg)

Performs system call fcntl on the IO object. See fcntl(2) for detail.

If the arg is a number, the numeric value is passed to the system call. If the arg is a string, it is treated as the packed structure. The default arg value is 0.

fileno

to_i

Returns the file descriptor number of the IO port.

flush

Flushes the internal buffer of the IO port.

getc

Reads the next character from the IO port, and returns an fixnum corresponding that character. Returns nil at the end of file.

gets([rs])

Reads a line from the IO port, or nil on end of file. Works mostly same as each, but gets does not iterate.

Lines are separated by the value of the optional argument rs, which default value is defined by the variable $/.

The line read is set to the variable $_.

ioctl(cmd, arg)

Performs system call ioctl on the IO object. See ioctl(2) for detail.

If the arg is a number, the numeric value is passed to the system call. If the arg is a string, it is treated as the packed structure. The default arg value is 0.

isatty

tty?

Returns true if the IO port connected to the tty.

lineno

Returns the current line number of the IO.

lineno= number

Sets the line number of the IO.

pos

Returns the current position of the file pointer.

pos= pos

Moves the file pointer to the pos.

print arg...

Outputs arguments to the IO port.

printf(format, arg...)

Output arguments to the IO port with formatting like printf in C language.

putc(c)

Writes the character c to the stream.

puts(obj...)

Outputs an obj to the IO port, then newline for each arguments.

read [length]

Attempts to read length bytes of data from the IO port. If no length given, reads all data until EOF.

returns nil at EOF.

readchar

Reads a character from the IO port, just like getc, but raises an EOFError exception at the end of file.

readline([rs])

Reads a line from the IO port, just like gets, but raises an EOFError exception at the end of file.

Each lines is separated by the value of the optional argument rs, which default value is defined by the variable $/.

The line read is set to the variable $_ just like IO#gets.

readlines([rs])

Reads entire lines from the IO port and returns an array containing the lines read.

Lines are separated by the value of the optional argument rs, which default value is defined by the variable $/.

reopen(io)

Reconnect self to io. It also changes the class of the stream.

rewind

Resets the position of the file pointer to the beginning of the file.

seek(offset, whence)

Moves the file pointer to the offset. The value for whence are 0 th set the file pointer to offset, 1 to set it to current plus offset, 2 to set it to EOF plus offset.

stat

Returns the status info of the file in the Stat structure, which has attributes as follows:

dev	 	# device number of file-system
ino		# i-node number
mode		# file mode
nlink		# number of hard links
uid		# user ID of owner
gid		# group ID of owner
rdev		# device type (special files only)
size		# total size, in bytes
blksize		# preferred blocksize for file-system I/O
blocks		# number of blocks allocated
atime		# time of last access
mtime		# time of last modification
ctime		# time of last i-node change

For more detail, see stat(2). Some fields are filled with 0, if that field is not supported on your system.

sync

Returns the `sync' mode of the IO port. When the `sync' mode is true, the internal buffer will be flushed, everytime something written to the output port.

sync= newstate

Sets the `sync' mode of the IO port.

sysread(length)

Attempts to read length bytes of data from the IO port, using the system call read(2). It bypasses stdio, so mixing this with other kinds of reads/eof checks may cause confusion.

syswrite(string)

Attempts to write data from the string to the IO port, using the write(2) system call. It bypasses stdio, so mixing this with prints may cause confusion.

tell

Returns the current position of the file pointer.

write(str)

Outputs the string to the IO port. Returns the number of bytes written.

ungetc(c)

Pushes c back to the stream. Only one push-back is guaranteed.

matz@netlab.co.jp