prev - up - next - index

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

prev - up - next - index

matz@netlab.co.jp