Ruby  3.1.4p223 (2023-03-30 revision HEAD)
Data Structures | Macros | Typedefs | Enumerations | Functions
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_t
 Ruby's IO, metadata and buffers. More...
 
struct  rb_io_t::rb_io_enc_t
 Decomposed encoding flags (e.g. More...
 

Macros

#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_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 struct rb_io_buffer_t rb_io_buffer_t
 Just another name of rb_io_buffer_t. More...
 
typedef struct rb_io_t rb_io_t
 Ruby's IO, metadata and buffers. More...
 
typedef struct rb_io_enc_t rb_io_enc_t
 Just another name of rb_io_enc_t. More...
 

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

FILErb_io_stdio_file (rb_io_t *fptr)
 Finds or creates a stdio's file structure from a Ruby's one. More...
 
FILErb_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)
 Sets an IO to a "nonblock mode". More...
 
int rb_io_descriptor (VALUE io)
 Returns an integer representing the numeric file descriptor for 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_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...
 

Detailed Description

Author
$Author$
Date
Fri Nov 12 16:47:09 JST 1993

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 277 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 249 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 285 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 270 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 293 of file io.h.

◆ FMODE_READABLE

#define FMODE_READABLE   0x00000001

The IO is opened for reading.

Definition at line 232 of file io.h.

◆ FMODE_READWRITE

#define FMODE_READWRITE   (FMODE_READABLE|FMODE_WRITABLE)

The IO is opened for both read/write.

Definition at line 238 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 321 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 256 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 313 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 299 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 262 of file io.h.

◆ FMODE_WRITABLE

#define FMODE_WRITABLE   0x00000002

The IO is opened for writing.

Definition at line 235 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 343 of file io.h.

◆ 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 223 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 366 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]objAn IO object to fill in.
[out]fpA variable of type rb_io_t.
Exceptions
rb_eTypeErrorobj is not RUBY_T_FILE.
Postcondition
fp holds obj's underlying IO.

Definition at line 358 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]objAn IO object.
[out]fpA variable of type rb_io_t.
Exceptions
rb_eFrozenErrorobj is frozen.
rb_eIOErrorobj is closed.
Postcondition
fp holds obj's underlying IO.

Definition at line 337 of file io.h.

Typedef Documentation

◆ rb_io_buffer_t

Just another name of rb_io_buffer_t.

Definition at line 1 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 1 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

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 66 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]fdA file descriptor.
[in]modestrC string, something like "r+".
Exceptions
rb_eSystemCallErrorfdopen 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 6476 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]ioDestination IO.
[in]bufContents to go to io.
[in]sizeNumber of bytes of buf.
Exceptions
rb_eFrozenErrorio is frozen.
rb_eIOErrorio is not open for writing.
rb_eSystemCallErrorwritev(2) failed for some reason.
Return values
-1Write failed.
otherwiseNumber 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 1807 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]fptrAn IO you want to read characters from.
Exceptions
rb_eIOErrorfptr is not for reading.
Postcondition
Upon successful return fptr is ready for reading bytes.

Definition at line 953 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]fptrAn IO you want to read characters from.
Exceptions
rb_eIOErrorfptr is not for reading.
Postcondition
Upon successful return fptr is ready for reading characters.

Definition at line 934 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]fptrAn IO
Exceptions
rb_eIOErrorfptr is closed.
Postcondition
fptr is open.

Definition at line 786 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]fptrIO that you expect be initialised.
Exceptions
rb_eIOErrorfptr is not initialised.
Postcondition
fptr is initialised.

Definition at line 778 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]ioArbitrary ruby object to convert.
Exceptions
rb_eTypeErrorobj.to_io returned something non-IO.
Return values
RUBY_QnilNo conversion from obj to IO defined.
otherwiseConverted IO representation of obj.
See also
rb_check_array_type
rb_check_string_type
rb_check_hash_type

Definition at line 807 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 962 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]fptrAn IO you want to write to.
Exceptions
rb_eIOErrorfptr is not for writing.
Postcondition
Upon successful return fptr is ready for writing.

Definition at line 986 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]ioAn IO.
Return values
intA file descriptor.

Definition at line 2650 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]optThe hash to decompose.
[out]enc_pReturn value buffer.
[out]enc2_pReturn value buffer.
[out]fmode_pReturn value buffer.
Exceptions
rb_eTypeErroropt is broken.
rb_eArgErrorSpecified encoding does not exist.
Return values
1Components got extracted.
0Otherwise.
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 6155 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.
...
}
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:2406
struct rb_io_enc_t rb_io_enc_t
Just another name of rb_io_enc_t.
Definition: io.h:214
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:6282
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40
Parameters
[in,out]vmode_pPointer to a mode object.
[in,out]vperm_pPointer to a permission object.
[in]opthashKeyword arguments
[out]oflags_pO_ flags return buffer.
[out]fmode_pFMODE_ flags return buffer.
[out]convconfig_pEncoding config return buffer.
Exceptions
rb_eTypeErrorUnexpected object (e.g. Time) passed.
rb_eArgErrorContradiction 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 6282 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]fptrIO to close.
Postcondition
fptr is no longer a valid pointer.

Definition at line 5161 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]ioTarget object.
Exceptions
rb_eTypeErrorNo implicit conversion to IO.
Returns
Return value of obj.to_io.
See also
rb_str_to_str
rb_ary_to_ary

Definition at line 801 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]ioAn IO.
Returns
Its tied IO for writing, if any, or io itself otherwise.

Definition at line 813 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);
}
#define Qnil
Old name of RUBY_Qnil.
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:1446
Parameters
[in]errorSystem errno.
[in]ioAn IO object to wait.
[in]eventsAn integer set of interests.
[in]timeoutTime, or numeric seconds since UNIX epoch.
Exceptions
rb_eIOErrorio is not open.
rb_eRangeErrortimeout is out of range.
rb_eSystemCallErrorselect(2) failed for some reason.
Return values
RUBY_QfalseOperation timed out.
OtherwiseActual events reached.

Definition at line 1446 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]errorSystem errno.
[in]ioAn IO object to wait.
[in]timeoutTime, or numeric seconds since UNIX epoch.
Exceptions
rb_eIOErrorio is not open.
rb_eRangeErrortimeout is out of range.
rb_eSystemCallErrorselect(2) failed for some reason.
rb_eTypeErrorOperation timed out.
Returns
Always returns RUBY_IO_READABLE.

Definition at line 1487 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]errorSystem errno.
[in]ioAn IO object to wait.
[in]timeoutTime, or numeric seconds since UNIX epoch.
Exceptions
rb_eIOErrorio is not open.
rb_eRangeErrortimeout is out of range.
rb_eSystemCallErrorselect(2) failed for some reason.
rb_eTypeErrorOperation timed out.
Returns
Always returns RUBY_IO_WRITABLE.

Definition at line 1500 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]modestrFile mode, in C's string.
Exceptions
rb_eArgErrormodestr is broken.
Returns
A set of flags.

Definition at line 5873 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]modestrFile mode, in C's string.
Exceptions
rb_eArgErrormodestr is broken.
Returns
A set of flags.

Definition at line 6006 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]fptrAn IO to wait for reading.
Postcondition
The are bytes to be read.

Definition at line 1007 of file io.c.

◆ rb_io_set_nonblock()

void rb_io_set_nonblock ( rb_io_t fptr)

Sets an IO to a "nonblock mode".

This amends the way an IO operates so that instead of waiting for rooms for read/write, it returns errors. In case of multiplexed IO situations it can be vital for IO operations not to block. This is the key API to achieve that property.

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]fptrAn IO that is to ne nonblocking.
Postcondition
Descriptor that fptr describes is under nonblocking mode.

Definition at line 3121 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]ioAn IO.
[in]wAnother IO.
Return values
RUBY_QnilThere was no tied IO for writing for io.
otherwiseThe IO formerly tied to io.
Postcondition
io ties w for writing.

Definition at line 824 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]fptrTarget IO.
Returns
A stdio's file, created if absent.
Postcondition
fptr has its corresponding stdio's file.

Definition at line 8544 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]fptrIO to set the flag.
Exceptions
rb_eIOErrorfptr is not opened.
Postcondition
fptr is in sync mode.

Definition at line 6779 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]objObject in question.
Exceptions
rb_eFrozenErrorobj is frozen.
Returns
The passed obj

Definition at line 771 of file io.c.

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

Parameters
[in]ioAn IO object to wait.
[in]eventsSee above.
[in]timeoutTime, or numeric seconds since UNIX epoch.
Exceptions
rb_eIOErrorio is not open.
rb_eRangeErrortimeout is out of range.
rb_eSystemCallErrorselect(2) failed for some reason.
Return values
RUBY_QfalseOperation timed out.
OtherwiseActual events reached.

Definition at line 1294 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]fdThe file descriptor to wait.
Exceptions
rb_eIOErrorBad file descriptor.
Returns
0 or 1 (meaning unclear).
Postcondition
fd is ready for reading.

Definition at line 1351 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]fdThe file descriptor to wait.
Exceptions
rb_eIOErrorBad file descriptor.
Returns
0 or 1 (meaning unclear).

Definition at line 1385 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]stA stat.
Returns
Allocated new instance of rb_cStat.

Definition at line 547 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]fdThe file descriptor to wait.
[in]eventsA set of enum rb_io_event_t.
[in,out]tvTimeout.
Return values
0Operation timed out.
-1select(2) failed for some reason.
otherwiseA 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 1428 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]oflagsA set of O_ flags.
Returns
Corresponding set of FMODE_ flags.

◆ RBIMPL_ATTR_NORETURN()

RBIMPL_ATTR_NORETURN ( )

Utility function to raise rb_eEOFError.

Exceptions
rb_eEOFErrorEnd 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]fptrAn IO which can have pending reads.
Return values
0The IO is empty.
1There is something buffered.