Ruby: include/ruby/io.h Source File

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

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
51#include "ruby/internal/attr/const.h"
52#include "ruby/internal/attr/pure.h"
53#include "ruby/internal/attr/noreturn.h"
54#include "ruby/internal/dllexport.h"
55#include "ruby/internal/value.h"
56#include "ruby/backward/2/attributes.h" /* PACKED_STRUCT_UNALIGNED */
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
64 RBIMPL_SYMBOL_EXPORT_BEGIN()
65
66struct stat;
67struct timeval;
68
72 RUBY_EXTERN VALUE rb_eIOTimeoutError;
73
81typedef enum {
82 RUBY_IO_READABLE = RB_WAITFD_IN,
83 RUBY_IO_WRITABLE = RB_WAITFD_OUT,
84 RUBY_IO_PRIORITY = RB_WAITFD_PRI,
85} rb_io_event_t;
86
91PACKED_STRUCT_UNALIGNED(struct rb_io_buffer_t {
92
94 char *ptr; /* off + len <= capa */
95
97 int off;
98
100 int len;
101
103 int capa;
104});
105
107 typedef struct rb_io_buffer_t rb_io_buffer_t;
108
110/*
111 * enc enc2 read action write action
112 * NULL NULL force_encoding(default_external) write the byte sequence of str
113 * e1 NULL force_encoding(e1) convert str.encoding to e1
114 * e1 e2 convert from e2 to e1 convert str.encoding to e2
115 */
116 struct rb_io_enc_t {
118 rb_encoding *enc;
120 rb_encoding *enc2;
126 int ecflags;
134 VALUE ecopts;
135};
136
138 typedef struct rb_io_t {
139
141 VALUE self;
142
144 FILE *stdio_file;
145
147 int fd;
148
150 int mode;
151
153 rb_pid_t pid;
154
156 int lineno;
157
159 VALUE pathv;
160
162 void (*finalize)(struct rb_io_t*,int);
163
165 rb_io_buffer_t wbuf;
166
171 rb_io_buffer_t rbuf;
172
178 VALUE tied_io_for_writing;
179
180 struct rb_io_enc_t encs;
183 rb_econv_t *readconv;
184
189 rb_io_buffer_t cbuf;
190
192 rb_econv_t *writeconv;
193
200 VALUE writeconv_asciicompat;
201
203 int writeconv_initialized;
204
209 int writeconv_pre_ecflags;
210
215 VALUE writeconv_pre_ecopts;
216
224 VALUE write_lock;
225
229 VALUE timeout;
230} rb_io_t;
231
233 typedef struct rb_io_enc_t rb_io_enc_t;
234
242#define HAVE_RB_IO_T 1
243
251#define FMODE_READABLE 0x00000001
252
254#define FMODE_WRITABLE 0x00000002
255
257#define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)
258
268#define FMODE_BINMODE 0x00000004
269
275#define FMODE_SYNC 0x00000008
276
281#define FMODE_TTY 0x00000010
282
289#define FMODE_DUPLEX 0x00000020
290
296#define FMODE_APPEND 0x00000040
297
304#define FMODE_CREATE 0x00000080
305/* #define FMODE_NOREVLOOKUP 0x00000100 */
306
312#define FMODE_EXCL 0x00000400
313
318#define FMODE_TRUNC 0x00000800
319
332#define FMODE_TEXTMODE 0x00001000
333/* #define FMODE_PREP 0x00010000 */
334/* #define FMODE_SIGNAL_ON_EPIPE 0x00020000 */
335
340#define FMODE_SETENC_BY_BOM 0x00100000
341/* #define FMODE_UNIX 0x00200000 */
342/* #define FMODE_INET 0x00400000 */
343/* #define FMODE_INET6 0x00800000 */
344
356#define RB_IO_POINTER(obj,fp) rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)
357
362#define GetOpenFile RB_IO_POINTER
363
377#define RB_IO_OPEN(obj, fp) do {\
378 (fp) = rb_io_make_open_file(obj);\
379} while (0)
380
385#define MakeOpenFile RB_IO_OPEN
386
398 rb_io_t *rb_io_make_open_file(VALUE obj);
399
455 FILE *rb_io_stdio_file(rb_io_t *fptr);
456
471 FILE *rb_fdopen(int fd, const char *modestr);
472
488int rb_io_modestr_fmode(const char *modestr);
489
503int rb_io_modestr_oflags(const char *modestr);
504
505 RBIMPL_ATTR_CONST()
513int rb_io_oflags_fmode(int oflags);
514
526void rb_io_check_writable(rb_io_t *fptr);
527
529void rb_io_check_readable(rb_io_t *fptr);
530
549void rb_io_check_char_readable(rb_io_t *fptr);
550
559void rb_io_check_byte_readable(rb_io_t *fptr);
560
570int rb_io_fptr_finalize(rb_io_t *fptr);
571
581void rb_io_synchronized(rb_io_t *fptr);
582
590void rb_io_check_initialized(rb_io_t *fptr);
591
599void rb_io_check_closed(rb_io_t *fptr);
600
611 VALUE rb_io_get_io(VALUE io);
612
625 VALUE rb_io_check_io(VALUE io);
626
650 VALUE rb_io_get_write_io(VALUE io);
651
667 VALUE rb_io_set_write_io(VALUE io, VALUE w);
668
703void rb_io_set_nonblock(rb_io_t *fptr);
704
712int rb_io_descriptor(VALUE io);
713
731int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, int *fmode_p);
732
800void rb_io_extract_modeenc(VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, int *fmode_p, rb_io_enc_t *convconfig_p);
801
802/* :TODO: can this function be __attribute__((warn_unused_result)) or not? */
818ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size);
819
820//RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_readable"))
830int rb_io_wait_readable(int fd);
831
832//RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_writable"))
841int rb_io_wait_writable(int fd);
842
843//RBIMPL_ATTR_DEPRECATED(("use rb_io_wait"))
858int rb_wait_for_single_fd(int fd, int events, struct timeval *tv);
859
867 VALUE rb_io_timeout(VALUE io);
868
877 VALUE rb_io_set_timeout(VALUE io, VALUE timeout);
878
898 VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout);
899
930 VALUE rb_io_maybe_wait(int error, VALUE io, VALUE events, VALUE timeout);
931
946int rb_io_maybe_wait_readable(int error, VALUE io, VALUE timeout);
947
962int rb_io_maybe_wait_writable(int error, VALUE io, VALUE timeout);
963
965/* compatibility for ruby 1.8 and older */
966#define rb_io_mode_flags(modestr) [<"rb_io_mode_flags() is obsolete; use rb_io_modestr_fmode()">]
967#define rb_io_modenum_flags(oflags) [<"rb_io_modenum_flags() is obsolete; use rb_io_oflags_fmode()">]
979 VALUE rb_io_taint_check(VALUE obj);
980
981 RBIMPL_ATTR_NORETURN()
988void rb_eof_error(void);
989
997void rb_io_read_check(rb_io_t *fptr);
998
999 RBIMPL_ATTR_PURE()
1008int rb_io_read_pending(rb_io_t *fptr);
1009
1016 VALUE rb_stat_new(const struct stat *st);
1017
1018/* gc.c */
1019
1020 RBIMPL_SYMBOL_EXPORT_END()
1021
1022#endif /* RUBY_IO_H */
const.h
Defines RBIMPL_ATTR_CONST.
RBIMPL_ATTR_CONST
#define RBIMPL_ATTR_CONST()
Wraps (or simulates) __attribute__((const))
Definition const.h:36
dllexport.h
Tweaking visibility of C variables/functions.
RUBY_EXTERN
#define RUBY_EXTERN
Declaration of externally visible global variables.
Definition dllexport.h:47
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:106
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:97
encoding.h
Encoding relates APIs.
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.
Definition io.c:6367
rb_stat_new
VALUE rb_stat_new(const struct stat *st)
Constructs an instance of rb_cStat from the passed information.
Definition file.c:514
rb_io_get_io
VALUE rb_io_get_io(VALUE io)
Identical to rb_io_check_io(), except it raises exceptions on conversion failures.
Definition io.c:797
rb_io_timeout
VALUE rb_io_timeout(VALUE io)
Get the timeout associated with the specified io object.
Definition io.c:843
rb_io_taint_check
VALUE rb_io_taint_check(VALUE obj)
Definition io.c:767
rb_io_read_check
void rb_io_read_check(rb_io_t *fptr)
Blocks until there is a pending read in the passed IO.
Definition io.c:1051
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.
Definition io.c:6500
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.
Definition io.c:997
rb_io_check_readable
void rb_io_check_readable(rb_io_t *fptr)
Just another name of rb_io_check_byte_readable.
Definition io.c:1006
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.
Definition io.c:6649
rb_io_t
struct rb_io_t rb_io_t
Ruby's IO, metadata and buffers.
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)...
Definition io.c:6424
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.
Definition io.c:1558
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.
Definition io.c:6970
rb_io_descriptor
int rb_io_descriptor(VALUE io)
Returns an integer representing the numeric file descriptor for io.
Definition io.c:2869
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.
Definition io.c:9249
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.
Definition io.c:1617
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
rb_eIOTimeoutError
VALUE rb_eIOTimeoutError
Indicates that a timeout has occurred while performing an IO operation.
Definition io.c:183
rb_io_check_initialized
void rb_io_check_initialized(rb_io_t *fptr)
Asserts that the passed IO is initialised.
Definition io.c:774
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.
Definition io.c:803
rb_io_set_timeout
VALUE rb_io_set_timeout(VALUE io, VALUE timeout)
Set the timeout associated with the specified io object.
Definition io.c:869
rb_io_bufwrite
ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size)
Buffered write to the passed IO.
Definition io.c:1980
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.
Definition io.c:978
rb_io_read_pending
int rb_io_read_pending(rb_io_t *fptr)
Queries if the passed IO has any pending reads.
Definition io.c:1042
rb_io_get_write_io
VALUE rb_io_get_write_io(VALUE io)
Queries the tied IO for writing.
Definition io.c:809
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".
Definition io.c:3379
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_wait_writable
int rb_io_wait_writable(int fd)
Blocks until the passed file descriptor gets writable.
Definition io.c:1515
rb_io_set_write_io
VALUE rb_io_set_write_io(VALUE io, VALUE w)
Assigns the tied IO for writing.
Definition io.c:820
rb_io_check_writable
void rb_io_check_writable(rb_io_t *fptr)
Asserts that an IO is opened for writing.
Definition io.c:1030
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.
Definition io.c:1630
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
rb_eof_error
void rb_eof_error(void)
Utility function to raise rb_eEOFError.
Definition io.c:761
rb_io_event_t
rb_io_event_t
Type of events that an IO can wait.
Definition io.h:81
RUBY_IO_READABLE
@ RUBY_IO_READABLE
IO::READABLE
Definition io.h:82
RUBY_IO_PRIORITY
@ RUBY_IO_PRIORITY
IO::PRIORITY
Definition io.h:84
RUBY_IO_WRITABLE
@ RUBY_IO_WRITABLE
IO::WRITABLE
Definition io.h:83
rb_io_wait_readable
int rb_io_wait_readable(int fd)
Blocks until the passed file descriptor gets readable.
Definition io.c:1481
rb_io_synchronized
void rb_io_synchronized(rb_io_t *fptr)
Sets FMODE_SYNC.
Definition io.c:7273
rb_io_wait
VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout)
Blocks until the passed IO is ready for the passed events.
Definition io.c:1420
noreturn.h
Defines RBIMPL_ATTR_NORETURN.
RBIMPL_ATTR_NORETURN
#define RBIMPL_ATTR_NORETURN()
Wraps (or simulates) [[noreturn]]
Definition noreturn.h:38
pure.h
Defines RBIMPL_ATTR_PURE.
RBIMPL_ATTR_PURE
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure))
Definition pure.h:33
__sFILE
Definition vsnprintf.c:160
OnigEncodingTypeST
Definition onigmo.h:160
rb_econv_t
Definition transcode.c:130
rb_io_buffer_t
IO buffers.
Definition io.h:104
rb_io_enc_t
Decomposed encoding flags (e.g.
Definition io.h:116
rb_io_enc_t::ecflags
int ecflags
Flags.
Definition io.h:126
rb_io_enc_t::enc2
rb_encoding * enc2
External encoding.
Definition io.h:120
rb_io_enc_t::ecopts
VALUE ecopts
Flags as Ruby hash.
Definition io.h:134
rb_io_enc_t::enc
rb_encoding * enc
Internal encoding.
Definition io.h:118
rb_io_t
Ruby's IO, metadata and buffers.
Definition io.h:138
rb_io_t::fd
int fd
file descriptor.
Definition io.h:147
rb_io_t::lineno
int lineno
number of lines read
Definition io.h:156
rb_io_t::writeconv
rb_econv_t * writeconv
Encoding converter used when writing to this IO.
Definition io.h:192
rb_io_t::pid
rb_pid_t pid
child's pid (for pipes)
Definition io.h:153
rb_io_t::wbuf
rb_io_buffer_t wbuf
Write buffer.
Definition io.h:165
rb_io_t::readconv
rb_econv_t * readconv
Encoding converter used when reading from this IO.
Definition io.h:183
rb_io_t::writeconv_asciicompat
VALUE writeconv_asciicompat
This is, when set, an instance of rb_cString which holds the "common" encoding.
Definition io.h:200
rb_io_t::stdio_file
FILE * stdio_file
stdio ptr for read/write, if available.
Definition io.h:144
rb_io_t::writeconv_initialized
int writeconv_initialized
Whether rb_io_t::writeconv is already set up.
Definition io.h:203
rb_io_t::pathv
VALUE pathv
pathname for file
Definition io.h:159
rb_io_t::mode
int mode
mode flags: FMODE_XXXs
Definition io.h:150
rb_io_t::writeconv_pre_ecflags
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:209
rb_io_t::encs
struct rb_io_enc_t encs
Decomposed encoding flags.
Definition io.h:180
rb_io_t::write_lock
VALUE write_lock
This is a Ruby level mutex.
Definition io.h:224
rb_io_t::cbuf
rb_io_buffer_t cbuf
rb_io_ungetc() destination.
Definition io.h:189
rb_io_t::self
VALUE self
The IO's Ruby level counterpart.
Definition io.h:141
rb_io_t::writeconv_pre_ecopts
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:215
rb_io_t::tied_io_for_writing
VALUE tied_io_for_writing
Duplex IO object, if set.
Definition io.h:178
rb_io_t::finalize
void(* finalize)(struct rb_io_t *, int)
finalize proc
Definition io.h:162
rb_io_t::timeout
VALUE timeout
The timeout associated with this IO when performing blocking operations.
Definition io.h:229
rb_io_t::rbuf
rb_io_buffer_t rbuf
(Byte) read buffer.
Definition io.h:171
timeval
Definition missing.h:63
value.h
Defines VALUE and ID.
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40