(892c46283a5ea4179500d951c9d4866c0051f27b)

#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/packed_struct.h"
#include "ruby/internal/attr/pure.h"
#include "ruby/internal/attr/noreturn.h"
#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.

Data Structures
struct	rb_io_internal_buffer
	IO buffers. More...

struct	rb_io_encoding
	Decomposed encoding flags (e.g. More...

struct	rb_io
	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) rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)
	Queries the underlying IO pointer. More...

#define	GetOpenFile RB_IO_POINTER
	This is an old name of RB_IO_POINTER. More...

#define	RB_IO_OPEN(obj, fp)
	Fills an IO object. More...

#define	MakeOpenFile RB_IO_OPEN
	This is an old name of RB_IO_OPEN. More...

Possible flags for ::rb_io_t::mode
#define	FMODE_READABLE 0x00000001
	The IO is opened for reading. More...

#define	FMODE_WRITABLE 0x00000002
	The IO is opened for writing. More...

#define	FMODE_READWRITE (FMODE_READABLE\|FMODE_WRITABLE)
	The IO is opened for both read/write. More...

#define	FMODE_BINMODE 0x00000004
	The IO is in "binary mode". More...

#define	FMODE_SYNC 0x00000008
	The IO is in "sync mode". More...

#define	FMODE_TTY 0x00000010
	The IO is a TTY. More...

#define	FMODE_DUPLEX 0x00000020
	Ruby eventually detects that the IO is bidirectional. More...

#define	FMODE_APPEND 0x00000040
	The IO is opened for appending. More...

#define	FMODE_CREATE 0x00000080
	The IO is opened for creating. More...

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

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

#define	FMODE_TEXTMODE 0x00001000
	The IO is in "text mode". More...

#define	FMODE_EXTERNAL 0x00010000
	This flag means that an IO object is wrapping an "external" file descriptor, which is owned by something outside the Ruby interpreter (usually a C extension). More...

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

Typedefs
typedef enum rb_io_event	rb_io_event_t

typedef struct rb_io_internal_buffer	rb_io_buffer_t
	Just another name of rb_io_buffer_t. More...

typedef struct rb_io	rb_io_t

typedef struct rb_io_encoding	rb_io_enc_t
	Just another name of rb_io_enc_t. More...

Enumerations
enum	rb_io_event { 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
VALUE	rb_io_open_descriptor (VALUE klass, int descriptor, int mode, VALUE path, VALUE timeout, struct rb_io_encoding *encoding)
	Allocate a new IO object, with the given file descriptor. More...

VALUE	rb_io_closed_p (VALUE io)
	Returns whether or not the underlying IO is closed. More...

FILE *	rb_io_stdio_file (rb_io_t *fptr)
	Finds or creates a stdio's file structure from a Ruby's one. More...

FILE *	rb_fdopen (int fd, const char *modestr)
	Identical to rb_io_stdio_file(), except it takes file descriptors instead of Ruby's IO. More...

int	rb_io_modestr_fmode (const char *modestr)
	Maps a file mode string (that rb_file_open() takes) into a mixture of `FMODE_` flags. More...

int	rb_io_modestr_oflags (const char *modestr)
	Identical to rb_io_modestr_fmode(), except it returns a mixture of `O_` flags. More...

	RBIMPL_ATTR_CONST () 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). More...

void	rb_io_check_writable (rb_io_t *fptr)
	Asserts that an IO is opened for writing. More...

void	rb_io_check_readable (rb_io_t *fptr)
	Just another name of rb_io_check_byte_readable. More...

void	rb_io_check_char_readable (rb_io_t *fptr)
	Asserts that an IO is opened for character-based reading. More...

void	rb_io_check_byte_readable (rb_io_t *fptr)
	Asserts that an IO is opened for byte-based reading. More...

int	rb_io_fptr_finalize (rb_io_t *fptr)
	Destroys the given IO. More...

void	rb_io_synchronized (rb_io_t *fptr)
	Sets FMODE_SYNC. More...

void	rb_io_check_initialized (rb_io_t *fptr)
	Asserts that the passed IO is initialised. More...

void	rb_io_check_closed (rb_io_t *fptr)
	This badly named function asserts that the passed IO is open. More...

VALUE	rb_io_get_io (VALUE io)
	Identical to rb_io_check_io(), except it raises exceptions on conversion failures. More...

VALUE	rb_io_check_io (VALUE io)
	Try converting an object to its IO representation using its `to_io` method, if any. More...

VALUE	rb_io_get_write_io (VALUE io)
	Queries the tied IO for writing. More...

VALUE	rb_io_set_write_io (VALUE io, VALUE w)
	Assigns the tied IO for writing. More...

void	rb_io_set_nonblock (rb_io_t *fptr)
	Instructs the OS to put its internal file structure into "nonblocking mode". More...

VALUE	rb_io_path (VALUE io)
	Returns the path for the given IO. More...

int	rb_io_descriptor (VALUE io)
	Returns an integer representing the numeric file descriptor for io. More...

int	rb_io_mode (VALUE io)
	Get the mode of the IO. More...

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

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

ssize_t	rb_io_bufwrite (VALUE io, const void *buf, size_t size)
	Buffered write to the passed IO. More...

int	rb_io_wait_readable (int fd)
	Blocks until the passed file descriptor gets readable. More...

int	rb_io_wait_writable (int fd)
	Blocks until the passed file descriptor gets writable. More...

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

VALUE	rb_io_timeout (VALUE io)
	Get the timeout associated with the specified io object. More...

VALUE	rb_io_set_timeout (VALUE io, VALUE timeout)
	Set the timeout associated with the specified io object. More...

VALUE	rb_io_wait (VALUE io, VALUE events, VALUE timeout)
	Blocks until the passed IO is ready for the passed events. More...

VALUE	rb_io_maybe_wait (int error, VALUE io, VALUE events, VALUE timeout)
	Identical to rb_io_wait() except it additionally takes previous errno. More...

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

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

VALUE	rb_io_taint_check (VALUE obj)

	RBIMPL_ATTR_NORETURN () void rb_eof_error(void)
	Utility function to raise rb_eEOFError. More...

void	rb_io_read_check (rb_io_t *fptr)
	Blocks until there is a pending read in the passed IO. More...

	RBIMPL_ATTR_PURE () int rb_io_read_pending(rb_io_t *fptr)
	Queries if the passed IO has any pending reads. More...

VALUE	rb_stat_new (const struct stat *st)
	Constructs an instance of rb_cStat from the passed information. More...

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

char *	ptr
	Pointer to the underlying memory region, of at least `capa` bytes. More...

int	off
	Offset inside of `ptr`. More...

int	len
	Length of the buffer. More...

int	capa
	Designed capacity of the buffer. More...

struct rb_io_encoding	RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END

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

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

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

◆ 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 308 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 331 of file io.h.

◆ FMODE_EXTERNAL

#define FMODE_EXTERNAL 0x00010000

This flag means that an IO object is wrapping an "external" file descriptor, which is owned by something outside the Ruby interpreter (usually a C extension).

Ruby will not close this file when the IO object is garbage collected. If this flag is set, then IO::autoclose? is false, and vice-versa.

This flag was previously called FMODE_PREP internally.

Definition at line 360 of file io.h.

◆ FMODE_READABLE

#define FMODE_READABLE 0x00000001

The IO is opened for reading.

Definition at line 270 of file io.h.

◆ FMODE_READWRITE

#define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)

The IO is opened for both read/write.

Definition at line 276 of file io.h.

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

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

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

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

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

◆ FMODE_WRITABLE

#define FMODE_WRITABLE 0x00000002

The IO is opened for writing.

Definition at line 273 of file io.h.

◆ 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 402 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 425 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 417 of file io.h.

◆ RB_IO_POINTER

#define RB_IO_POINTER	(	obj,
		fp
	)	rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)

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

Typedef Documentation

◆ rb_io_buffer_t

typedef struct rb_io_internal_buffer rb_io_buffer_t

Just another name of rb_io_buffer_t.

Definition at line 72 of file io.h.

◆ rb_io_enc_t

typedef struct rb_io_encoding rb_io_enc_t

Just another name of rb_io_enc_t.

Definition at line 72 of file io.h.

Enumeration Type Documentation

◆ rb_io_event

enum rb_io_event

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_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 7044 of file io.c.

Referenced by 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 2009 of file io.c.

◆ 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 1015 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 996 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 796 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 788 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 817 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 1024 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 1048 of file io.c.

Referenced by rb_io_bufwrite().

◆ rb_io_closed_p()

VALUE rb_io_closed_p ( VALUE io )

Returns whether or not the underlying IO is closed.

Returns: Whether the underlying IO is closed.

Definition at line 5825 of file io.c.

◆ 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 2892 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 6711 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.
   ...
}

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 6836 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 5646 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 811 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 823 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);
}

On timeout, RUBY_Qfalse is returned. Unless you are specifically handling the timeouts, you should typically raise rb_eIOTimeoutError in this case.

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.
RUBY_Qnil	Operation failed for some other reason (errno).
Otherwise	Actual events reached.

Definition at line 1603 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 is only concerned with reading and handles the timeout.

If you do not want the default timeout handling, consider using rb_io_maybe_wait directly.

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.
rb_eIOTimeoutError	The wait operation timed out.

Return values

Otherwise Always returns RUBY_IO_READABLE.

Definition at line 1644 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 is only concerned with writing, and handles the timeout.

If you do not want the default timeout handling, consider using rb_io_maybe_wait directly.

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.
rb_eIOTimeoutError	The wait operation timed out.

Return values

Otherwise Always returns RUBY_IO_WRITABLE.

Definition at line 1659 of file io.c.

◆ rb_io_mode()

int rb_io_mode ( VALUE io )

Get the mode of the IO.

Definition at line 2912 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 6429 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 6562 of file io.c.

◆ rb_io_open_descriptor()

VALUE rb_io_open_descriptor	(	VALUE	klass,
		int	descriptor,
		int	mode,
		VALUE	path,
		VALUE	timeout,
		struct rb_io_encoding *	encoding
	)

Allocate a new IO object, with the given file descriptor.

Definition at line 9214 of file io.c.

◆ rb_io_path()

VALUE rb_io_path ( VALUE io )

Returns the path for the given IO.

Definition at line 2966 of file io.c.

◆ 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 1069 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 3418 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 886 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 834 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 FILEs 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 9343 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 7331 of file io.c.

◆ 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 781 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 857 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 1447 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 1508 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 1542 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 524 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 1585 of file io.c.

Referenced by rb_thread_fd_writable(), and rb_thread_wait_fd().

◆ RBIMPL_ATTR_CONST()

RBIMPL_ATTR_CONST ( )

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.

◆ RBIMPL_ATTR_NORETURN()

RBIMPL_ATTR_NORETURN ( )

Utility function to raise rb_eEOFError.

Exceptions

rb_eEOFError End of file situation.

Note: It never returns.

◆ RBIMPL_ATTR_PURE()

RBIMPL_ATTR_PURE ( )

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.

Variable Documentation

◆ capa

int capa

Designed capacity of the buffer.

Definition at line 11 of file io.h.

Referenced by rb_ary_hidden_new(), rb_ary_new_capa(), rb_hash_new_capa(), rb_str_buf_new(), rb_str_resize(), and rb_str_set_len().

◆ len

int len

Length of the buffer.

Definition at line 8 of file io.h.

Referenced by rb_ary_cat(), rb_ary_cmp(), rb_ary_delete_at(), rb_ary_dup(), rb_ary_join(), rb_ary_plus(), rb_ary_replace(), rb_ary_resize(), rb_ary_reverse(), rb_ary_rotate(), rb_ary_shift(), rb_ary_sort_bang(), rb_ary_store(), rb_ary_subseq(), rb_big_clone(), rb_big_new(), rb_big_resize(), rb_check_id_cstr(), rb_check_symbol_cstr(), rb_deprecate_constant(), rb_econv_append(), rb_econv_insert_output(), rb_econv_set_replacement(), rb_econv_substr_append(), rb_enc_ascget(), rb_enc_interned_str(), rb_enc_str_buf_cat(), rb_enc_str_new(), rb_enc_str_new_static(), rb_enc_symname2_p(), rb_exc_new(), rb_external_str_new(), rb_external_str_new_with_enc(), rb_filesystem_str_new(), rb_intern2(), rb_intern3(), rb_intern_const(), rb_interned_str(), rb_io_ungetc(), rb_locale_str_new(), rb_memcicmp(), rb_memhash(), rb_memory_view_init_as_byte_array(), rb_memory_view_parse_item_format(), rb_range_beg_len(), rb_reg_new(), rb_reg_nth_match(), rb_reg_prepare_re(), rb_str_buf_cat_ascii(), rb_str_buf_new_cstr(), rb_str_cat(), rb_str_concat(), rb_str_conv_enc_opts(), rb_str_drop_bytes(), rb_str_dump(), rb_str_ellipsize(), rb_str_format(), rb_str_modify_expand(), rb_str_new(), rb_str_new_static(), rb_str_new_with_class(), rb_str_resize(), rb_str_set_len(), rb_str_subpos(), rb_str_subseq(), rb_str_substr(), rb_str_times(), rb_str_tmp_new(), rb_str_update(), rb_usascii_str_new(), rb_usascii_str_new_static(), rb_utf8_str_new(), rb_utf8_str_new_static(), rb_write_error2(), ruby_enc_find_extname(), ruby_init_loadpath(), ruby_scan_digits(), ruby_scan_hex(), ruby_scan_oct(), ruby_setenv(), ruby_strdup(), and ruby_strtoul().

◆ off

int off

Offset inside of ptr.

Definition at line 5 of file io.h.

Referenced by rb_econv_substr_append(), and rb_time_interval().

◆ ptr

char* ptr

Pointer to the underlying memory region, of at least capa bytes.

Definition at line 2 of file io.h.

Referenced by rb_ary_delete_at(), rb_ary_push(), rb_ary_replace(), rb_ary_resize(), rb_ary_rotate(), rb_ary_sort_bang(), rb_check_id_cstr(), rb_check_symbol_cstr(), rb_enc_interned_str(), rb_enc_interned_str_cstr(), rb_enc_str_buf_cat(), rb_enc_str_new(), rb_enc_str_new_cstr(), rb_enc_str_new_static(), rb_exc_new(), rb_external_str_new(), rb_external_str_new_cstr(), rb_external_str_new_with_enc(), rb_filesystem_str_new(), rb_filesystem_str_new_cstr(), rb_gc_update_tbl_refs(), rb_interned_str(), rb_interned_str_cstr(), rb_locale_str_new(), rb_locale_str_new_cstr(), rb_memhash(), rb_memory_view_extract_item_members(), rb_memory_view_get_item(), rb_memory_view_get_item_pointer(), rb_ractor_local_storage_ptr_set(), rb_rand_bytes_int32(), rb_reg_prepare_re(), rb_str_buf_cat_ascii(), rb_str_buf_new_cstr(), rb_str_cat(), rb_str_cat_cstr(), rb_str_conv_enc_opts(), rb_str_drop_bytes(), rb_str_new(), rb_str_new_cstr(), rb_str_new_static(), rb_str_new_with_class(), rb_str_resize(), rb_string_value(), rb_string_value_cstr(), rb_string_value_ptr(), rb_usascii_str_new(), rb_usascii_str_new_cstr(), rb_usascii_str_new_static(), rb_utf8_str_new(), rb_utf8_str_new_cstr(), rb_utf8_str_new_static(), RSTRING_PTR(), ruby_xrealloc(), and ruby_xrealloc2().

◆ rb_eIOTimeoutError

VALUE rb_eIOTimeoutError

extern

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

Definition at line 190 of file io.c.

Referenced by rb_io_maybe_wait_readable(), and rb_io_maybe_wait_writable().

(892c46283a5ea4179500d951c9d4866c0051f27b)

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ FMODE_APPEND

◆ FMODE_BINMODE

◆ FMODE_CREATE

◆ FMODE_DUPLEX

◆ FMODE_EXCL

◆ FMODE_EXTERNAL

◆ FMODE_READABLE

◆ FMODE_READWRITE

◆ FMODE_SETENC_BY_BOM

◆ FMODE_SYNC

◆ FMODE_TEXTMODE

◆ FMODE_TRUNC

◆ FMODE_TTY

◆ FMODE_WRITABLE

◆ GetOpenFile

◆ MakeOpenFile

◆ RB_IO_OPEN

◆ RB_IO_POINTER

Typedef Documentation

◆ rb_io_buffer_t

◆ rb_io_enc_t

Enumeration Type Documentation

◆ rb_io_event

Function Documentation

◆ rb_fdopen()

◆ rb_io_bufwrite()

◆ rb_io_check_byte_readable()

◆ rb_io_check_char_readable()

◆ rb_io_check_closed()

◆ rb_io_check_initialized()

◆ rb_io_check_io()

◆ rb_io_check_readable()

◆ rb_io_check_writable()

◆ rb_io_closed_p()

◆ rb_io_descriptor()

◆ rb_io_extract_encoding_option()

◆ rb_io_extract_modeenc()

◆ rb_io_fptr_finalize()

◆ rb_io_get_io()

◆ rb_io_get_write_io()

◆ rb_io_maybe_wait()

◆ rb_io_maybe_wait_readable()

◆ rb_io_maybe_wait_writable()

◆ rb_io_mode()

◆ rb_io_modestr_fmode()

◆ rb_io_modestr_oflags()

◆ rb_io_open_descriptor()

◆ rb_io_path()

◆ rb_io_read_check()

◆ rb_io_set_nonblock()

◆ rb_io_set_timeout()

◆ rb_io_set_write_io()

◆ rb_io_stdio_file()

◆ rb_io_synchronized()

◆ rb_io_taint_check()

◆ rb_io_timeout()

◆ rb_io_wait()

◆ rb_io_wait_readable()

◆ rb_io_wait_writable()

◆ rb_stat_new()

◆ rb_wait_for_single_fd()

◆ RBIMPL_ATTR_CONST()

◆ RBIMPL_ATTR_NORETURN()

◆ RBIMPL_ATTR_PURE()

Variable Documentation

◆ capa

◆ len

◆ off

◆ ptr

◆ rb_eIOTimeoutError