Ruby 3.5.0dev (2025-06-06 revision 347e581a4cbe2bbf7c13532038f2a68b0b37099a)
io.h
Go to the documentation of this file.
1#ifndef RUBY_IO_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RUBY_IO_H 1
13#include "ruby/internal/config.h"
14
15#include <stdio.h>
16#include "ruby/encoding.h"
17
18#if defined(HAVE_STDIO_EXT_H)
19#include <stdio_ext.h>
20#endif
21
22#include <errno.h>
23
25#if defined(HAVE_POLL)
26# ifdef _AIX
27# define reqevents events
28# define rtnevents revents
29# endif
30# include <poll.h>
31# ifdef _AIX
32# undef reqevents
33# undef rtnevents
34# undef events
35# undef revents
36# endif
37# define RB_WAITFD_IN POLLIN
38# if defined(POLLPRI)
39# define RB_WAITFD_PRI POLLPRI
40# else
41# define RB_WAITFD_PRI 0
42# endif
43# define RB_WAITFD_OUT POLLOUT
44#else
45# define RB_WAITFD_IN 0x001
46# define RB_WAITFD_PRI 0x002
47# define RB_WAITFD_OUT 0x004
48#endif
56#include "ruby/internal/value.h"
57
58// IO#wait, IO#wait_readable, IO#wait_writable, IO#wait_priority are defined by this implementation.
59#define RUBY_IO_WAIT_METHODS
60
61// Used as the default timeout argument to `rb_io_wait` to use the `IO#timeout` value.
62#define RUBY_IO_TIMEOUT_DEFAULT Qnil
63
65
66struct stat;
67struct timeval;
68
69#if defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC)
70# define RUBY_USE_STATX 0
71#elif defined(HAVE_STRUCT_STATX_STX_BTIME)
72# define RUBY_USE_STATX 1
73struct statx;
74#else
75# define RUBY_USE_STATX 0
76#endif
77
78#if RUBY_USE_STATX
79typedef struct statx rb_io_stat_data;
80#else
81typedef struct stat rb_io_stat_data;
82#endif
83
88
97 RUBY_IO_READABLE = RB_WAITFD_IN,
98 RUBY_IO_WRITABLE = RB_WAITFD_OUT,
99 RUBY_IO_PRIORITY = RB_WAITFD_PRI,
100};
101
102typedef enum rb_io_event rb_io_event_t;
103
108RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN()
110
112 char *ptr; /* off + len <= capa */
113
115 int off;
116
118 int len;
119
121 int capa;
122} RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END();
123
126
128/*
129 * enc enc2 read action write action
130 * NULL NULL force_encoding(default_external) write the byte sequence of str
131 * e1 NULL force_encoding(e1) convert str.encoding to e1
132 * e1 e2 convert from e2 to e1 convert str.encoding to e2
133 */
154
162#define FMODE_READABLE 0x00000001
163
165#define FMODE_WRITABLE 0x00000002
166
168#define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)
169
179#define FMODE_BINMODE 0x00000004
180
186#define FMODE_SYNC 0x00000008
187
192#define FMODE_TTY 0x00000010
193
200#define FMODE_DUPLEX 0x00000020
201
207#define FMODE_APPEND 0x00000040
208
215#define FMODE_CREATE 0x00000080
216/* #define FMODE_NOREVLOOKUP 0x00000100 */
217
223#define FMODE_EXCL 0x00000400
224
229#define FMODE_TRUNC 0x00000800
230
243#define FMODE_TEXTMODE 0x00001000
252#define FMODE_EXTERNAL 0x00010000
253
254/* #define FMODE_SIGNAL_ON_EPIPE 0x00020000 */
255
260#define FMODE_SETENC_BY_BOM 0x00100000
261/* #define FMODE_UNIX 0x00200000 */
262/* #define FMODE_INET 0x00400000 */
263/* #define FMODE_INET6 0x00800000 */
264
267enum rb_io_mode {
268 RUBY_IO_MODE_EXTERNAL = FMODE_EXTERNAL,
269
270 RUBY_IO_MODE_READABLE = FMODE_READABLE,
271 RUBY_IO_MODE_WRITABLE = FMODE_WRITABLE,
272 RUBY_IO_MODE_READABLE_WRITABLE = (RUBY_IO_MODE_READABLE|RUBY_IO_MODE_WRITABLE),
273
274 RUBY_IO_MODE_BINARY = FMODE_BINMODE,
275 RUBY_IO_MODE_TEXT = FMODE_TEXTMODE,
276 RUBY_IO_MODE_TEXT_SET_ENCODING_FROM_BOM = FMODE_SETENC_BY_BOM,
277
278 RUBY_IO_MODE_SYNCHRONISED = FMODE_SYNC,
279
280 RUBY_IO_MODE_TTY = FMODE_TTY,
281
282 RUBY_IO_MODE_DUPLEX = FMODE_DUPLEX,
283
284 RUBY_IO_MODE_APPEND = FMODE_APPEND,
285 RUBY_IO_MODE_CREATE = FMODE_CREATE,
286 RUBY_IO_MODE_EXCLUSIVE = FMODE_EXCL,
287 RUBY_IO_MODE_TRUNCATE = FMODE_TRUNC,
288};
289
290typedef enum rb_io_mode rb_io_mode_t;
291
292#ifndef HAVE_RB_IO_T
293#define HAVE_RB_IO_T 1
295struct rb_io {
297 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
299
301 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
303
306 int fd;
307
309 RBIMPL_ATTR_DEPRECATED(("rb_io_mode"))
310 enum rb_io_mode mode;
311
313 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
314 rb_pid_t pid;
315
317 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
319
323
325 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
326 void (*finalize)(struct rb_io*,int);
327
329 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
331
336 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
338
346
347 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
351 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
353
358 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
360
362 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
364
371 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
373
375 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
377
382 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
384
389 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
391
399 RBIMPL_ATTR_DEPRECATED(("with no replacement"))
401
407};
408#endif
409
410typedef struct rb_io rb_io_t;
411
414
418VALUE rb_io_open_descriptor(VALUE klass, int descriptor, int mode, VALUE path, VALUE timeout, struct rb_io_encoding *encoding);
419
426
436#define RB_IO_POINTER(obj,fp) rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)
437
442#define GetOpenFile RB_IO_POINTER
443
457#define RB_IO_OPEN(obj, fp) do {\
458 (fp) = rb_io_make_open_file(obj);\
459} while (0)
460
465#define MakeOpenFile RB_IO_OPEN
466
478rb_io_t *rb_io_make_open_file(VALUE obj);
479
536
551FILE *rb_fdopen(int fd, const char *modestr);
552
568enum rb_io_mode rb_io_modestr_fmode(const char *modestr);
569
583int rb_io_modestr_oflags(const char *modestr);
584
593int rb_io_oflags_fmode(int oflags);
594
606void rb_io_check_writable(rb_io_t *fptr);
607
609void rb_io_check_readable(rb_io_t *fptr);
610
630
640
651
661void rb_io_synchronized(rb_io_t *fptr);
662
671
679void rb_io_check_closed(rb_io_t *fptr);
680
692
706
731
748
783void rb_io_set_nonblock(rb_io_t *fptr);
784
790
798int rb_io_descriptor(VALUE io);
799
804int rb_io_mode(VALUE io);
805
823int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, enum rb_io_mode *fmode_p);
824
892void rb_io_extract_modeenc(VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, enum rb_io_mode *fmode_p, rb_io_enc_t *convconfig_p);
893
894/* :TODO: can this function be __attribute__((warn_unused_result)) or not? */
910ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size);
911
912//RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_readable"))
922int rb_io_wait_readable(int fd);
923
924//RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_writable"))
933int rb_io_wait_writable(int fd);
934
935//RBIMPL_ATTR_DEPRECATED(("use rb_io_wait"))
950int rb_wait_for_single_fd(int fd, int events, struct timeval *tv);
951
960
970
991
1022VALUE rb_io_maybe_wait(int error, VALUE io, VALUE events, VALUE timeout);
1023
1041int rb_io_maybe_wait_readable(int error, VALUE io, VALUE timeout);
1042
1060int rb_io_maybe_wait_writable(int error, VALUE io, VALUE timeout);
1061
1063/* compatibility for ruby 1.8 and older */
1064#define rb_io_mode_flags(modestr) [<"rb_io_mode_flags() is obsolete; use rb_io_modestr_fmode()">]
1065#define rb_io_modenum_flags(oflags) [<"rb_io_modenum_flags() is obsolete; use rb_io_oflags_fmode()">]
1078
1086void rb_eof_error(void);
1087
1095void rb_io_read_check(rb_io_t *fptr);
1096
1106int rb_io_read_pending(rb_io_t *fptr);
1107
1114VALUE rb_stat_new(const struct stat *st);
1115
1116#if RUBY_USE_STATX
1123VALUE rb_statx_new(const rb_io_stat_data *st);
1124#else
1125# define rb_statx_new rb_stat_new
1126#endif
1127
1128/* gc.c */
1129
1131
1132#endif /* RUBY_IO_H */
Defines RBIMPL_ATTR_CONST.
#define RBIMPL_ATTR_CONST()
Wraps (or simulates) __attribute__((const))
Definition const.h:36
#define RBIMPL_ATTR_DEPRECATED(msg)
Wraps (or simulates) [[deprecated]]
Definition deprecated.h:64
Tweaking visibility of C variables/functions.
#define RUBY_EXTERN
Declaration of externally visible global variables.
Definition dllexport.h:45
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
Encoding relates APIs.
#define FMODE_READABLE
The IO is opened for reading.
Definition io.h:162
enum rb_io_mode rb_io_modestr_fmode(const char *modestr)
Maps a file mode string (that rb_file_open() takes) into a mixture of FMODE_ flags.
Definition io.c:6465
VALUE rb_io_get_io(VALUE io)
Identical to rb_io_check_io(), except it raises exceptions on conversion failures.
Definition io.c:811
VALUE rb_io_timeout(VALUE io)
Get the timeout associated with the specified io object.
Definition io.c:857
VALUE rb_io_taint_check(VALUE obj)
Definition io.c:781
void rb_io_read_check(rb_io_t *fptr)
Blocks until there is a pending read in the passed IO.
Definition io.c:1069
int rb_io_modestr_oflags(const char *modestr)
Identical to rb_io_modestr_fmode(), except it returns a mixture of O_ flags.
Definition io.c:6598
#define FMODE_SETENC_BY_BOM
This flag amends the encoding of the IO so that the BOM of the contents of the IO takes effect.
Definition io.h:260
rb_io_event
Type of events that an IO can wait.
Definition io.h:96
@ RUBY_IO_READABLE
IO::READABLE
Definition io.h:97
@ RUBY_IO_PRIORITY
IO::PRIORITY
Definition io.h:99
@ RUBY_IO_WRITABLE
IO::WRITABLE
Definition io.h:98
#define FMODE_EXTERNAL
This flag means that an IO object is wrapping an "external" file descriptor, which is owned by someth...
Definition io.h:252
void rb_io_check_byte_readable(rb_io_t *fptr)
Asserts that an IO is opened for byte-based reading.
Definition io.c:1015
#define FMODE_TTY
The IO is a TTY.
Definition io.h:192
#define FMODE_CREATE
The IO is opened for creating.
Definition io.h:215
void rb_io_check_readable(rb_io_t *fptr)
Just another name of rb_io_check_byte_readable.
Definition io.c:1024
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.
Definition io.c:1592
FILE * rb_fdopen(int fd, const char *modestr)
Identical to rb_io_stdio_file(), except it takes file descriptors instead of Ruby's IO.
Definition io.c:7081
int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, enum rb_io_mode *fmode_p)
This function breaks down the option hash that IO#initialize takes into components.
Definition io.c:6747
int rb_io_descriptor(VALUE io)
Returns an integer representing the numeric file descriptor for io.
Definition io.c:2899
#define FMODE_WRITABLE
The IO is opened for writing.
Definition io.h:165
FILE * rb_io_stdio_file(rb_io_t *fptr)
Finds or creates a stdio's file structure from a Ruby's one.
Definition io.c:9415
#define FMODE_APPEND
The IO is opened for appending.
Definition io.h:207
#define FMODE_DUPLEX
Ruby eventually detects that the IO is bidirectional.
Definition io.h:200
#define FMODE_BINMODE
The IO is in "binary mode".
Definition io.h:179
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.
Definition io.c:1651
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:1610
VALUE rb_eIOTimeoutError
Indicates that a timeout has occurred while performing an IO operation.
Definition io.c:190
#define FMODE_SYNC
The IO is in "sync mode".
Definition io.h:186
VALUE rb_io_path(VALUE io)
Returns the path for the given IO.
Definition io.c:2973
void rb_io_extract_modeenc(VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, enum rb_io_mode *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:6872
void rb_io_check_initialized(rb_io_t *fptr)
Asserts that the passed IO is initialised.
Definition io.c:788
#define FMODE_EXCL
This flag amends the effect of FMODE_CREATE, so that if there already is a file at the given path the...
Definition io.h:223
#define FMODE_TEXTMODE
The IO is in "text mode".
Definition io.h:243
int rb_io_fptr_finalize(rb_io_t *fptr)
Destroys the given IO.
Definition io.c:5675
VALUE rb_io_check_io(VALUE io)
Try converting an object to its IO representation using its to_io method, if any.
Definition io.c:817
VALUE rb_io_closed_p(VALUE io)
Returns whether or not the underlying IO is closed.
Definition io.c:5861
VALUE rb_io_set_timeout(VALUE io, VALUE timeout)
Set the timeout associated with the specified io object.
Definition io.c:886
ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size)
Buffered write to the passed IO.
Definition io.c:2016
void rb_io_check_char_readable(rb_io_t *fptr)
Asserts that an IO is opened for character-based reading.
Definition io.c:996
#define FMODE_TRUNC
This flag amends the effect of FMODE_CREATE, so that if there already is a file at the given path it ...
Definition io.h:229
VALUE rb_io_get_write_io(VALUE io)
Queries the tied IO for writing.
Definition io.c:823
void rb_io_set_nonblock(rb_io_t *fptr)
Instructs the OS to put its internal file structure into "nonblocking mode".
Definition io.c:3425
int rb_io_wait_writable(int fd)
Blocks until the passed file descriptor gets writable.
Definition io.c:1549
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 io.c:9281
VALUE rb_io_set_write_io(VALUE io, VALUE w)
Assigns the tied IO for writing.
Definition io.c:834
void rb_io_check_writable(rb_io_t *fptr)
Asserts that an IO is opened for writing.
Definition io.c:1048
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.
Definition io.c:1666
void rb_io_check_closed(rb_io_t *fptr)
This badly named function asserts that the passed IO is open.
Definition io.c:796
int rb_io_wait_readable(int fd)
Blocks until the passed file descriptor gets readable.
Definition io.c:1515
void rb_io_synchronized(rb_io_t *fptr)
Sets FMODE_SYNC.
Definition io.c:7368
VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout)
Blocks until the passed IO is ready for the passed events.
Definition io.c:1454
Defines RBIMPL_ATTR_NORETURN.
#define RBIMPL_ATTR_NORETURN()
Wraps (or simulates) [[noreturn]]
Definition noreturn.h:38
Defines RBIMPL_ATTR_PACKED_STRUCT_BEGIN, RBIMPL_ATTR_PACKED_STRUCT_END, RBIMPL_ATTR_PACKED_STRUCT_UNA...
Defines RBIMPL_ATTR_PURE.
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure))
Definition pure.h:33
Decomposed encoding flags (e.g.
Definition io.h:134
int ecflags
Flags.
Definition io.h:144
VALUE ecopts
Flags as Ruby hash.
Definition io.h:152
rb_encoding * enc2
External encoding.
Definition io.h:138
rb_encoding * enc
Internal encoding.
Definition io.h:136
IO buffers.
Definition io.h:109
char * ptr
Pointer to the underlying memory region, of at least capa bytes.
Definition io.h:112
int off
Offset inside of ptr.
Definition io.h:115
int len
Length of the buffer.
Definition io.h:118
int capa
Designed capacity of the buffer.
Definition io.h:121
Ruby's IO, metadata and buffers.
Definition io.h:295
rb_io_buffer_t wbuf
Write buffer.
Definition io.h:330
enum rb_io_mode mode
mode flags: FMODE_XXXs
Definition io.h:310
void(* finalize)(struct rb_io *, int)
finalize proc
Definition io.h:326
rb_econv_t * readconv
Encoding converter used when reading from this IO.
Definition io.h:352
rb_econv_t * writeconv
Encoding converter used when writing to this IO.
Definition io.h:363
struct rb_io_encoding encs
Decomposed encoding flags.
Definition io.h:348
VALUE self
The IO's Ruby level counterpart.
Definition io.h:298
VALUE write_lock
This is a Ruby level mutex.
Definition io.h:400
VALUE timeout
The timeout associated with this IO when performing blocking operations.
Definition io.h:406
FILE * stdio_file
stdio ptr for read/write, if available.
Definition io.h:302
VALUE writeconv_pre_ecopts
Value of ::rb_io_t::rb_io_enc_t::ecopts stored right before initialising rb_io_t::writeconv.
Definition io.h:390
VALUE tied_io_for_writing
Duplex IO object, if set.
Definition io.h:345
int writeconv_initialized
Whether rb_io_t::writeconv is already set up.
Definition io.h:376
int fd
file descriptor.
Definition io.h:306
rb_io_buffer_t rbuf
(Byte) read buffer.
Definition io.h:337
int lineno
number of lines read
Definition io.h:318
VALUE writeconv_asciicompat
This is, when set, an instance of rb_cString which holds the "common" encoding.
Definition io.h:372
rb_io_buffer_t cbuf
rb_io_ungetc() destination.
Definition io.h:359
rb_pid_t pid
child's pid (for pipes)
Definition io.h:314
int writeconv_pre_ecflags
Value of ::rb_io_t::rb_io_enc_t::ecflags stored right before initialising rb_io_t::writeconv.
Definition io.h:383
VALUE pathv
pathname for file
Definition io.h:322
Defines VALUE and ID.
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40