Ruby
3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
|
Public APIs related to rb_cIO. More...
Go to the source code of this file.
Macros | |
#define | rb_defout rb_stdout |
#define | RB_RESERVED_FD_P(fd) rb_reserved_fd_p(fd) |
Just another name of rb_reserved_fd_p. More... | |
Functions | |
VALUE | rb_io_write (VALUE io, VALUE str) |
Writes the given string to the given IO. More... | |
VALUE | rb_io_gets (VALUE io) |
Reads a "line" from the given IO. More... | |
VALUE | rb_io_getbyte (VALUE io) |
Reads a byte from the given IO. More... | |
VALUE | rb_io_ungetc (VALUE io, VALUE c) |
"Unget"s a string. More... | |
VALUE | rb_io_ungetbyte (VALUE io, VALUE b) |
Identical to rb_io_ungetc(), except it doesn't take the encoding of the passed IO into account. More... | |
VALUE | rb_io_close (VALUE io) |
Closes the IO. More... | |
VALUE | rb_io_flush (VALUE io) |
Flushes any buffered data within the passed IO to the underlying operating system. More... | |
VALUE | rb_io_eof (VALUE io) |
Queries if the passed IO is at the end of file. More... | |
VALUE | rb_io_binmode (VALUE io) |
Sets the binmode. More... | |
VALUE | rb_io_ascii8bit_binmode (VALUE io) |
Forces no conversions be applied to the passed IO. More... | |
VALUE | rb_io_addstr (VALUE io, VALUE str) |
Identical to rb_io_write(), except it always returns the passed IO. More... | |
VALUE | rb_io_printf (int argc, const VALUE *argv, VALUE io) |
This is a rb_f_sprintf() + rb_io_write() combo. More... | |
VALUE | rb_io_print (int argc, const VALUE *argv, VALUE io) |
Iterates over the passed array to apply rb_io_write() individually. More... | |
VALUE | rb_io_puts (int argc, const VALUE *argv, VALUE io) |
Iterates over the passed array to apply rb_io_write() individually. More... | |
VALUE | rb_io_fdopen (int fd, int flags, const char *path) |
Creates an IO instance whose backend is the given file descriptor. More... | |
VALUE | rb_file_open (const char *fname, const char *fmode) |
Opens a file located at the given path. More... | |
VALUE | rb_file_open_str (VALUE fname, const char *fmode) |
Identical to rb_file_open(), except it takes the pathname as a Ruby's string instead of C's. More... | |
VALUE | rb_gets (void) |
Much like rb_io_gets(), but it reads from the mysterious ARGF object. More... | |
void | rb_write_error (const char *str) |
Writes the given error message to somewhere applicable. More... | |
void | rb_write_error2 (const char *str, long len) |
Identical to rb_write_error(), except it additionally takes the message's length. More... | |
void | rb_close_before_exec (int lowfd, int maxhint, VALUE noclose_fds) |
Closes everything. More... | |
int | rb_pipe (int *pipes) |
This is an rb_cloexec_pipe() + rb_update_max_fd() combo. More... | |
int | rb_reserved_fd_p (int fd) |
Queries if the given FD is reserved or not. More... | |
int | rb_cloexec_open (const char *pathname, int flags, mode_t mode) |
Opens a file that closes on exec. More... | |
int | rb_cloexec_dup (int oldfd) |
Identical to rb_cloexec_fcntl_dupfd(), except it implies minfd is 3. More... | |
int | rb_cloexec_dup2 (int oldfd, int newfd) |
Identical to rb_cloexec_dup(), except you can specify the destination file descriptor. More... | |
int | rb_cloexec_pipe (int fildes[2]) |
Opens a pipe with closing on exec. More... | |
int | rb_cloexec_fcntl_dupfd (int fd, int minfd) |
Duplicates a file descriptor with closing on exec. More... | |
void | rb_update_max_fd (int fd) |
Informs the interpreter that the passed fd can be the max. More... | |
void | rb_fd_fix_cloexec (int fd) |
Sets or clears the close-on-exec flag of the passed file descriptor to the desired state. More... | |
Variables | |
VALUE | rb_fs |
The field separator character for inputs, or the $; . More... | |
VALUE | rb_output_fs |
The field separator character for outputs, or the $, . More... | |
VALUE | rb_rs |
The record separator character for inputs, or the $/ . More... | |
VALUE | rb_default_rs |
This is the default value of rb_rs, i.e. More... | |
VALUE | rb_output_rs |
The record separator character for outputs, or the $\ . More... | |
Public APIs related to rb_cIO.
RBIMPL
or rbimpl
are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will. __VA_ARGS__
is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98. Definition in file io.h.
#define rb_defout rb_stdout |
Exists here for backwards compatibility only. You can safely forget about it.
#define RB_RESERVED_FD_P | ( | fd | ) | rb_reserved_fd_p(fd) |
Just another name of rb_reserved_fd_p.
int rb_cloexec_dup | ( | int | oldfd | ) |
Identical to rb_cloexec_fcntl_dupfd(), except it implies minfd is 3.
[in] | oldfd | File descriptor to duplicate. |
-1 | dup2(2) failed for some reason. |
otherwise | An allocated new file descriptor. |
int rb_cloexec_dup2 | ( | int | oldfd, |
int | newfd | ||
) |
Identical to rb_cloexec_dup(), except you can specify the destination file descriptor.
If the destination is already squatted by another file descriptor that gets silently closed without any warnings. (This is a spec requested by POSIX.)
[in] | oldfd | File descriptor to duplicate. |
[in] | newfd | Return value destination. |
-1 | dup2(2) failed for some reason. |
newfd | An allocated new file descriptor. |
newfd
gets closed with no notifications. newfd
is untouched. int rb_cloexec_fcntl_dupfd | ( | int | fd, |
int | minfd | ||
) |
Duplicates a file descriptor with closing on exec.
In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function duplicates a file descriptor as dup(2)
does, but additionally instructs the operating system that we don't want the duplicated FD be seen from child processes.
[in] | fd | File descriptor to duplicate. |
[in] | minfd | Minimum allowed FD to return. |
-1 | dup(2) failed for some reason. |
otherwise | An allocated new file descriptor. |
minfd
is handy when for instance STDERR is closed but you don't want to use fd 2.
Definition at line 461 of file io.c.
Referenced by rb_cloexec_dup().
int rb_cloexec_open | ( | const char * | pathname, |
int | flags, | ||
mode_t | mode | ||
) |
Opens a file that closes on exec.
In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function opens a file descriptor as open(2)
does, but additionally instructs the operating system that we don't want it be seen from child processes.
[in] | pathname | File path to open. |
[in] | flags | Open mode, as in open(2) . |
[in] | mode | File mode, in case of O_CREAT . |
-1 | open(2) failed for some reason. |
otherwise | An allocated new file descriptor. |
int rb_cloexec_pipe | ( | int | fildes[2] | ) |
Opens a pipe with closing on exec.
In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function opens a pipe as pipe(2)
does, but additionally instructs the operating system that we don't want the duplicated FDs be seen from child processes.
[out] | fildes | Return buffer. Must at least hold 2 elements. |
0 | Successful creation of a pipe. |
-1 | Failure in underlying system call(s). |
pipes
is filled with file descriptors. errno
is set on failure. Definition at line 427 of file io.c.
Referenced by rb_pipe().
void rb_close_before_exec | ( | int | lowfd, |
int | maxhint, | ||
VALUE | noclose_fds | ||
) |
Closes everything.
In case of POSIX environments, a child process inherits its parent's opened file descriptors. Which is nowadays considered as one of the UNIX mistakes. This function closes such inherited file descriptors. When your C extension needs to have a child process, don't forget to call this from your child process right before exec.
[in] | lowfd | Lower bound of FDs (you want STDIN to remain, no?). |
[in] | maxhint | Hint of max FDs. |
[in] | noclose_fds | A hash, whose keys are an allowlist. |
void rb_fd_fix_cloexec | ( | int | fd | ) |
Sets or clears the close-on-exec flag of the passed file descriptor to the desired state.
STDIN, STDOUT, STDERR are the exceptional file descriptors that shall remain open. All others are to be closed on exec. When a C extension library opens a file descriptor using anything other than rb_cloexec_open() etc., that file descriptor shall experience this function.
[in] | fd | An open file descriptor. |
VALUE rb_file_open | ( | const char * | fname, |
const char * | fmode | ||
) |
Opens a file located at the given path.
fmode
is a C string that represents the open mode. It can be one of:
r
(means O_RDONLY
),w
(means O_WRONLY | O_TRUNC | O_CREAT
),a
(means O_WRONLY | O_APPEND | O_CREAT
),Followed by zero or more combinations of:
b
(means _O_BINARY
),t
(means _O_TEXT
),+
(means O_RDWR
),x
(means O_TRUNC
), or:[BOM|]enc[:enc]
(see below).This last one specifies external (and internal if any) encodings, respectively. If optional BOM|
is specified and the specified external encoding is capable of expressing BOMs, opening file's contents' byte order is auto-detected using the mechanism.
So for instance, fmode of "rt|BOM:utf-16le:utf-8"
specifies that...
\n
.[in] | fname | Path to open. |
[in] | fmode | Mode specifier much like fopen(3) . |
rb_eArgError | fmode contradicted (e.g. "bt" ). |
rb_eSystemCallError | open(2) failed for some reason. |
Identical to rb_file_open(), except it takes the pathname as a Ruby's string instead of C's.
In case the passed Ruby object is a non-String it tries to call #to_path
.
[in] | fname | Path to open. |
[in] | fmode | Mode specifier much like fopen(3) . |
rb_eTypeError | fname is not a String. |
rb_eEncCompatError | fname is not ASCII-compatible. |
rb_eArgError | fmode contradicted (e.g. "bt" ). |
rb_eSystemCallError | open(2) failed for some reason. |
VALUE rb_gets | ( | void | ) |
Much like rb_io_gets(), but it reads from the mysterious ARGF object.
ARGF in this context can be seen as a virtual IO which concatenates contents of the files passed to the process via the ARGV, or just STDIN if there are no such files.
Unlike rb_io_gets() this function sets $_
.
rb_eFrozenError | ARGF resorts to STDIN but it is frozen. |
RUBY_Qnil | ARGF is at EOF. |
otherwise | An instance of rb_cString. |
$_
is set. Identical to rb_io_write(), except it always returns the passed IO.
[out] | io | An IO, opened for writing. |
[in] | str | A String-like object to write to io . |
rb_eIOError | io isn't opened for writing. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from str to String. |
rb_eSystemCallError | write(2) failed. |
io
. str
is written to io
. Forces no conversions be applied to the passed IO.
Unlike rb_io_binmode(), this cancels any newline conversions as well as encoding conversions. Any texts read/written through the IO will be the verbatim binary contents.
[out] | io | Target IO to modify. |
rb_eFrozenError | io is frozen. |
io
. io
is in binmode. Both external/internal encoding are set to rb_ascii8bit_encoding(). IO#binmode
. Sets the binmode.
This operation nullifies the effect of textmode (newline conversion from "\r\n"
to "\n"
or vice versa). Note that it doesn't stop character encodings conversions. For instance an IO created using:
has both newline and character conversions. If you pass such IO to this function, only the textmode:true
part is cancelled. Texts read through the IO would still be encoded in Windows-31J; texts written to the IO will be encoded in GB18030.
[out] | io | Target IO to modify. |
rb_eFrozenError | io is frozen. |
io
. io
is in binmode. Closes the IO.
Any buffered contents are flushed to the operating system. Any future operations against the IO would raise rb_eIOError. In case the io was created using IO.popen
, it also sets the $?
.
[out] | io | Target IO to close. |
$?
is set in case IO is a pipe. io
any further. select()
-ing the passed IO. Definition at line 5717 of file io.c.
Referenced by rb_gets().
Queries if the passed IO is at the end of file.
"The end of file" here mans that there are no more data to read. This function blocks until the read buffer is filled in, and if that operation reached the end of file, it still returns RUBY_Qfalse (because there are data yet in that buffer). It returns RUBY_Qtrue once after the buffer is cleared.
[in,out] | io | Target io to query. |
rb_eIOError | io is not opened for reading. |
rb_eFrozenError | io is frozen. |
RUBY_Qfalse | There are things yet to be read. |
RUBY_Qtrue | "The end of file" situation. |
VALUE rb_io_fdopen | ( | int | fd, |
int | flags, | ||
const char * | path | ||
) |
Creates an IO instance whose backend is the given file descriptor.
C extension libraries sometimes have file descriptors created elsewhere (maybe deep inside of another shared library), which they want ruby programs to handle. This function is handy for such situations.
[in] | fd | Target file descriptor. |
[in] | flags | Flags, e.g. O_CREAT|O_EXCL |
[in] | path | The path of the file that backs fd , for diagnostics. |
path
NULL if you don't know. Flushes any buffered data within the passed IO to the underlying operating system.
[out] | io | Target IO to flush. |
rb_eIOError | io is closed. |
rb_eFrozenError | io is frozen. |
rb_eSystemCallError | write(2) failed for some reason. |
io
. io
's buffers are empty. ungetc
, this operation in fact changes the behaviour of the io
. Definition at line 2400 of file io.c.
Referenced by rb_io_getbyte().
Reads a byte from the given IO.
[in,out] | io | An IO, opened for reading. |
rb_eIOError | io is not opened for reading. |
rb_eFrozenError | io is frozen. |
RUBY_Qnil | io is at EOF. |
otherwise | An instance of rb_cInteger. |
io
is read. Reads a "line" from the given IO.
A line here means a chunk of characters which is terminated by either "\n"
or an EOF.
[in,out] | io | An IO, opened for reading. |
rb_eIOError | io isn't opened for reading. |
rb_eFrozenError | io is frozen. |
RUBY_Qnil | io is at EOF. |
otherwise | An instance of rb_cString. |
io
is read. IO#gets
it doesn't set $_
. IO#gets
it doesn't consider $/
. Definition at line 4262 of file io.c.
Referenced by rb_gets().
Iterates over the passed array to apply rb_io_write() individually.
If there is $,
, this function inserts the string in middle of each iterations. If there is $\
, this function appends the string at the end. If the array is empty, this function outputs $_
.
[in] | argc | Number of objects of argv . |
[in] | argv | An array of strings to display. |
[out] | io | An IO, opened for writing. |
rb_eIOError | io isn't opened for writing. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from str to String. |
rb_eSystemCallError | write(2) failed. |
argv
is written to io
. This is a rb_f_sprintf() + rb_io_write() combo.
[in] | argc | Number of objects of argv . |
[in] | argv | A format string followed by its arguments. |
[out] | io | An IO, opened for writing. |
rb_eIOError | io isn't opened for writing. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from str to String. |
rb_eSystemCallError | write(2) failed. |
argv
is formatted, then written to io
. Iterates over the passed array to apply rb_io_write() individually.
Unlike rb_io_print(), this function prints a newline per each element. It also flattens the passed array (OTOH rb_io_print() just resorts to rb_ary_to_s()).
[in] | argc | Number of objects of argv . |
[in] | argv | An array of strings to display. |
[out] | io | An IO, opened for writing. |
rb_eIOError | io isn't opened for writing. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from str to String. |
rb_eSystemCallError | write(2) failed. |
argv
is written to io
. Definition at line 8924 of file io.c.
Referenced by rb_f_abort().
Identical to rb_io_ungetc(), except it doesn't take the encoding of the passed IO into account.
When an integer is passed, it just casts that value to C's unsigned char
, and pushes that back.
[out] | io | An IO, opened for reading. |
[in] | b | Either a String, or an Integer. |
rb_eIOError | io is not opened for reading. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from b to rb_cString. |
"Unget"s a string.
This function pushes back the passed string onto the passed IO, such that a subsequent buffered read will return it. If the passed content is in fact an integer, a single character string of that codepoint of the encoding of the IO will be pushed back instead.
It might be counter-intuitive but this function can push back multiple characters at once. Also this function can be called multiple times on a same IO. Also a "character" can be wider than a byte, depending on the encoding of the IO.
[out] | io | An IO, opened for reading. |
[in] | c | Either a String, or an Integer. |
rb_eIOError | io is not opened for reading. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from c to rb_cString. |
Writes the given string to the given IO.
[out] | io | An IO, opened for writing. |
[in] | str | A String-like object to write to io . |
rb_eIOError | io isn't opened for writing. |
rb_eFrozenError | io is frozen. |
rb_eTypeError | No conversion from str to String. |
rb_eSystemCallError | write(2) failed for some reason. |
io
. str
(up to the length of return value) is written to io
. Definition at line 2296 of file io.c.
Referenced by rb_io_addstr(), rb_io_print(), rb_io_printf(), rb_io_puts(), and rb_write_error2().
int rb_pipe | ( | int * | pipes | ) |
This is an rb_cloexec_pipe() + rb_update_max_fd() combo.
[out] | pipes | Return buffer. Must at least hold 2 elements. |
0 | Successful creation of a pipe. |
-1 | Failure in underlying system call(s). |
pipes
is filled with file descriptors. errno
is set on failure. int rb_reserved_fd_p | ( | int | fd | ) |
Queries if the given FD is reserved or not.
Occasionally Ruby interpreter opens files for its own purposes. Use this function to prevent touching such behind-the-scene descriptors.
[in] | fd | Target file descriptor. |
1 | fd is reserved. |
0 | Otherwise. |
void rb_update_max_fd | ( | int | fd | ) |
Informs the interpreter that the passed fd can be the max.
This information is used from rb_close_before_exec().
[in] | fd | An open FD, which can be large. |
Definition at line 248 of file io.c.
Referenced by rb_fd_fix_cloexec(), rb_io_open_descriptor(), and rb_pipe().
void rb_write_error | ( | const char * | str | ) |
Writes the given error message to somewhere applicable.
On Windows it goes to the console. On POSIX environments it goes to the standard error.
[in] | str | Error message to display. |
str
is written to somewhere. void rb_write_error2 | ( | const char * | str, |
long | len | ||
) |
Identical to rb_write_error(), except it additionally takes the message's length.
Necessary when you want to handle wide characters.
[in] | str | Error message to display. |
[in] | len | Length of str , in bytes. |
str
is written to somewhere. Definition at line 9101 of file io.c.
Referenced by rb_write_error().
|
extern |
This is the default value of rb_rs, i.e.
"\n"
. It seems it has always been just a newline string since the beginning. Not sure why C codes has to use this, given there is no way for ruby programs to interface.
Also it has not been deprecated for unknown reasons.
Definition at line 207 of file io.c.
Referenced by rb_gets(), rb_io_gets(), and rb_io_puts().
|
extern |
The field separator character for inputs, or the $;
.
This affects how String#split
works. You can set this via the -F
command line option. You can also assign arbitrary ruby objects programmatically, but it makes best sense for you to assign a regular expression here.
|
extern |
The field separator character for outputs, or the $,
.
This affects how Array#join
works.
Definition at line 204 of file io.c.
Referenced by rb_io_print().
|
extern |
The record separator character for outputs, or the $\
.
This affects how IO#print
works.
Definition at line 206 of file io.c.
Referenced by rb_io_print().