Ruby  3.4.0dev (2024-11-22 revision 37a72b0150ec36b4ea27175039afc28c62207b0c)
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 
66 struct stat;
67 struct timeval;
68 
73 
82  RUBY_IO_READABLE = RB_WAITFD_IN,
83  RUBY_IO_WRITABLE = RB_WAITFD_OUT,
84  RUBY_IO_PRIORITY = RB_WAITFD_PRI,
85 };
86 
87 typedef enum rb_io_event rb_io_event_t;
88 
93 RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN()
95 
97  char *ptr; /* off + len <= capa */
98 
100  int off;
101 
103  int len;
104 
106  int capa;
107 } RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END();
108 
111 
113 /*
114  * enc enc2 read action write action
115  * NULL NULL force_encoding(default_external) write the byte sequence of str
116  * e1 NULL force_encoding(e1) convert str.encoding to e1
117  * e1 e2 convert from e2 to e1 convert str.encoding to e2
118  */
129  int ecflags;
138 };
139 
140 #ifndef HAVE_RB_IO_T
141 #define HAVE_RB_IO_T 1
143 struct rb_io {
145  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
147 
149  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
151 
154  int fd;
155 
158  int mode;
159 
161  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
162  rb_pid_t pid;
163 
165  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
166  int lineno;
167 
171 
173  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
174  void (*finalize)(struct rb_io*,int);
175 
177  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
179 
184  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
186 
194 
195  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
196  struct rb_io_encoding encs;
199  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
201 
206  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
208 
210  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
212 
219  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
221 
223  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
225 
230  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
232 
237  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
239 
247  RBIMPL_ATTR_DEPRECATED(("with no replacement"))
249 
255 };
256 #endif
257 
258 typedef struct rb_io rb_io_t;
259 
261 typedef struct rb_io_encoding rb_io_enc_t;
262 
270 #define FMODE_READABLE 0x00000001
271 
273 #define FMODE_WRITABLE 0x00000002
274 
276 #define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)
277 
287 #define FMODE_BINMODE 0x00000004
288 
294 #define FMODE_SYNC 0x00000008
295 
300 #define FMODE_TTY 0x00000010
301 
308 #define FMODE_DUPLEX 0x00000020
309 
315 #define FMODE_APPEND 0x00000040
316 
323 #define FMODE_CREATE 0x00000080
324 /* #define FMODE_NOREVLOOKUP 0x00000100 */
325 
331 #define FMODE_EXCL 0x00000400
332 
337 #define FMODE_TRUNC 0x00000800
338 
351 #define FMODE_TEXTMODE 0x00001000
360 #define FMODE_EXTERNAL 0x00010000
361 
362 /* #define FMODE_SIGNAL_ON_EPIPE 0x00020000 */
363 
368 #define FMODE_SETENC_BY_BOM 0x00100000
369 /* #define FMODE_UNIX 0x00200000 */
370 /* #define FMODE_INET 0x00400000 */
371 /* #define FMODE_INET6 0x00800000 */
372 
378 VALUE rb_io_open_descriptor(VALUE klass, int descriptor, int mode, VALUE path, VALUE timeout, struct rb_io_encoding *encoding);
379 
386 
396 #define RB_IO_POINTER(obj,fp) rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)
397 
402 #define GetOpenFile RB_IO_POINTER
403 
417 #define RB_IO_OPEN(obj, fp) do {\
418  (fp) = rb_io_make_open_file(obj);\
419 } while (0)
420 
425 #define MakeOpenFile RB_IO_OPEN
426 
438 rb_io_t *rb_io_make_open_file(VALUE obj);
439 
496 
511 FILE *rb_fdopen(int fd, const char *modestr);
512 
528 int rb_io_modestr_fmode(const char *modestr);
529 
543 int rb_io_modestr_oflags(const char *modestr);
544 
553 int rb_io_oflags_fmode(int oflags);
554 
566 void rb_io_check_writable(rb_io_t *fptr);
567 
569 void rb_io_check_readable(rb_io_t *fptr);
570 
590 
600 
610 int rb_io_fptr_finalize(rb_io_t *fptr);
611 
621 void rb_io_synchronized(rb_io_t *fptr);
622 
630 void rb_io_check_initialized(rb_io_t *fptr);
631 
639 void rb_io_check_closed(rb_io_t *fptr);
640 
652 
666 
691 
708 
743 void rb_io_set_nonblock(rb_io_t *fptr);
744 
750 
758 int rb_io_descriptor(VALUE io);
759 
764 int rb_io_mode(VALUE io);
765 
783 int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, int *fmode_p);
784 
852 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);
853 
854 /* :TODO: can this function be __attribute__((warn_unused_result)) or not? */
870 ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size);
871 
872 //RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_readable"))
882 int rb_io_wait_readable(int fd);
883 
884 //RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_writable"))
893 int rb_io_wait_writable(int fd);
894 
895 //RBIMPL_ATTR_DEPRECATED(("use rb_io_wait"))
910 int rb_wait_for_single_fd(int fd, int events, struct timeval *tv);
911 
920 
930 
950 VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout);
951 
982 VALUE rb_io_maybe_wait(int error, VALUE io, VALUE events, VALUE timeout);
983 
1001 int rb_io_maybe_wait_readable(int error, VALUE io, VALUE timeout);
1002 
1020 int rb_io_maybe_wait_writable(int error, VALUE io, VALUE timeout);
1021 
1023 /* compatibility for ruby 1.8 and older */
1024 #define rb_io_mode_flags(modestr) [<"rb_io_mode_flags() is obsolete; use rb_io_modestr_fmode()">]
1025 #define rb_io_modenum_flags(oflags) [<"rb_io_modenum_flags() is obsolete; use rb_io_oflags_fmode()">]
1038 
1046 void rb_eof_error(void);
1047 
1055 void rb_io_read_check(rb_io_t *fptr);
1056 
1066 int rb_io_read_pending(rb_io_t *fptr);
1067 
1074 VALUE rb_stat_new(const struct stat *st);
1075 
1076 /* gc.c */
1077 
1079 
1080 #endif /* RUBY_IO_H */
Defines RBIMPL_ATTR_CONST.
#define RBIMPL_ATTR_DEPRECATED(msg)
Wraps (or simulates) [[deprecated]]
Definition: deprecated.h:36
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.
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:6429
VALUE rb_stat_new(const struct stat *st)
Constructs an instance of rb_cStat from the passed information.
Definition: file.c:524
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
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)...
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:6562
int rb_io_mode(VALUE io)
Get the mode of the IO.
Definition: io.c:2912
rb_io_event
Type of events that an IO can wait.
Definition: io.h:81
@ RUBY_IO_READABLE
IO::READABLE
Definition: io.h:82
@ RUBY_IO_PRIORITY
IO::PRIORITY
Definition: io.h:84
@ RUBY_IO_WRITABLE
IO::WRITABLE
Definition: io.h:83
void rb_io_check_byte_readable(rb_io_t *fptr)
Asserts that an IO is opened for byte-based reading.
Definition: io.c:1015
void rb_io_check_readable(rb_io_t *fptr)
Just another name of rb_io_check_byte_readable.
Definition: io.c:1024
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:6711
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:9343
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:1585
RBIMPL_ATTR_NORETURN() void rb_eof_error(void)
Utility function to raise rb_eEOFError.
int rb_io_descriptor(VALUE io)
Returns an integer representing the numeric file descriptor for io.
Definition: io.c:2892
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:1644
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:1603
VALUE rb_eIOTimeoutError
Indicates that a timeout has occurred while performing an IO operation.
Definition: io.c:190
VALUE rb_io_path(VALUE io)
Returns the path for the given IO.
Definition: io.c:2966
void rb_io_check_initialized(rb_io_t *fptr)
Asserts that the passed IO is initialised.
Definition: io.c:788
int rb_io_fptr_finalize(rb_io_t *fptr)
Destroys the given IO.
Definition: io.c:5646
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:5825
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:7044
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:2009
void rb_io_check_char_readable(rb_io_t *fptr)
Asserts that an IO is opened for character-based reading.
Definition: io.c:996
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:3418
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:6836
RBIMPL_ATTR_PURE() int rb_io_read_pending(rb_io_t *fptr)
Queries if the passed IO has any pending reads.
int rb_io_wait_writable(int fd)
Blocks until the passed file descriptor gets writable.
Definition: io.c:1542
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:9214
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:1659
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:1508
void rb_io_synchronized(rb_io_t *fptr)
Sets FMODE_SYNC.
Definition: io.c:7331
VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout)
Blocks until the passed IO is ready for the passed events.
Definition: io.c:1447
Defines RBIMPL_ATTR_NORETURN.
Defines #RBIMPL_ATTR_PACKED_STRUCT_BEGIN, #RBIMPL_ATTR_PACKED_STRUCT_END, #RBIMPL_ATTR_PACKED_STRUCT_...
Defines RBIMPL_ATTR_PURE.
Decomposed encoding flags (e.g.
Definition: io.h:119
int ecflags
Flags.
Definition: io.h:129
VALUE ecopts
Flags as Ruby hash.
Definition: io.h:137
rb_encoding * enc2
External encoding.
Definition: io.h:123
rb_encoding * enc
Internal encoding.
Definition: io.h:121
IO buffers.
Definition: io.h:94
char * ptr
Pointer to the underlying memory region, of at least capa bytes.
Definition: io.h:97
int off
Offset inside of ptr.
Definition: io.h:100
int len
Length of the buffer.
Definition: io.h:103
int capa
Designed capacity of the buffer.
Definition: io.h:106
Ruby's IO, metadata and buffers.
Definition: io.h:143
int mode
mode flags: FMODE_XXXs
Definition: io.h:158
rb_io_buffer_t wbuf
Write buffer.
Definition: io.h:178
void(* finalize)(struct rb_io *, int)
finalize proc
Definition: io.h:174
rb_econv_t * readconv
Encoding converter used when reading from this IO.
Definition: io.h:200
rb_econv_t * writeconv
Encoding converter used when writing to this IO.
Definition: io.h:211
struct rb_io_encoding encs
Decomposed encoding flags.
Definition: io.h:196
VALUE self
The IO's Ruby level counterpart.
Definition: io.h:146
VALUE write_lock
This is a Ruby level mutex.
Definition: io.h:248
VALUE timeout
The timeout associated with this IO when performing blocking operations.
Definition: io.h:254
FILE * stdio_file
stdio ptr for read/write, if available.
Definition: io.h:150
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:238
VALUE tied_io_for_writing
Duplex IO object, if set.
Definition: io.h:193
int writeconv_initialized
Whether rb_io_t::writeconv is already set up.
Definition: io.h:224
int fd
file descriptor.
Definition: io.h:154
rb_io_buffer_t rbuf
(Byte) read buffer.
Definition: io.h:185
int lineno
number of lines read
Definition: io.h:166
VALUE writeconv_asciicompat
This is, when set, an instance of rb_cString which holds the "common" encoding.
Definition: io.h:220
rb_io_buffer_t cbuf
rb_io_ungetc() destination.
Definition: io.h:207
rb_pid_t pid
child's pid (for pipes)
Definition: io.h:162
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:231
VALUE pathv
pathname for file
Definition: io.h:170
Defines VALUE and ID.
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40