Ruby: include/ruby/internal/intern/io.h File Reference

Ruby 3.4.8p72 (2025-12-17 revision 995b59f66677d44767ce9faac6957e5543617ff9)

Macros | Functions | Variables
io.h File Reference

Public APIs related to rb_cIO. More...

`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
Include dependency graph for io.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros
#define | rb_defout rb_stdout
#define | RB_RESERVED_FD_P(fd) rb_reserved_fd_p(fd)
| Just another name of rb_reserved_fd_p.

## Functions
VALUE | rb_io_write (VALUE io, VALUE str)
| Writes the given string to the given IO.
VALUE | rb_io_gets (VALUE io)
| Reads a "line" from the given IO.
VALUE | rb_io_getbyte (VALUE io)
| Reads a byte from the given IO.
VALUE | rb_io_ungetc (VALUE io, VALUE c)
| "Unget"s a string.
VALUE | rb_io_ungetbyte (VALUE io, VALUE b)
| Identical to rb_io_ungetc(), except it doesn't take the encoding of the passed IO into account.
VALUE | rb_io_close (VALUE io)
| Closes the IO.
VALUE | rb_io_flush (VALUE io)
| Flushes any buffered data within the passed IO to the underlying operating system.
VALUE | rb_io_eof (VALUE io)
| Queries if the passed IO is at the end of file.
VALUE | rb_io_binmode (VALUE io)
| Sets the binmode.
VALUE | rb_io_ascii8bit_binmode (VALUE io)
| Forces no conversions be applied to the passed IO.
VALUE | rb_io_addstr (VALUE io, VALUE str)
| Identical to rb_io_write(), except it always returns the passed IO.
VALUE | rb_io_printf (int argc, const VALUE *argv, VALUE io)
| This is a rb_f_sprintf() + rb_io_write() combo.
VALUE | rb_io_print (int argc, const VALUE *argv, VALUE io)
| Iterates over the passed array to apply rb_io_write() individually.
VALUE | rb_io_puts (int argc, const VALUE *argv, VALUE io)
| Iterates over the passed array to apply rb_io_write() individually.
VALUE | rb_io_fdopen (int fd, int flags, const char *path)
| Creates an IO instance whose backend is the given file descriptor.
VALUE | rb_file_open (const char *fname, const char *fmode)
| Opens a file located at the given path.
VALUE | rb_file_open_str (VALUE fname, const char *fmode)
| Identical to rb_file_open(), except it takes the pathname as a Ruby's string instead of C's.
VALUE | rb_gets (void)
| Much like rb_io_gets(), but it reads from the mysterious ARGF object.
void | rb_write_error (const char *str)
| Writes the given error message to somewhere applicable.
void | rb_write_error2 (const char *str, long len)
| Identical to rb_write_error(), except it additionally takes the message's length.
void | rb_close_before_exec (int lowfd, int maxhint, VALUE noclose_fds)
| Closes everything.
int | rb_pipe (int *pipes)
| This is an rb_cloexec_pipe() + rb_update_max_fd() combo.
int | rb_reserved_fd_p (int fd)
| Queries if the given FD is reserved or not.
int | rb_cloexec_open (const char *pathname, int flags, mode_t mode)
| Opens a file that closes on exec.
int | rb_cloexec_dup (int oldfd)
| Identical to rb_cloexec_fcntl_dupfd(), except it implies minfd is 3.
int | rb_cloexec_dup2 (int oldfd, int newfd)
| Identical to rb_cloexec_dup(), except you can specify the destination file descriptor.
int | rb_cloexec_pipe (int fildes[2])
| Opens a pipe with closing on exec.
int | rb_cloexec_fcntl_dupfd (int fd, int minfd)
| Duplicates a file descriptor with closing on exec.
void | rb_update_max_fd (int fd)
| Informs the interpreter that the passed fd can be the max.
void | rb_fd_fix_cloexec (int fd)
| Sets or clears the close-on-exec flag of the passed file descriptor to the desired state.

## Variables
VALUE | rb_fs
| The field separator character for inputs, or the `$;`.
VALUE | rb_output_fs
| The field separator character for outputs, or the `$,`.
VALUE | rb_rs
| The record separator character for inputs, or the `$/`.
VALUE | rb_default_rs
| This is the default value of rb_rs, i.e.
VALUE | rb_output_rs
| The record separator character for outputs, or the `$\`.

## Detailed Description

Public APIs related to rb_cIO.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file io.h.

## Macro Definition Documentation

## ◆ rb_defout

#define rb_defout rb_stdout

Deprecated:
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 37 of file io.h.

## ◆ RB_RESERVED_FD_P

#define RB_RESERVED_FD_P | ( |  | fd | ) | rb_reserved_fd_p(fd)

Just another name of rb_reserved_fd_p.

Definition at line 556 of file io.h.

## Function Documentation

## ◆ rb_cloexec_dup()

int rb_cloexec_dup | ( | int | oldfd | ) |

Identical to rb_cloexec_fcntl_dupfd(), except it implies minfd is 3.

Parameters

  [in] | oldfd | File descriptor to duplicate.

Return values

  -1 | `dup2(2)` failed for some reason.
  otherwise | An allocated new file descriptor.

Note
  This function does not raise.

Definition at line 367 of file io.c.

## ◆ rb_cloexec_dup2()

int rb_cloexec_dup2 | ( | int | oldfd,
|  | int | newfd
| ) |  |

Identical to rb_cloexec_dup(), except you can specify the destination file descriptor.

If the destination is already squatted by another file descriptor that gets silently closed without any warnings. (This is a spec requested by POSIX.)

Parameters

  [in] | oldfd | File descriptor to duplicate.
  [in] | newfd | Return value destination.

Return values

  -1 | `dup2(2)` failed for some reason.
  newfd | An allocated new file descriptor.

Postcondition
  Whatever sat at `newfd` gets closed with no notifications.
  In case return value is -1 `newfd` is untouched.

Note
  This function does not raise.

Definition at line 374 of file io.c.

## ◆ rb_cloexec_fcntl_dupfd()

int rb_cloexec_fcntl_dupfd | ( | int | fd,
|  | int | minfd
| ) |  |

Duplicates a file descriptor with closing on exec.

In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function duplicates a file descriptor as `dup(2)` does, but additionally instructs the operating system that we don't want the duplicated FD be seen from child processes.

Parameters

  [in] | fd | File descriptor to duplicate.
  [in] | minfd | Minimum allowed FD to return.

Return values

  -1 | `dup(2)` failed for some reason.
  otherwise | An allocated new file descriptor.

Note
  This function does not raise.

`minfd` is handy when for instance STDERR is closed but you don't want to use fd 2.

Definition at line 461 of file io.c.

Referenced by rb_cloexec_dup(), and rb_cloexec_fcntl_dupfd().

## ◆ rb_cloexec_open()

int rb_cloexec_open | ( | const char * | pathname,
|  | int | flags,
|  | mode_t | mode
| ) |  |

Opens a file that closes on exec.

In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function opens a file descriptor as `open(2)` does, but additionally instructs the operating system that we don't want it be seen from child processes.

Parameters

  [in] | pathname | File path to open.
  [in] | flags | Open mode, as in `open(2)`.
  [in] | mode | File mode, in case of `O_CREAT`.

Return values

  -1 | `open(2)` failed for some reason.
  otherwise | An allocated new file descriptor.

Note
  This function does not raise.

Definition at line 328 of file io.c.

## ◆ rb_cloexec_pipe()

int rb_cloexec_pipe | ( | int | fildes[2] | ) |

Opens a pipe with closing on exec.

In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function opens a pipe as `pipe(2)` does, but additionally instructs the operating system that we don't want the duplicated FDs be seen from child processes.

Parameters

  [out] | fildes | Return buffer. Must at least hold 2 elements.

Return values

  0 | Successful creation of a pipe.
  -1 | Failure in underlying system call(s).

Postcondition
  `pipes` is filled with file descriptors.
  `errno` is set on failure.

Definition at line 427 of file io.c.

Referenced by rb_pipe().

## ◆ rb_close_before_exec()

void rb_close_before_exec | ( | int | lowfd,
|  | int | maxhint,
|  | VALUE | noclose_fds
| ) |  |

Closes everything.

In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function closes such inherited file descriptors. When your C extension needs to have a child process, don't forget to call this from your child process right before exec.

Parameters

  [in] | lowfd | Lower bound of FDs (you want STDIN to remain, no?).
  [in] | maxhint | Hint of max FDs.
  [in] | noclose_fds | A hash, whose keys are an allowlist.

## ◆ rb_fd_fix_cloexec()

void rb_fd_fix_cloexec | ( | int | fd | ) |

Sets or clears the close-on-exec flag of the passed file descriptor to the desired state.

STDIN, STDOUT, STDERR are the exceptional file descriptors that shall remain open. All others are to be closed on exec. When a C extension library opens a file descriptor using anything other than rb_cloexec_open() etc., that file descriptor shall experience this function.

Parameters

  [in] | fd | An open file descriptor.

Definition at line 298 of file io.c.

## ◆ rb_file_open()

VALUE rb_file_open | ( | const char * | fname,
|  | const char * | fmode
| ) |  |

Opens a file located at the given path.

`fmode` is a C string that represents the open mode. It can be one of:

- `r` (means `O_RDONLY`),
- `w` (means `O_WRONLY | O_TRUNC | O_CREAT`),
- `a` (means `O_WRONLY | O_APPEND | O_CREAT`),

Followed by zero or more combinations of:

- `b` (means `_O_BINARY`),
- `t` (means `_O_TEXT`),
- `+` (means `O_RDWR`),
- `x` (means `O_TRUNC`), or
- `:[BOM|]enc[:enc]` (see below).

This last one specifies external (and internal if any) encodings, respectively. If optional `BOM|` is specified and the specified external encoding is capable of expressing BOMs, opening file's contents' byte order is auto-detected using the mechanism.

So for instance, fmode of `"rt|BOM:utf-16le:utf-8"` specifies that...

- the physical representation of the contents of the file is in UTF-16;
- honours its BOM but assumes little endian if absent;
- opens the file for reading;
- what is read is converted into UTF-8;
- with newlines cannibalised to `\n`.

Parameters

  [in] | fname | Path to open.
  [in] | fmode | Mode specifier much like `fopen(3)`.

Exceptions

  rb_eArgError | `fmode` contradicted (e.g. `"bt"`).
  rb_eSystemCallError | `open(2)` failed for some reason.

Returns
  An instance of rb_cIO.

Definition at line 7275 of file io.c.

## ◆ rb_file_open_str()

VALUE rb_file_open_str | ( | VALUE | fname,
|  | const char * | fmode
| ) |  |

Identical to rb_file_open(), except it takes the pathname as a Ruby's string instead of C's.

In case the passed Ruby object is a non-String it tries to call `#to_path`.

Parameters

  [in] | fname | Path to open.
  [in] | fmode | Mode specifier much like `fopen(3)`.

Exceptions

  rb_eTypeError | `fname` is not a String.
  rb_eEncCompatError | `fname` is not ASCII-compatible.
  rb_eArgError | `fmode` contradicted (e.g. `"bt"`).
  rb_eSystemCallError | `open(2)` failed for some reason.

Returns
  An instance of rb_cIO.

Definition at line 7268 of file io.c.

## ◆ rb_gets()

VALUE rb_gets | ( | void |  | ) |

Much like rb_io_gets(), but it reads from the mysterious ARGF object.

ARGF in this context can be seen as a virtual IO which concatenates contents of the files passed to the process via the ARGV, or just STDIN if there are no such files.

Unlike rb_io_gets() this function sets `$_`.

Exceptions

  rb_eFrozenError | ARGF resorts to STDIN but it is frozen.

Return values

  RUBY_Qnil | ARGF is at EOF.
  otherwise | An instance of rb_cString.

Postcondition
  ARGF is read.
  `$_` is set.

Definition at line 10412 of file io.c.

## ◆ rb_io_addstr()

VALUE rb_io_addstr | ( | VALUE | io,
|  | VALUE | str
| ) |  |

Identical to rb_io_write(), except it always returns the passed IO.

Parameters

  [out] | io | An IO, opened for writing.
  [in] | str | A String-like object to write to `io`.

Exceptions

  rb_eIOError | `io` isn't opened for writing.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `str` to String.
  rb_eSystemCallError | `write(2)` failed.

Returns
  The passed `io`.

Postcondition
  `str` is written to `io`.

Note
  This function blocks.

Definition at line 2350 of file io.c.

## ◆ rb_io_ascii8bit_binmode()

VALUE rb_io_ascii8bit_binmode | ( | VALUE | io | ) |

Forces no conversions be applied to the passed IO.

Unlike rb_io_binmode(), this cancels any newline conversions as well as encoding conversions. Any texts read/written through the IO will be the verbatim binary contents.

Parameters

  [out] | io | Target IO to modify.

Exceptions

  rb_eFrozenError | `io` is frozen.

Returns
  The passed `io`.

Postcondition
  `io` is in binmode. Both external/internal encoding are set to rb_ascii8bit_encoding().

Note
  This is the implementation of `IO#binmode`.

Definition at line 6384 of file io.c.

Referenced by rb_io_ascii8bit_binmode().

## ◆ rb_io_binmode()

VALUE rb_io_binmode | ( | VALUE | io | ) |

Sets the binmode.

This operation nullifies the effect of textmode (newline conversion from `"\r\n"` to `"\n"` or vice versa). Note that it doesn't stop character encodings conversions. For instance an IO created using:

File.open(
"/dev/urandom",
textmode: true,
external_encoding: Encoding::GB18030,
internal_encoding: Encoding::Windows_31J)

has both newline and character conversions. If you pass such IO to this function, only the `textmode:true` part is cancelled. Texts read through the IO would still be encoded in Windows-31J; texts written to the IO will be encoded in GB18030.

Parameters

  [out] | io | Target IO to modify.

Exceptions

  rb_eFrozenError | `io` is frozen.

Returns
  The passed `io`.

Postcondition
  `io` is in binmode.

Note
  There is no equivalent operation in Ruby. You can do this only in C.

Definition at line 6338 of file io.c.

Referenced by rb_io_binmode().

## ◆ rb_io_close()

VALUE rb_io_close | ( | VALUE | io | ) |

Closes the IO.

Any buffered contents are flushed to the operating system. Any future operations against the IO would raise rb_eIOError. In case the io was created using `IO.popen`, it also sets the `$?`.

Parameters

  [out] | io | Target IO to close.

Returns
  Always returns RUBY_Qnil.

Postcondition
  `$?` is set in case IO is a pipe.
  No operations are possible against `io` any further.

Note
  This can block to flush the contents.
  This can wake other threads up, especially those who are `select()`-ing the passed IO.
  Multiple invocations of this function over the same IO again and again is not an error, since Ruby 2.3.

Definition at line 5758 of file io.c.

Referenced by rb_gets().

## ◆ rb_io_eof()

VALUE rb_io_eof | ( | VALUE | io | ) |

Queries if the passed IO is at the end of file.

"The end of file" here mans that there are no more data to read. This function blocks until the read buffer is filled in, and if that operation reached the end of file, it still returns RUBY_Qfalse (because there are data yet in that buffer). It returns RUBY_Qtrue once after the buffer is cleared.

Parameters

  [in,out] | io | Target io to query.

Exceptions

  rb_eIOError | `io` is not opened for reading.
  rb_eFrozenError | `io` is frozen.

Return values

  RUBY_Qfalse | There are things yet to be read.
  RUBY_Qtrue | "The end of file" situation.

Definition at line 2695 of file io.c.

## ◆ rb_io_fdopen()

VALUE rb_io_fdopen | ( | int | fd,
|  | int | flags,
|  | const char * | path
| ) |  |

Creates an IO instance whose backend is the given file descriptor.

C extension libraries sometimes have file descriptors created elsewhere (maybe deep inside of another shared library), which they want ruby programs to handle. This function is handy for such situations.

Parameters

  [in] | fd | Target file descriptor.
  [in] | flags | Flags, e.g. `O_CREAT|O_EXCL`
  [in] | path | The path of the file that backs `fd`, for diagnostics.

Returns
  An allocated instance of rb_cIO with the autoclose flag set.

Note
  Leave `path` NULL if you don't know.

Definition at line 9343 of file io.c.

## ◆ rb_io_flush()

VALUE rb_io_flush | ( | VALUE | io | ) |

Flushes any buffered data within the passed IO to the underlying operating system.

Parameters

  [out] | io | Target IO to flush.

Exceptions

  rb_eIOError | `io` is closed.
  rb_eFrozenError | `io` is frozen.
  rb_eSystemCallError | `write(2)` failed for some reason.

Returns
  The passed `io`.

Postcondition
  `io`'s buffers are empty.

Note
  This operation also discards the read buffer. Should basically be harmless, but in an esoteric situation like when user pushed something different from what was read using `ungetc`, this operation in fact changes the behaviour of the `io`.
  Buffering is difficult. This operation flushes the data from our userspace to the kernel, but that doesn't always mean you can expect them stored persistently onto your hard drive.

Definition at line 2406 of file io.c.

## ◆ rb_io_getbyte()

VALUE rb_io_getbyte | ( | VALUE | io | ) |

Reads a byte from the given IO.

Note
  In Ruby a "byte" always means an 8 bit integer ranging from 0 to 255 inclusive.

Parameters

  [in,out] | io | An IO, opened for reading.

Exceptions

  rb_eIOError | `io` is not opened for reading.
  rb_eFrozenError | `io` is frozen.

Return values

  RUBY_Qnil | `io` is at EOF.
  otherwise | An instance of rb_cInteger.

Postcondition
  `io` is read.

Definition at line 5078 of file io.c.

Referenced by rb_io_getbyte().

## ◆ rb_io_gets()

VALUE rb_io_gets | ( | VALUE | io | ) |

Reads a "line" from the given IO.

A line here means a chunk of characters which is terminated by either `"\n"` or an EOF.

Parameters

  [in,out] | io | An IO, opened for reading.

Exceptions

  rb_eIOError | `io` isn't opened for reading.
  rb_eFrozenError | `io` is frozen.

Return values

  RUBY_Qnil | `io` is at EOF.
  otherwise | An instance of rb_cString.

Postcondition
  `io` is read.

Note
  Unlike `IO#gets` it doesn't set `$_`.
  Unlike `IO#gets` it doesn't consider `$/`.

Definition at line 4303 of file io.c.

Referenced by rb_gets(), and rb_io_gets().

## ◆ rb_io_print()

VALUE rb_io_print | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | io
| ) |  |

Iterates over the passed array to apply rb_io_write() individually.

If there is `$,`, this function inserts the string in middle of each iterations. If there is `$\`, this function appends the string at the end. If the array is empty, this function outputs `$_`.

Parameters

  [in] | argc | Number of objects of `argv`.
  [in] | argv | An array of strings to display.
  [out] | io | An IO, opened for writing.

Exceptions

  rb_eIOError | `io` isn't opened for writing.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `str` to String.
  rb_eSystemCallError | `write(2)` failed.

Returns
  Always returns RUBY_Qnil.

Postcondition
  `argv` is written to `io`.

Note
  This function blocks.
  This function calls rb_io_write() multiple times. Which means, it is not an atomic operation. Outputs from multiple threads can interleave.

Definition at line 8738 of file io.c.

## ◆ rb_io_printf()

VALUE rb_io_printf | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | io
| ) |  |

This is a rb_f_sprintf() + rb_io_write() combo.

Parameters

  [in] | argc | Number of objects of `argv`.
  [in] | argv | A format string followed by its arguments.
  [out] | io | An IO, opened for writing.

Exceptions

  rb_eIOError | `io` isn't opened for writing.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `str` to String.
  rb_eSystemCallError | `write(2)` failed.

Returns
  Always returns RUBY_Qnil.

Postcondition
  `argv` is formatted, then written to `io`.

Note
  This function blocks.

Definition at line 8612 of file io.c.

## ◆ rb_io_puts()

VALUE rb_io_puts | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | io
| ) |  |

Iterates over the passed array to apply rb_io_write() individually.

Unlike rb_io_print(), this function prints a newline per each element. It also flattens the passed array (OTOH rb_io_print() just resorts to rb_ary_to_s()).

Parameters

  [in] | argc | Number of objects of `argv`.
  [in] | argv | An array of strings to display.
  [out] | io | An IO, opened for writing.

Exceptions

  rb_eIOError | `io` isn't opened for writing.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `str` to String.
  rb_eSystemCallError | `write(2)` failed.

Returns
  Always returns RUBY_Qnil.

Postcondition
  `argv` is written to `io`.

Note
  This function blocks.
  This function calls rb_io_write() multiple times. Which means, it is not an atomic operation. Outputs from multiple threads can interleave.

Definition at line 8970 of file io.c.

## ◆ rb_io_ungetbyte()

VALUE rb_io_ungetbyte | ( | VALUE | io,
|  | VALUE | b
| ) |  |

Identical to rb_io_ungetc(), except it doesn't take the encoding of the passed IO into account.

When an integer is passed, it just casts that value to C's `unsigned char`, and pushes that back.

Parameters

  [out] | io | An IO, opened for reading.
  [in] | b | Either a String, or an Integer.

Exceptions

  rb_eIOError | `io` is not opened for reading.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `b` to rb_cString.

Returns
  Always returns RUBY_Qnil.

Definition at line 5172 of file io.c.

Referenced by rb_io_ungetbyte().

## ◆ rb_io_ungetc()

VALUE rb_io_ungetc | ( | VALUE | io,
|  | VALUE | c
| ) |  |

"Unget"s a string.

This function pushes back the passed string onto the passed IO, such that a subsequent buffered read will return it. If the passed content is in fact an integer, a single character string of that codepoint of the encoding of the IO will be pushed back instead.

It might be counter-intuitive but this function can push back multiple characters at once. Also this function can be called multiple times on a same IO. Also a "character" can be wider than a byte, depending on the encoding of the IO.

Parameters

  [out] | io | An IO, opened for reading.
  [in] | c | Either a String, or an Integer.

Exceptions

  rb_eIOError | `io` is not opened for reading.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `c` to rb_cString.

Returns
  Always returns RUBY_Qnil.

Definition at line 5236 of file io.c.

Referenced by rb_io_ungetc().

## ◆ rb_io_write()

VALUE rb_io_write | ( | VALUE | io,
|  | VALUE | str
| ) |  |

Writes the given string to the given IO.

Parameters

  [out] | io | An IO, opened for writing.
  [in] | str | A String-like object to write to `io`.

Exceptions

  rb_eIOError | `io` isn't opened for writing.
  rb_eFrozenError | `io` is frozen.
  rb_eTypeError | No conversion from `str` to String.
  rb_eSystemCallError | `write(2)` failed for some reason.

Returns
  The number of bytes written to the `io`.

Postcondition
  `str` (up to the length of return value) is written to `io`.

Note
  This function blocks.
  Partial write is a thing. It must be at least questionable not to check the return value.

Definition at line 2302 of file io.c.

## ◆ rb_pipe()

int rb_pipe | ( | int * | pipes | ) |

This is an rb_cloexec_pipe() + rb_update_max_fd() combo.

Parameters

  [out] | pipes | Return buffer. Must at least hold 2 elements.

Return values

  0 | Successful creation of a pipe.
  -1 | Failure in underlying system call(s).

Postcondition
  `pipes` is filled with file descriptors.
  `errno` is set on failure.

Definition at line 7385 of file io.c.

Referenced by rb_pipe().

## ◆ rb_reserved_fd_p()

int rb_reserved_fd_p | ( | int | fd | ) |

Queries if the given FD is reserved or not.

Occasionally Ruby interpreter opens files for its own purposes. Use this function to prevent touching such behind-the-scene descriptors.

Parameters

  [in] | fd | Target file descriptor.

Return values

  1 | `fd` is reserved.
  0 | Otherwise.

## ◆ rb_update_max_fd()

void rb_update_max_fd | ( | int | fd | ) |

Informs the interpreter that the passed fd can be the max.

This information is used from rb_close_before_exec().

Parameters

  [in] | fd | An open FD, which can be large.

Definition at line 248 of file io.c.

Referenced by rb_fd_fix_cloexec(), rb_io_open_descriptor(), and rb_pipe().

## ◆ rb_write_error()

void rb_write_error | ( | const char * | str | ) |

Writes the given error message to somewhere applicable.

On Windows it goes to the console. On POSIX environments it goes to the standard error.

Warning
  IT IS A BAD IDEA to use this function form your C extensions. It is often annoying when GUI applications write to consoles; users don't want to look at there. Programmers also want to control the cause of the message itself, like by rescuing an exception. Just let ruby handle errors. That must be better than going your own way.

Parameters

  [in] | str | Error message to display.

Postcondition
  `str` is written to somewhere.

Definition at line 9167 of file io.c.

## ◆ rb_write_error2()

void rb_write_error2 | ( | const char * | str,
|  | long | len
| ) |  |

Identical to rb_write_error(), except it additionally takes the message's length.

Necessary when you want to handle wide characters.

Parameters

  [in] | str | Error message to display.
  [in] | len | Length of `str`, in bytes.

Postcondition
  `str` is written to somewhere.

Definition at line 9147 of file io.c.

Referenced by rb_write_error().

## Variable Documentation

## ◆ rb_default_rs

VALUE rb_default_rs
| extern

This is the default value of rb_rs, i.e.

`"\n"`. It seems it has always been just a newline string since the beginning. Not sure why C codes has to use this, given there is no way for ruby programs to interface.

Also it has not been deprecated for unknown reasons.

Definition at line 207 of file io.c.

Referenced by rb_gets(), rb_io_gets(), and rb_io_puts().

## ◆ rb_fs

VALUE rb_fs
| extern

The field separator character for inputs, or the `$;`.

This affects how `String#split` works. You can set this via the `-F` command line option. You can also assign arbitrary ruby objects programmatically, but it makes best sense for you to assign a regular expression here.

Definition at line 674 of file string.c.

## ◆ rb_output_fs

VALUE rb_output_fs
| extern

The field separator character for outputs, or the `$,`.

This affects how `Array#join` works.

Deprecated:
  Assigning anything other than RUBY_Qnil to this variable is deprecated.

Definition at line 204 of file io.c.

## ◆ rb_output_rs

VALUE rb_output_rs
| extern

The record separator character for outputs, or the `$\`.

This affects how `IO#print` works.

Deprecated:
  Assigning anything other than RUBY_Qnil to this variable is deprecated.

Definition at line 206 of file io.c.

Referenced by rb_io_print().

## ◆ rb_rs

VALUE rb_rs
| extern

The record separator character for inputs, or the `$/`.

This affects how `IO#gets` works. You can set this via the `-0` command line option.

Deprecated:
  Assigning anything other than RUBY_Qnil to this variable is deprecated.

Definition at line 205 of file io.c.