Ruby: include/ruby/io.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
io.h File Reference
`#include "ruby/internal/config.h"`
`#include <stdio.h>`
`#include "ruby/encoding.h"`
`#include <errno.h>`
`#include "ruby/internal/attr/const.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/attr/noreturn.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/backward/2/attributes.h"`

Go to the source code of this file.

## Data Structures
struct | rb_io_buffer_t
| IO buffers. More...
struct | rb_io_enc_t
| Decomposed encoding flags (e.g. More...
struct | rb_io_t
| Ruby's IO, metadata and buffers. More...

## Macros
#define | RUBY_IO_WAIT_METHODS
#define | RUBY_IO_TIMEOUT_DEFAULT Qnil
#define | HAVE_RB_IO_T 1
#define | RB_IO_POINTER(obj, fp)
| Queries the underlying IO pointer.
#define | GetOpenFile RB_IO_POINTER
| This is an old name of RB_IO_POINTER.
#define | RB_IO_OPEN(obj, fp)
| Fills an IO object.
#define | MakeOpenFile RB_IO_OPEN
| This is an old name of RB_IO_OPEN.
Possible flags for ::rb_io_t::mode
#define | FMODE_READABLE 0x00000001
| The IO is opened for reading.
#define | FMODE_WRITABLE 0x00000002
| The IO is opened for writing.
#define | FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)
| The IO is opened for both read/write.
#define | FMODE_BINMODE 0x00000004
| The IO is in "binary mode".
#define | FMODE_SYNC 0x00000008
| The IO is in "sync mode".
#define | FMODE_TTY 0x00000010
| The IO is a TTY.
#define | FMODE_DUPLEX 0x00000020
| Ruby eventually detects that the IO is bidirectional.
#define | FMODE_APPEND 0x00000040
| The IO is opened for appending.
#define | FMODE_CREATE 0x00000080
| The IO is opened for creating.
#define | FMODE_EXCL 0x00000400
| This flag amends the effect of FMODE_CREATE, so that if there already is a file at the given path the operation fails.
#define | FMODE_TRUNC 0x00000800
| This flag amends the effect of FMODE_CREATE, so that if there already is a file at the given path it gets truncated.
#define | FMODE_TEXTMODE 0x00001000
| The IO is in "text mode".
#define | FMODE_SETENC_BY_BOM 0x00100000
| This flag amends the encoding of the IO so that the BOM of the contents of the IO takes effect.

## Typedefs
typedef struct rb_io_buffer_t | rb_io_buffer_t
| Just another name of rb_io_buffer_t.
typedef struct rb_io_t | rb_io_t
| Ruby's IO, metadata and buffers.
typedef struct rb_io_enc_t | rb_io_enc_t
| Just another name of rb_io_enc_t.

## Enumerations
enum | rb_io_event_t { RUBY_IO_READABLE = RB_WAITFD_IN , RUBY_IO_WRITABLE = RB_WAITFD_OUT , RUBY_IO_PRIORITY = RB_WAITFD_PRI }
| Type of events that an IO can wait. More...

## Functions
FILE * | rb_io_stdio_file (rb_io_t *fptr)
| Finds or creates a stdio's file structure from a Ruby's one.
FILE * | rb_fdopen (int fd, const char *modestr)
| Identical to rb_io_stdio_file(), except it takes file descriptors instead of Ruby's IO.
int | rb_io_modestr_fmode (const char *modestr)
| Maps a file mode string (that rb_file_open() takes) into a mixture of `FMODE_` flags.
int | rb_io_modestr_oflags (const char *modestr)
| Identical to rb_io_modestr_fmode(), except it returns a mixture of `O_` flags.
int | rb_io_oflags_fmode (int oflags)
| Converts an oflags (that rb_io_modestr_oflags() returns) to a fmode (that rb_io_mode_flags() returns).
void | rb_io_check_writable (rb_io_t *fptr)
| Asserts that an IO is opened for writing.
void | rb_io_check_readable (rb_io_t *fptr)
| Just another name of rb_io_check_byte_readable.
void | rb_io_check_char_readable (rb_io_t *fptr)
| Asserts that an IO is opened for character-based reading.
void | rb_io_check_byte_readable (rb_io_t *fptr)
| Asserts that an IO is opened for byte-based reading.
int | rb_io_fptr_finalize (rb_io_t *fptr)
| Destroys the given IO.
void | rb_io_synchronized (rb_io_t *fptr)
| Sets FMODE_SYNC.
void | rb_io_check_initialized (rb_io_t *fptr)
| Asserts that the passed IO is initialised.
void | rb_io_check_closed (rb_io_t *fptr)
| This badly named function asserts that the passed IO is open.
VALUE | rb_io_get_io (VALUE io)
| Identical to rb_io_check_io(), except it raises exceptions on conversion failures.
VALUE | rb_io_check_io (VALUE io)
| Try converting an object to its IO representation using its `to_io` method, if any.
VALUE | rb_io_get_write_io (VALUE io)
| Queries the tied IO for writing.
VALUE | rb_io_set_write_io (VALUE io, VALUE w)
| Assigns the tied IO for writing.
void | rb_io_set_nonblock (rb_io_t *fptr)
| Instructs the OS to put its internal file structure into "nonblocking mode".
int | rb_io_descriptor (VALUE io)
| Returns an integer representing the numeric file descriptor for io.
int | rb_io_extract_encoding_option (VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, int *fmode_p)
| This function breaks down the option hash that `IO#initialize` takes into components.
void | rb_io_extract_modeenc (VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, int *fmode_p, rb_io_enc_t *convconfig_p)
| This function can be seen as an extended version of rb_io_extract_encoding_option() that not only concerns the option hash but also mode string and so on.
ssize_t | rb_io_bufwrite (VALUE io, const void *buf, size_t size)
| Buffered write to the passed IO.
int | rb_io_wait_readable (int fd)
| Blocks until the passed file descriptor gets readable.
int | rb_io_wait_writable (int fd)
| Blocks until the passed file descriptor gets writable.
int | rb_wait_for_single_fd (int fd, int events, struct timeval *tv)
| Blocks until the passed file descriptor is ready for the passed events.
VALUE | rb_io_timeout (VALUE io)
| Get the timeout associated with the specified io object.
VALUE | rb_io_set_timeout (VALUE io, VALUE timeout)
| Set the timeout associated with the specified io object.
VALUE | rb_io_wait (VALUE io, VALUE events, VALUE timeout)
| Blocks until the passed IO is ready for the passed events.
VALUE | rb_io_maybe_wait (int error, VALUE io, VALUE events, VALUE timeout)
| Identical to rb_io_wait() except it additionally takes previous errno.
int | rb_io_maybe_wait_readable (int error, VALUE io, VALUE timeout)
| Blocks until the passed IO is ready for reading, if that makes sense for the passed errno.
int | rb_io_maybe_wait_writable (int error, VALUE io, VALUE timeout)
| Blocks until the passed IO is ready for writing, if that makes sense for the passed errno.
VALUE | rb_io_taint_check (VALUE obj)
void | rb_eof_error (void)
| Utility function to raise rb_eEOFError.
void | rb_io_read_check (rb_io_t *fptr)
| Blocks until there is a pending read in the passed IO.
int | rb_io_read_pending (rb_io_t *fptr)
| Queries if the passed IO has any pending reads.
VALUE | rb_stat_new (const struct stat *st)
| Constructs an instance of rb_cStat from the passed information.

## Variables
VALUE | rb_eIOTimeoutError
| Indicates that a timeout has occurred while performing an IO operation.

## Detailed Description

Author
  $Author$

Date
  Fri Nov 12 16:47:09 JST 1993

Copyright
  Copyright (C) 1993-2007 Yukihiro Matsumoto
  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.

Definition in file io.h.

## Macro Definition Documentation

## ◆ FMODE_APPEND

#define FMODE_APPEND 0x00000040

The IO is opened for appending.

This mode always writes at the end of the IO. Ruby manages this flag for record but basically the logic behind this mode is at the underlying operating system. We almost do nothing.

Definition at line 296 of file io.h.

Referenced by rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_BINMODE

#define FMODE_BINMODE 0x00000004

The IO is in "binary mode".

This is not what everything rb_io_binmode() concerns. This low-level flag is to stop CR <-> CRLF conversions that would happen in the underlying operating system.

Setting this one and FMODE_TEXTMODE at the same time is a contradiction. Setting this one and ECONV_NEWLINE_DECORATOR_MASK at the same time is also a contradiction.

Definition at line 268 of file io.h.

Referenced by rb_io_binmode(), rb_io_extract_modeenc(), rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_CREATE

#define FMODE_CREATE 0x00000080

The IO is opened for creating.

This makes sense only when the destination file does not exist at the time the IO object was created. This is the default mode for writing, but you can pass `"r+"` to `IO.open` etc., to reroute this creation.

Definition at line 304 of file io.h.

Referenced by rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_DUPLEX

#define FMODE_DUPLEX 0x00000020

Ruby eventually detects that the IO is bidirectional.

For instance a TTY has such property. There are several other things known to be duplexed. Additionally you (extension library authors) can also implement your own bidirectional IO subclasses. One of such example is `Socket`.

Definition at line 289 of file io.h.

## ◆ FMODE_EXCL

#define FMODE_EXCL 0x00000400

This flag amends the effect of FMODE_CREATE, so that if there already is a file at the given path the operation fails.

Using this you can be sure that the file you get is a fresh new one.

Definition at line 312 of file io.h.

Referenced by rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_READABLE

#define FMODE_READABLE 0x00000001

The IO is opened for reading.

Definition at line 251 of file io.h.

Referenced by rb_io_check_char_readable(), rb_io_extract_modeenc(), rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_READWRITE

#define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)

The IO is opened for both read/write.

Definition at line 257 of file io.h.

Referenced by rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_SETENC_BY_BOM

#define FMODE_SETENC_BY_BOM 0x00100000

This flag amends the encoding of the IO so that the BOM of the contents of the IO takes effect.

Definition at line 340 of file io.h.

Referenced by rb_io_modestr_fmode().

## ◆ FMODE_SYNC

#define FMODE_SYNC 0x00000008

The IO is in "sync mode".

All output is immediately flushed to the underlying operating system then. Can be set via rb_io_synchronized(), but there is no way except calling `IO#sync=` to reset.

Definition at line 275 of file io.h.

Referenced by rb_io_synchronized().

## ◆ FMODE_TEXTMODE

#define FMODE_TEXTMODE 0x00001000

The IO is in "text mode".

On systems where such mode make sense, this flag changes the way the IO handles the contents. On POSIX systems it is basically a no-op, but with this flag set you can optionally let Ruby manually convert newlines, unlike when in binary mode:

IO.open("/p/a/t/h", "wt", crlf_newline: true) # "wb" is NG.

Setting this one and FMODE_BINMODE at the same time is a contradiction.

Definition at line 332 of file io.h.

Referenced by rb_io_modestr_fmode().

## ◆ FMODE_TRUNC

#define FMODE_TRUNC 0x00000800

This flag amends the effect of FMODE_CREATE, so that if there already is a file at the given path it gets truncated.

Definition at line 318 of file io.h.

Referenced by rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ FMODE_TTY

#define FMODE_TTY 0x00000010

The IO is a TTY.

What is a TTY and what isn't depends on the underlying operating system's `isatty(3)` output. You cannot change this.

Definition at line 281 of file io.h.

Referenced by rb_io_getbyte().

## ◆ FMODE_WRITABLE

#define FMODE_WRITABLE 0x00000002

The IO is opened for writing.

Definition at line 254 of file io.h.

Referenced by rb_file_size(), rb_io_check_writable(), rb_io_extract_modeenc(), rb_io_modestr_fmode(), and rb_io_oflags_fmode().

## ◆ GetOpenFile

#define GetOpenFile RB_IO_POINTER

This is an old name of RB_IO_POINTER.

Not sure if we want to deprecate this macro. There still are tons of usages out there in the wild.

Definition at line 362 of file io.h.

Referenced by rb_io_ascii8bit_binmode(), rb_io_binmode(), rb_io_bufwrite(), rb_io_check_char_readable(), rb_io_eof(), rb_io_getbyte(), rb_io_ungetbyte(), and rb_io_ungetc().

## ◆ HAVE_RB_IO_T

#define HAVE_RB_IO_T 1

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 242 of file io.h.

## ◆ MakeOpenFile

#define MakeOpenFile RB_IO_OPEN

This is an old name of RB_IO_OPEN.

Not sure if we want to deprecate this macro. There still are usages out there in the wild.

Definition at line 385 of file io.h.

## ◆ RB_IO_OPEN

#define RB_IO_OPEN | ( |  | obj,
|  |  | fp )

Value:
do {\
(fp) = rb_io_make_open_file(obj);\
} while (0)

Fills an IO object.

This makes the best sense when called from inside of an `#initialize` method of a 3rd party extension library that inherits rb_cIO.

If the passed IO is already opened for something it first closes that and opens a new one instead.

Parameters

  [out] | obj | An IO object to fill in.
  [out] | fp | A variable of type rb_io_t.

Exceptions

  rb_eTypeError | `obj` is not RUBY_T_FILE.

Postcondition
  `fp` holds `obj`'s underlying IO.

Definition at line 377 of file io.h.

## ◆ RB_IO_POINTER

#define RB_IO_POINTER | ( |  | obj,
|  |  | fp )

Value:
rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)
rb_io_taint_check
VALUE rb_io_taint_check(VALUE obj)
Definition io.c:767
rb_io_check_closed
void rb_io_check_closed(rb_io_t *fptr)
This badly named function asserts that the passed IO is open.
Definition io.c:782
RFILE
#define RFILE(obj)
Convenient casting macro.
Definition rfile.h:50

Queries the underlying IO pointer.

Parameters

  [in] | obj | An IO object.
  [out] | fp | A variable of type rb_io_t.

Exceptions

  rb_eFrozenError | `obj` is frozen.
  rb_eIOError | `obj` is closed.

Postcondition
  `fp` holds `obj`'s underlying IO.

Definition at line 356 of file io.h.

Referenced by rb_file_size(), and rb_io_wait().

## ◆ RUBY_IO_TIMEOUT_DEFAULT

#define RUBY_IO_TIMEOUT_DEFAULT Qnil

Definition at line 62 of file io.h.

## ◆ RUBY_IO_WAIT_METHODS

#define RUBY_IO_WAIT_METHODS

Definition at line 59 of file io.h.

## Typedef Documentation

## ◆ rb_io_buffer_t

typedef struct rb_io_buffer_t rb_io_buffer_t

Just another name of rb_io_buffer_t.

Definition at line 107 of file io.h.

## ◆ rb_io_enc_t

typedef struct rb_io_enc_t rb_io_enc_t

Just another name of rb_io_enc_t.

Definition at line 233 of file io.h.

## ◆ rb_io_t

typedef struct rb_io_t rb_io_t

Ruby's IO, metadata and buffers.

## Enumeration Type Documentation

## ◆ rb_io_event_t

enum rb_io_event_t

Type of events that an IO can wait.

Enumerator
RUBY_IO_READABLE | `IO::READABLE`
RUBY_IO_WRITABLE | `IO::WRITABLE`
RUBY_IO_PRIORITY | `IO::PRIORITY`

Definition at line 81 of file io.h.

## Function Documentation

## ◆ rb_eof_error()

void rb_eof_error | ( | void |  | ) |

Utility function to raise rb_eEOFError.

Exceptions

  rb_eEOFError | End of file situation.

Note
  It never returns.

Definition at line 761 of file io.c.

## ◆ rb_fdopen()

FILE * rb_fdopen | ( | int | fd,
|  | const char * | modestr )

Identical to rb_io_stdio_file(), except it takes file descriptors instead of Ruby's IO.

It can also be seen as a compatibility layer to wrap `fdopen(3)`. Nowadays all supporting systems, including Windows, have `fdopen`. Why not use them.

Parameters

  [in] | fd | A file descriptor.
  [in] | modestr | C string, something like `"r+"`.

Exceptions

  rb_eSystemCallError | `fdopen` failed for some reason.

Returns
  A stdio's file associated with `fd`.

Note
  Interpretation of `modestr` depends on the underlying operating system. On glibc you might be able to pass e.g. `"rm"`, but that's an extension to POSIX.

Definition at line 6970 of file io.c.

Referenced by rb_fdopen(), and rb_io_stdio_file().

## ◆ rb_io_bufwrite()

ssize_t rb_io_bufwrite | ( | VALUE | io,
|  | const void * | buf,
|  | size_t | size )

Buffered write to the passed IO.

Parameters

  [out] | io | Destination IO.
  [in] | buf | Contents to go to `io`.
  [in] | size | Number of bytes of `buf`.

Exceptions

  rb_eFrozenError | `io` is frozen.
  rb_eIOError | `io` is not open for writing.
  rb_eSystemCallError | `writev(2)` failed for some reason.

Return values

  -1 | Write failed.
  otherwise | Number of bytes actually written.

Postcondition
  `buf` is written to `io`.

Note
  Partial write is a thing. It is a failure not to check the return value.

Definition at line 1980 of file io.c.

Referenced by rb_io_bufwrite().

## ◆ rb_io_check_byte_readable()

void rb_io_check_byte_readable | ( | rb_io_t * | fptr | ) |

Asserts that an IO is opened for byte-based reading.

Byte-based and character-based reading operations cannot be mixed at a time.

Parameters

  [in] | fptr | An IO you want to read characters from.

Exceptions

  rb_eIOError | `fptr` is not for reading.

Postcondition
  Upon successful return `fptr` is ready for reading bytes.

Definition at line 997 of file io.c.

Referenced by rb_io_check_readable(), rb_io_getbyte(), and rb_io_ungetbyte().

## ◆ rb_io_check_char_readable()

void rb_io_check_char_readable | ( | rb_io_t * | fptr | ) |

Asserts that an IO is opened for character-based reading.

A character can be wider than a byte. Because of this we have to buffer reads from descriptors. This fiction checks if that is possible.

Parameters

  [in] | fptr | An IO you want to read characters from.

Exceptions

  rb_eIOError | `fptr` is not for reading.

Postcondition
  Upon successful return `fptr` is ready for reading characters.

Definition at line 978 of file io.c.

Referenced by rb_io_check_byte_readable(), rb_io_eof(), and rb_io_ungetc().

## ◆ rb_io_check_closed()

void rb_io_check_closed | ( | rb_io_t * | fptr | ) |

This badly named function asserts that the passed IO is open.

Parameters

  [in] | fptr | An IO

Exceptions

  rb_eIOError | `fptr` is closed.

Postcondition
  `fptr` is open.

Definition at line 782 of file io.c.

Referenced by rb_io_check_char_readable(), rb_io_check_writable(), rb_io_descriptor(), rb_io_maybe_wait(), and rb_io_wait().

## ◆ rb_io_check_initialized()

void rb_io_check_initialized | ( | rb_io_t * | fptr | ) |

Asserts that the passed IO is initialised.

Parameters

  [in] | fptr | IO that you expect be initialised.

Exceptions

  rb_eIOError | `fptr` is not initialised.

Postcondition
  `fptr` is initialised.

Definition at line 774 of file io.c.

Referenced by rb_io_check_closed(), and rb_io_synchronized().

## ◆ rb_io_check_io()

VALUE rb_io_check_io | ( | VALUE | io | ) |

Try converting an object to its IO representation using its `to_io` method, if any.

If there is no such thing, returns RUBY_Qnil.

Parameters

  [in] | io | Arbitrary ruby object to convert.

Exceptions

  rb_eTypeError | `obj.to_io` returned something non-IO.

Return values

  RUBY_Qnil | No conversion from `obj` to IO defined.
  otherwise | Converted IO representation of `obj`.

See also
  rb_check_array_type
  rb_check_string_type
  rb_check_hash_type

Definition at line 803 of file io.c.

## ◆ rb_io_check_readable()

void rb_io_check_readable | ( | rb_io_t * | fptr | ) |

Just another name of rb_io_check_byte_readable.

Definition at line 1006 of file io.c.

## ◆ rb_io_check_writable()

void rb_io_check_writable | ( | rb_io_t * | fptr | ) |

Asserts that an IO is opened for writing.

Parameters

  [in] | fptr | An IO you want to write to.

Exceptions

  rb_eIOError | `fptr` is not for writing.

Postcondition
  Upon successful return `fptr` is ready for writing.

Definition at line 1030 of file io.c.

Referenced by rb_io_bufwrite().

## ◆ rb_io_descriptor()

int rb_io_descriptor | ( | VALUE | io | ) |

Returns an integer representing the numeric file descriptor for io.

Parameters

  [in] | io | An IO.

Return values

  int | A file descriptor.

Definition at line 2869 of file io.c.

## ◆ rb_io_extract_encoding_option()

int rb_io_extract_encoding_option | ( | VALUE | opt,
|  | rb_encoding ** | enc_p,
|  | rb_encoding ** | enc2_p,
|  | int * | fmode_p )

This function breaks down the option hash that `IO#initialize` takes into components.

This is an implementation detail of rb_io_extract_modeenc() today. People prefer that API instead.

Parameters

  [in] | opt | The hash to decompose.
  [out] | enc_p | Return value buffer.
  [out] | enc2_p | Return value buffer.
  [out] | fmode_p | Return value buffer.

Exceptions

  rb_eTypeError | `opt` is broken.
  rb_eArgError | Specified encoding does not exist.

Return values

  1 | Components got extracted.
  0 | Otherwise.

Postcondition
  `enc_p` is the specified internal encoding.
  `enc2_p` is the specified external encoding.
  `fmode_p` is the specified set of `FMODE_` modes.

Definition at line 6649 of file io.c.

Referenced by rb_io_extract_modeenc().

## ◆ rb_io_extract_modeenc()

void rb_io_extract_modeenc | ( | VALUE * | vmode_p,
|  | VALUE * | vperm_p,
|  | VALUE | opthash,
|  | int * | oflags_p,
|  | int * | fmode_p,
|  | rb_io_enc_t * | convconfig_p )

This function can be seen as an extended version of rb_io_extract_encoding_option() that not only concerns the option hash but also mode string and so on.

This should be mixed with rb_scan_args() like:

// This method mimics File.new
static VALUE
your_method(int argc, const VALUE *argv, VALUE self)
{
VALUE f; // file name
VALUE m; // open mode
VALUE p; // permission (O_CREAT)
VALUE k; // keywords
rb_io_enc_t c; // converter
int oflags;
int fmode;
int n = rb_scan_args(argc, argv, "12:", &f, &m, &p, &k);
rb_io_extract_modeenc(&m, &p, k, &oflags, &fmode, &c);
// Every local variables declared so far has been properly filled here.
...
}
rb_scan_args
int rb_scan_args(int argc, const VALUE *argv, const char *fmt,...)
Retrieves argument from argc and argv to given VALUE references according to the format string.
Definition class.c:2579
rb_io_extract_modeenc
void rb_io_extract_modeenc(VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, int *fmode_p, rb_io_enc_t *convconfig_p)
This function can be seen as an extended version of rb_io_extract_encoding_option() that not only con...
Definition io.c:6776
rb_io_enc_t
Decomposed encoding flags (e.g.
Definition io.h:116
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Parameters

  [in,out] | vmode_p | Pointer to a mode object.
  [in,out] | vperm_p | Pointer to a permission object.
  [in] | opthash | Keyword arguments
  [out] | oflags_p | `O_` flags return buffer.
  [out] | fmode_p | `FMODE_` flags return buffer.
  [out] | convconfig_p | Encoding config return buffer.

Exceptions

  rb_eTypeError | Unexpected object (e.g. Time) passed.
  rb_eArgError | Contradiction inside of params.

Postcondition
  `*vmode_p` is a mode object (filled if any).
  `*vperm_p` is a permission object (filled if any).
  `*oflags_p` is filled with `O_` flags.
  `*fmode_p` is filled with `FMODE_` flags.
  `*convconfig_p` is filled with conversion instructions.

Definition at line 6776 of file io.c.

## ◆ rb_io_fptr_finalize()

int rb_io_fptr_finalize | ( | rb_io_t * | fptr | ) |

Destroys the given IO.

Any pending operations are flushed.

Note
  It makes no sense to call this function from anywhere outside of your class' rb_data_type_struct::dfree.

Parameters

  [out] | fptr | IO to close.

Postcondition
  `fptr` is no longer a valid pointer.

Definition at line 5598 of file io.c.

## ◆ rb_io_get_io()

VALUE rb_io_get_io | ( | VALUE | io | ) |

Identical to rb_io_check_io(), except it raises exceptions on conversion failures.

Parameters

  [in] | io | Target object.

Exceptions

  rb_eTypeError | No implicit conversion to IO.

Returns
  Return value of `obj.to_io`.

See also
  rb_str_to_str
  rb_ary_to_ary

Definition at line 797 of file io.c.

## ◆ rb_io_get_write_io()

VALUE rb_io_get_write_io | ( | VALUE | io | ) |

Queries the tied IO for writing.

An IO can be duplexed. Fine. The thing is, that characteristics could sometimes be achieved by the underlying operating system (for instance a socket's duplexity is by nature) but sometimes by us. Notable example is a bidirectional pipe. Suppose you have:

fp = IO.popen("-", "r+")

This pipe is duplexed (the `"r+"`). You can both read from/write to it. However your operating system may or may not implement bidirectional pipes. FreeBSD is one of such operating systems known to have one; OTOH Linux is known to lack such things. So to achieve maximum portability, Ruby's bidirectional pipes are done purely in user land. A pipe in ruby can have multiple file descriptors; one for reading and the other for writing. This API is to obtain the IO port which corresponds to the passed one, for writing.

Parameters

  [in] | io | An IO.

Returns
  Its tied IO for writing, if any, or `io` itself otherwise.

Definition at line 809 of file io.c.

## ◆ rb_io_maybe_wait()

VALUE rb_io_maybe_wait | ( | int | error,
|  | VALUE | io,
|  | VALUE | events,
|  | VALUE | timeout )

Identical to rb_io_wait() except it additionally takes previous errno.

If the passed errno indicates for instance `EINTR`, this function returns immediately. This is expected to be called in a loop.

while (true) {
... // Your interesting operation here
// `errno` could be updated
rb_io_maybe_wait(errno, io, ev, Qnil);
}
Qnil
#define Qnil
Old name of RUBY_Qnil.
Definition special_consts.h:60
rb_io_maybe_wait
VALUE rb_io_maybe_wait(int error, VALUE io, VALUE events, VALUE timeout)
Identical to rb_io_wait() except it additionally takes previous errno.
Definition io.c:1576

Parameters

  [in] | error | System errno.
  [in] | io | An IO object to wait.
  [in] | events | An integer set of interests.
  [in] | timeout | Time, or numeric seconds since UNIX epoch.

Exceptions

  rb_eIOError | `io` is not open.
  rb_eRangeError | `timeout` is out of range.
  rb_eSystemCallError | `select(2)` failed for some reason.

Return values

  RUBY_Qfalse | Operation timed out.
  Otherwise | Actual events reached.

Definition at line 1576 of file io.c.

Referenced by rb_io_maybe_wait_readable(), and rb_io_maybe_wait_writable().

## ◆ rb_io_maybe_wait_readable()

int rb_io_maybe_wait_readable | ( | int | error,
|  | VALUE | io,
|  | VALUE | timeout )

Blocks until the passed IO is ready for reading, if that makes sense for the passed errno.

This is a special case of rb_io_maybe_wait() that only concerns for reading.

Parameters

  [in] | error | System errno.
  [in] | io | An IO object to wait.
  [in] | timeout | Time, or numeric seconds since UNIX epoch.

Exceptions

  rb_eIOError | `io` is not open.
  rb_eRangeError | `timeout` is out of range.
  rb_eSystemCallError | `select(2)` failed for some reason.

Return values

  0 | Operation timed out.
  Otherwise | Always returns RUBY_IO_READABLE.

Definition at line 1617 of file io.c.

## ◆ rb_io_maybe_wait_writable()

int rb_io_maybe_wait_writable | ( | int | error,
|  | VALUE | io,
|  | VALUE | timeout )

Blocks until the passed IO is ready for writing, if that makes sense for the passed errno.

This is a special case of rb_io_maybe_wait() that only concernsfor writing.

Parameters

  [in] | error | System errno.
  [in] | io | An IO object to wait.
  [in] | timeout | Time, or numeric seconds since UNIX epoch.

Exceptions

  rb_eIOError | `io` is not open.
  rb_eRangeError | `timeout` is out of range.
  rb_eSystemCallError | `select(2)` failed for some reason.

Return values

  0 | Operation timed out.
  Otherwise | Always returns RUBY_IO_WRITABLE.

Definition at line 1630 of file io.c.

## ◆ rb_io_modestr_fmode()

int rb_io_modestr_fmode | ( | const char * | modestr | ) |

Maps a file mode string (that rb_file_open() takes) into a mixture of `FMODE_` flags.

This for instance returns `FMODE_WRITABLE | FMODE_TRUNC | FMODE_CREATE | FMODE_EXCL` for `"wx"`.

Note
  You cannot pass this return value to OS provided `open(2)` etc.

Parameters

  [in] | modestr | File mode, in C's string.

Exceptions

  rb_eArgError | `modestr` is broken.

Returns
  A set of flags.

Definition at line 6367 of file io.c.

Referenced by rb_io_extract_modeenc(), and rb_io_modestr_oflags().

## ◆ rb_io_modestr_oflags()

int rb_io_modestr_oflags | ( | const char * | modestr | ) |

Identical to rb_io_modestr_fmode(), except it returns a mixture of `O_` flags.

This for instance returns `O_WRONLY | O_TRUNC | O_CREAT | O_EXCL` for `"wx"`.

Parameters

  [in] | modestr | File mode, in C's string.

Exceptions

  rb_eArgError | `modestr` is broken.

Returns
  A set of flags.

Definition at line 6500 of file io.c.

## ◆ rb_io_oflags_fmode()

int rb_io_oflags_fmode | ( | int | oflags | ) |

Converts an oflags (that rb_io_modestr_oflags() returns) to a fmode (that rb_io_mode_flags() returns).

This is a purely functional operation.

Parameters

  [in] | oflags | A set of `O_` flags.

Returns
  Corresponding set of `FMODE_` flags.

Definition at line 6424 of file io.c.

Referenced by rb_io_extract_modeenc(), and rb_io_fdopen().

## ◆ rb_io_read_check()

void rb_io_read_check | ( | rb_io_t * | fptr | ) |

Blocks until there is a pending read in the passed IO.

If there already is it just returns.

Parameters

  [out] | fptr | An IO to wait for reading.

Postcondition
  The are bytes to be read.

Definition at line 1051 of file io.c.

## ◆ rb_io_read_pending()

int rb_io_read_pending | ( | rb_io_t * | fptr | ) |

Queries if the passed IO has any pending reads.

Unlike rb_io_read_check() this doesn't block; has no side effects.

Parameters

  [in] | fptr | An IO which can have pending reads.

Return values

  0 | The IO is empty.
  1 | There is something buffered.

Definition at line 1042 of file io.c.

## ◆ rb_io_set_nonblock()

void rb_io_set_nonblock | ( | rb_io_t * | fptr | ) |

Instructs the OS to put its internal file structure into "nonblocking mode".

This is an in-Kernel concept. Reading from/writing to that file using C function calls would return -1 with errno set. However when it comes to a ruby program, we hide that error behind our `IO#read` method. Ruby level `IO#read` blocks regardless of this flag. If you want to avoid blocking, you should consider using methods like `IO#readpartial`.

require 'io/nonblock'
STDIN.nonblock = true
STDIN.gets # blocks.

As of writing there is a room of this API in Fiber schedulers. A Fiber scheduler could be written in a way its behaviour depends on this property. You need an in-depth understanding of how schedulers work to properly leverage this, though.

Note
  Note however that nonblocking-ness propagates across process boundaries. You must really carefully watch your step when turning for instance `stderr` into nonblock mode (it tends to be shared across many processes). Also it is a complete disaster to mix a nonblocking file and stdio, and `stderr` tends to be under control of stdio in other processes.

Parameters

  [out] | fptr | An IO that is to ne nonblocking.

Postcondition
  Descriptor that `fptr` describes is under nonblocking mode.

Definition at line 3379 of file io.c.

## ◆ rb_io_set_timeout()

VALUE rb_io_set_timeout | ( | VALUE | io,
|  | VALUE | timeout )

Set the timeout associated with the specified io object.

This timeout is used as a best effort timeout to prevent operations from blocking forever.

Parameters

  [in] | io | An IO object.
  [in] | timeout | A timeout value. Must respond to #to_f. @

Definition at line 869 of file io.c.

## ◆ rb_io_set_write_io()

VALUE rb_io_set_write_io | ( | VALUE | io,
|  | VALUE | w )

Assigns the tied IO for writing.

See rb_io_get_write_io() for what a "tied IO for writing" is.

Parameters

  [out] | io | An IO.
  [in] | w | Another IO.

Return values

  RUBY_Qnil | There was no tied IO for writing for `io`.
  otherwise | The IO formerly tied to `io`.

Postcondition
  `io` ties `w` for writing.

Definition at line 820 of file io.c.

## ◆ rb_io_stdio_file()

FILE * rb_io_stdio_file | ( | rb_io_t * | fptr | ) |

Finds or creates a stdio's file structure from a Ruby's one.

This can be handy if you want to call an external API that accepts `FILE *`.

Note
  Note however, that `FILE`s can have their own buffer. Mixing Ruby's and stdio's file are basically dangerous. Use with care.

Parameters

  [in,out] | fptr | Target IO.

Returns
  A stdio's file, created if absent.

Postcondition
  `fptr` has its corresponding stdio's file.

Definition at line 9249 of file io.c.

## ◆ rb_io_synchronized()

void rb_io_synchronized | ( | rb_io_t * | fptr | ) |

Sets FMODE_SYNC.

Note
  There is no way for C extensions to undo this operation.

Parameters

  [out] | fptr | IO to set the flag.

Exceptions

  rb_eIOError | `fptr` is not opened.

Postcondition
  `fptr` is in sync mode.

Definition at line 7273 of file io.c.

Referenced by rb_io_synchronized().

## ◆ rb_io_taint_check()

VALUE rb_io_taint_check | ( | VALUE | obj | ) |

Deprecated
  This function 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.

Parameters

  [in] | obj | Object in question.

Exceptions

  rb_eFrozenError | obj is frozen.

Returns
  The passed `obj`

Definition at line 767 of file io.c.

## ◆ rb_io_timeout()

VALUE rb_io_timeout | ( | VALUE | io | ) |

Get the timeout associated with the specified io object.

Parameters

  [in] | io | An IO object.

Return values

  RUBY_Qnil | There is no associated timeout.
  Otherwise | The timeout value.

Definition at line 843 of file io.c.

Referenced by rb_fiber_scheduler_io_wait_readable(), and rb_fiber_scheduler_io_wait_writable().

## ◆ rb_io_wait()

VALUE rb_io_wait | ( | VALUE | io,
|  | VALUE | events,
|  | VALUE | timeout )

Blocks until the passed IO is ready for the passed events.

The "events" here is a Ruby level integer, which is an OR-ed value of `IO::READABLE`, `IO::WRITable`, and `IO::PRIORITY`.

If timeout is `Qnil`, it will use the default timeout as given by `rb_io_timeout(io)`.

Parameters

  [in] | io | An IO object to wait.
  [in] | events | See above.
  [in] | timeout | Time, or numeric seconds since UNIX epoch. If Qnil, use the default timeout. If Qfalse or Qundef, wait forever.

Exceptions

  rb_eIOError | `io` is not open.
  rb_eRangeError | `timeout` is out of range.
  rb_eSystemCallError | `select(2)` failed for some reason.

Return values

  RUBY_Qfalse | Operation timed out.
  Otherwise | Actual events reached.

Definition at line 1420 of file io.c.

Referenced by rb_io_maybe_wait(), and rb_io_read_check().

## ◆ rb_io_wait_readable()

int rb_io_wait_readable | ( | int | fd | ) |

Blocks until the passed file descriptor gets readable.

Deprecated
  We now prefer rb_io_maybe_wait_readable() over this one.

Parameters

  [in] | fd | The file descriptor to wait.

Exceptions

  rb_eIOError | Bad file descriptor.

Returns
  0 or 1 (meaning unclear).

Postcondition
  `fd` is ready for reading.

Definition at line 1481 of file io.c.

## ◆ rb_io_wait_writable()

int rb_io_wait_writable | ( | int | fd | ) |

Blocks until the passed file descriptor gets writable.

Deprecated
  We now prefer rb_io_maybe_wait_writable() over this one.

Parameters

  [in] | fd | The file descriptor to wait.

Exceptions

  rb_eIOError | Bad file descriptor.

Returns
  0 or 1 (meaning unclear).

Definition at line 1515 of file io.c.

## ◆ rb_stat_new()

VALUE rb_stat_new | ( | const struct stat * | st | ) |

Constructs an instance of rb_cStat from the passed information.

Parameters

  [in] | st | A stat.

Returns
  Allocated new instance of rb_cStat.

Definition at line 514 of file file.c.

## ◆ rb_wait_for_single_fd()

int rb_wait_for_single_fd | ( | int | fd,
|  | int | events,
|  | struct timeval * | tv )

Blocks until the passed file descriptor is ready for the passed events.

Deprecated
  We now prefer rb_io_maybe_wait() over this one.

Parameters

  [in] | fd | The file descriptor to wait.
  [in] | events | A set of enum rb_io_event_t.
  [in,out] | tv | Timeout.

Return values

  0 | Operation timed out.
  -1 | `select(2)` failed for some reason.
  otherwise | A set of enum rb_io_event_t.

Note
  Depending on your operating system `tv` might or might not be updated (POSIX permits both). Portable programs must have no assumptions.

Definition at line 1558 of file io.c.

Referenced by rb_thread_fd_writable(), and rb_thread_wait_fd().

## Variable Documentation

## ◆ rb_eIOTimeoutError

VALUE rb_eIOTimeoutError
| extern

Indicates that a timeout has occurred while performing an IO operation.

Definition at line 183 of file io.c.