Ruby  3.1.4p223 (2023-03-30 revision HEAD)
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 # define RB_WAITFD_PRI POLLPRI
39 # define RB_WAITFD_OUT POLLOUT
40 #else
41 # define RB_WAITFD_IN 0x001
42 # define RB_WAITFD_PRI 0x002
43 # define RB_WAITFD_OUT 0x004
44 #endif
51 #include "ruby/internal/value.h"
52 #include "ruby/backward/2/attributes.h" /* PACKED_STRUCT_UNALIGNED */
53 
55 
56 struct stat;
57 struct timeval;
58 
66 typedef enum {
67  RUBY_IO_READABLE = RB_WAITFD_IN,
68  RUBY_IO_WRITABLE = RB_WAITFD_OUT,
69  RUBY_IO_PRIORITY = RB_WAITFD_PRI,
71 
76 PACKED_STRUCT_UNALIGNED(struct rb_io_buffer_t {
77 
79  char *ptr; /* off + len <= capa */
80 
82  int off;
83 
85  int len;
86 
88  int capa;
89 });
90 
92 typedef struct rb_io_buffer_t rb_io_buffer_t;
93 
95 typedef struct rb_io_t {
96 
98  VALUE self;
99 
102 
104  int fd;
105 
107  int mode;
108 
110  rb_pid_t pid;
111 
113  int lineno;
114 
117 
119  void (*finalize)(struct rb_io_t*,int);
120 
123 
129 
136 
138  /*
139  * enc enc2 read action write action
140  * NULL NULL force_encoding(default_external) write the byte sequence of str
141  * e1 NULL force_encoding(e1) convert str.encoding to e1
142  * e1 e2 convert from e2 to e1 convert str.encoding to e2
143  */
144  struct rb_io_enc_t {
147 
150 
156  int ecflags;
157 
166  } encs;
170 
176 
179 
187 
190 
196 
202 
212 
214 typedef struct rb_io_enc_t rb_io_enc_t;
215 
223 #define HAVE_RB_IO_T 1
224 
232 #define FMODE_READABLE 0x00000001
233 
235 #define FMODE_WRITABLE 0x00000002
236 
238 #define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE)
239 
249 #define FMODE_BINMODE 0x00000004
250 
256 #define FMODE_SYNC 0x00000008
257 
262 #define FMODE_TTY 0x00000010
263 
270 #define FMODE_DUPLEX 0x00000020
271 
277 #define FMODE_APPEND 0x00000040
278 
285 #define FMODE_CREATE 0x00000080
286 /* #define FMODE_NOREVLOOKUP 0x00000100 */
287 
293 #define FMODE_EXCL 0x00000400
294 
299 #define FMODE_TRUNC 0x00000800
300 
313 #define FMODE_TEXTMODE 0x00001000
314 /* #define FMODE_PREP 0x00010000 */
315 /* #define FMODE_SIGNAL_ON_EPIPE 0x00020000 */
316 
321 #define FMODE_SETENC_BY_BOM 0x00100000
322 /* #define FMODE_UNIX 0x00200000 */
323 /* #define FMODE_INET 0x00400000 */
324 /* #define FMODE_INET6 0x00800000 */
325 
337 #define RB_IO_POINTER(obj,fp) rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr)
338 
343 #define GetOpenFile RB_IO_POINTER
344 
358 #define RB_IO_OPEN(obj, fp) do {\
359  (fp) = rb_io_make_open_file(obj);\
360 } while (0)
361 
366 #define MakeOpenFile RB_IO_OPEN
367 
379 rb_io_t *rb_io_make_open_file(VALUE obj);
380 
437 
452 FILE *rb_fdopen(int fd, const char *modestr);
453 
469 int rb_io_modestr_fmode(const char *modestr);
470 
484 int rb_io_modestr_oflags(const char *modestr);
485 
494 int rb_io_oflags_fmode(int oflags);
495 
507 void rb_io_check_writable(rb_io_t *fptr);
508 
510 void rb_io_check_readable(rb_io_t *fptr);
511 
531 
541 
551 int rb_io_fptr_finalize(rb_io_t *fptr);
552 
562 void rb_io_synchronized(rb_io_t *fptr);
563 
571 void rb_io_check_initialized(rb_io_t *fptr);
572 
580 void rb_io_check_closed(rb_io_t *fptr);
581 
593 
607 
632 
649 
671 void rb_io_set_nonblock(rb_io_t *fptr);
672 
680 int rb_io_descriptor(VALUE io);
681 
699 int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, int *fmode_p);
700 
768 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);
769 
770 /* :TODO: can this function be __attribute__((warn_unused_result)) or not? */
786 ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size);
787 
788 //RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_readable"))
798 int rb_io_wait_readable(int fd);
799 
800 //RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_writable"))
809 int rb_io_wait_writable(int fd);
810 
811 //RBIMPL_ATTR_DEPRECATED(("use rb_io_wait"))
826 int rb_wait_for_single_fd(int fd, int events, struct timeval *tv);
827 
842 VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout);
843 
874 VALUE rb_io_maybe_wait(int error, VALUE io, VALUE events, VALUE timeout);
875 
895 int rb_io_maybe_wait_readable(int error, VALUE io, VALUE timeout);
896 
916 int rb_io_maybe_wait_writable(int error, VALUE io, VALUE timeout);
917 
919 /* compatibility for ruby 1.8 and older */
920 #define rb_io_mode_flags(modestr) [<"rb_io_mode_flags() is obsolete; use rb_io_modestr_fmode()">]
921 #define rb_io_modenum_flags(oflags) [<"rb_io_modenum_flags() is obsolete; use rb_io_oflags_fmode()">]
934 
942 void rb_eof_error(void);
943 
951 void rb_io_read_check(rb_io_t *fptr);
952 
962 int rb_io_read_pending(rb_io_t *fptr);
963 
970 VALUE rb_stat_new(const struct stat *st);
971 
972 /* gc.c */
973 
975 
976 #endif /* RUBY_IO_H */
Defines RBIMPL_ATTR_CONST.
Tweaking visibility of C variables/functions.
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition: dllexport.h:106
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition: dllexport.h:97
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:5873
VALUE rb_stat_new(const struct stat *st)
Constructs an instance of rb_cStat from the passed information.
Definition: file.c:547
VALUE rb_io_get_io(VALUE io)
Identical to rb_io_check_io(), except it raises exceptions on conversion failures.
Definition: io.c:801
VALUE rb_io_taint_check(VALUE obj)
Definition: io.c:771
void rb_io_read_check(rb_io_t *fptr)
Blocks until there is a pending read in the passed IO.
Definition: io.c:1007
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:6006
void rb_io_check_byte_readable(rb_io_t *fptr)
Asserts that an IO is opened for byte-based reading.
Definition: io.c:953
void rb_io_check_readable(rb_io_t *fptr)
Just another name of rb_io_check_byte_readable.
Definition: io.c:962
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:6155
struct rb_io_t rb_io_t
Ruby's IO, metadata and buffers.
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:8544
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:1428
RBIMPL_ATTR_NORETURN() void rb_eof_error(void)
Utility function to raise rb_eEOFError.
struct rb_io_enc_t rb_io_enc_t
Just another name of rb_io_enc_t.
Definition: io.h:214
int rb_io_descriptor(VALUE io)
Returns an integer representing the numeric file descriptor for io.
Definition: io.c:2650
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:1487
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
void rb_io_check_initialized(rb_io_t *fptr)
Asserts that the passed IO is initialised.
Definition: io.c:778
int rb_io_fptr_finalize(rb_io_t *fptr)
Destroys the given IO.
Definition: io.c:5161
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:807
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:6476
ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size)
Buffered write to the passed IO.
Definition: io.c:1807
void rb_io_check_char_readable(rb_io_t *fptr)
Asserts that an IO is opened for character-based reading.
Definition: io.c:934
VALUE rb_io_get_write_io(VALUE io)
Queries the tied IO for writing.
Definition: io.c:813
void rb_io_set_nonblock(rb_io_t *fptr)
Sets an IO to a "nonblock mode".
Definition: io.c:3121
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
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:1385
VALUE rb_io_set_write_io(VALUE io, VALUE w)
Assigns the tied IO for writing.
Definition: io.c:824
void rb_io_check_writable(rb_io_t *fptr)
Asserts that an IO is opened for writing.
Definition: io.c:986
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:1500
void rb_io_check_closed(rb_io_t *fptr)
This badly named function asserts that the passed IO is open.
Definition: io.c:786
rb_io_event_t
Type of events that an IO can wait.
Definition: io.h:66
@ RUBY_IO_READABLE
IO::READABLE
Definition: io.h:67
@ RUBY_IO_PRIORITY
IO::PRIORITY
Definition: io.h:69
@ RUBY_IO_WRITABLE
IO::WRITABLE
Definition: io.h:68
int rb_io_wait_readable(int fd)
Blocks until the passed file descriptor gets readable.
Definition: io.c:1351
void rb_io_synchronized(rb_io_t *fptr)
Sets FMODE_SYNC.
Definition: io.c:6779
VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout)
Blocks until the passed IO is ready for the passed events.
Definition: io.c:1294
Defines RBIMPL_ATTR_NORETURN.
Defines RBIMPL_ATTR_PURE.
IO buffers.
Definition: io.h:89
Decomposed encoding flags (e.g.
Definition: io.h:144
int ecflags
Flags.
Definition: io.h:156
rb_encoding * enc
Internal encoding.
Definition: io.h:146
rb_encoding * enc2
External encoding.
Definition: io.h:149
VALUE ecopts
Flags as Ruby hash.
Definition: io.h:165
Ruby's IO, metadata and buffers.
Definition: io.h:95
int fd
file descriptor.
Definition: io.h:104
struct rb_io_t::rb_io_enc_t encs
Decomposed encoding flags.
int lineno
number of lines read
Definition: io.h:113
rb_econv_t * writeconv
Encoding converter used when writing to this IO.
Definition: io.h:178
rb_pid_t pid
child's pid (for pipes)
Definition: io.h:110
rb_io_buffer_t wbuf
Write buffer.
Definition: io.h:122
rb_econv_t * readconv
Encoding converter used when reading from this IO.
Definition: io.h:169
VALUE writeconv_asciicompat
This is, when set, an instance of rb_cString which holds the "common" encoding.
Definition: io.h:186
FILE * stdio_file
stdio ptr for read/write, if available.
Definition: io.h:101
int writeconv_initialized
Whether rb_io_t::writeconv is already set up.
Definition: io.h:189
VALUE pathv
pathname for file
Definition: io.h:116
int mode
mode flags: FMODE_XXXs
Definition: io.h:107
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:195
VALUE write_lock
This is a Ruby level mutex.
Definition: io.h:210
rb_io_buffer_t cbuf
rb_io_ungetc() destination.
Definition: io.h:175
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:201
VALUE tied_io_for_writing
Duplex IO object, if set.
Definition: io.h:135
void(* finalize)(struct rb_io_t *, int)
finalize proc
Definition: io.h:119
rb_io_buffer_t rbuf
(Byte) read buffer.
Definition: io.h:128
Defines VALUE and ID.
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40