(37a72b0150ec36b4ea27175039afc28c62207b0c)

Public APIs related to rb_cIO. More...

#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"

Include dependency graph for io.h:

This graph shows which files directly or indirectly include 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...

Detailed Description

Public APIs related to rb_cIO.

Author: Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright: This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning: Symbols prefixed with either 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.

Note: To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __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.

Macro Definition Documentation

◆ rb_defout

#define rb_defout rb_stdout

Deprecated:: This macro once was a thing in the old days, but makes no sense any longer today.

Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 37 of file io.h.

◆ RB_RESERVED_FD_P

#define RB_RESERVED_FD_P ( fd ) rb_reserved_fd_p(fd)

Just another name of rb_reserved_fd_p.

Definition at line 556 of file io.h.

Function Documentation

◆ rb_cloexec_dup()

int rb_cloexec_dup ( int oldfd )

Identical to rb_cloexec_fcntl_dupfd(), except it implies minfd is 3.

Parameters

[in] oldfd File descriptor to duplicate.

Return values

-1	`dup2(2)` failed for some reason.
otherwise	An allocated new file descriptor.

Note: This function does not raise.

Definition at line 367 of file io.c.

◆ rb_cloexec_dup2()

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.)

Parameters

[in]	oldfd	File descriptor to duplicate.
[in]	newfd	Return value destination.

Return values

-1	`dup2(2)` failed for some reason.
newfd	An allocated new file descriptor.

Postcondition: Whatever sat at newfd gets closed with no notifications.; In case return value is -1 newfd is untouched.

Note: This function does not raise.

Definition at line 374 of file io.c.

◆ rb_cloexec_fcntl_dupfd()

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.

Parameters

[in]	fd	File descriptor to duplicate.
[in]	minfd	Minimum allowed FD to return.

Return values

-1	`dup(2)` failed for some reason.
otherwise	An allocated new file descriptor.

Note: This function does not raise.

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().

◆ rb_cloexec_open()

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.

Parameters

[in]	pathname	File path to open.
[in]	flags	Open mode, as in `open(2)`.
[in]	mode	File mode, in case of `O_CREAT`.

Return values

-1	`open(2)` failed for some reason.
otherwise	An allocated new file descriptor.

Note: This function does not raise.

Definition at line 328 of file io.c.

◆ rb_cloexec_pipe()

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.

Parameters

[out] fildes Return buffer. Must at least hold 2 elements.

Return values

0	Successful creation of a pipe.
-1	Failure in underlying system call(s).

Postcondition: pipes is filled with file descriptors.; errno is set on failure.

Definition at line 427 of file io.c.

Referenced by rb_pipe().

◆ rb_close_before_exec()

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.

Parameters

[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.

◆ rb_fd_fix_cloexec()

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.

Parameters

[in] fd An open file descriptor.

Definition at line 298 of file io.c.

◆ rb_file_open()

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...

the physical representation of the contents of the file is in UTF-16;
honours its BOM but assumes little endian if absent;
opens the file for reading;
what is read is converted into UTF-8;
with newlines cannibalised to \n.

Parameters

[in]	fname	Path to open.
[in]	fmode	Mode specifier much like `fopen(3)`.

Exceptions

rb_eArgError	`fmode` contradicted (e.g. `"bt"`).
rb_eSystemCallError	`open(2)` failed for some reason.

Returns: An instance of rb_cIO.

Definition at line 7234 of file io.c.

◆ rb_file_open_str()

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.

In case the passed Ruby object is a non-String it tries to call #to_path.

Parameters

[in]	fname	Path to open.
[in]	fmode	Mode specifier much like `fopen(3)`.

Exceptions

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.

Returns: An instance of rb_cIO.

Definition at line 7227 of file io.c.

◆ rb_gets()

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 $_.

Exceptions

rb_eFrozenError ARGF resorts to STDIN but it is frozen.

Return values

RUBY_Qnil	ARGF is at EOF.
otherwise	An instance of rb_cString.

Postcondition: ARGF is read.; $_ is set.

Definition at line 10366 of file io.c.

◆ rb_io_addstr()

VALUE rb_io_addstr	(	VALUE	io,
		VALUE	str
	)

Identical to rb_io_write(), except it always returns the passed IO.

Parameters

[out]	io	An IO, opened for writing.
[in]	str	A String-like object to write to `io`.

Exceptions

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.

Returns: The passed io.

Postcondition: str is written to io.

Note: This function blocks.

Definition at line 2344 of file io.c.

◆ rb_io_ascii8bit_binmode()

VALUE rb_io_ascii8bit_binmode ( VALUE 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.

Parameters

[out] io Target IO to modify.

Exceptions

rb_eFrozenError io is frozen.

Returns: The passed io.

Postcondition: io is in binmode. Both external/internal encoding are set to rb_ascii8bit_encoding().

Note: This is the implementation of IO#binmode.

Definition at line 6343 of file io.c.

◆ rb_io_binmode()

VALUE rb_io_binmode ( VALUE io )

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:

File.open(
  "/dev/urandom",
  textmode: true,
  external_encoding: Encoding::GB18030,
  internal_encoding: Encoding::Windows_31J)

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.

Parameters

[out] io Target IO to modify.

Exceptions

rb_eFrozenError io is frozen.

Returns: The passed io.

Postcondition: io is in binmode.

Note: There is no equivalent operation in Ruby. You can do this only in C.

Definition at line 6297 of file io.c.

◆ rb_io_close()

VALUE rb_io_close ( VALUE io )

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 $?.

Parameters

[out] io Target IO to close.

Returns: Always returns RUBY_Qnil.

Postcondition: $? is set in case IO is a pipe.; No operations are possible against io any further.

Note: This can block to flush the contents.; This can wake other threads up, especially those who are select()-ing the passed IO.; Multiple invocations of this function over the same IO again and again is not an error, since Ruby 2.3.

Definition at line 5717 of file io.c.

Referenced by rb_gets().

◆ rb_io_eof()

VALUE rb_io_eof ( VALUE io )

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.

Parameters

[in,out] io Target io to query.

Exceptions

rb_eIOError	`io` is not opened for reading.
rb_eFrozenError	`io` is frozen.

Return values

RUBY_Qfalse	There are things yet to be read.
RUBY_Qtrue	"The end of file" situation.

Definition at line 2689 of file io.c.

◆ rb_io_fdopen()

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.

Parameters

[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.

Returns: An allocated instance of rb_cIO with the autoclose flag set.

Note: Leave path NULL if you don't know.

Definition at line 9297 of file io.c.

◆ rb_io_flush()

VALUE rb_io_flush ( VALUE io )

Flushes any buffered data within the passed IO to the underlying operating system.

Parameters

[out] io Target IO to flush.

Exceptions

rb_eIOError	`io` is closed.
rb_eFrozenError	`io` is frozen.
rb_eSystemCallError	`write(2)` failed for some reason.

Returns: The passed io.

Postcondition: io's buffers are empty.

Note: This operation also discards the read buffer. Should basically be harmless, but in an esoteric situation like when user pushed something different from what was read using ungetc, this operation in fact changes the behaviour of the io.; Buffering is difficult. This operation flushes the data from our userspace to the kernel, but that doesn't always mean you can expect them stored persistently onto your hard drive.

Definition at line 2400 of file io.c.

Referenced by rb_io_getbyte().

◆ rb_io_getbyte()

VALUE rb_io_getbyte ( VALUE io )

Reads a byte from the given IO.

Note: In Ruby a "byte" always means an 8 bit integer ranging from 0 to 255 inclusive.

Parameters

[in,out] io An IO, opened for reading.

Exceptions

rb_eIOError	`io` is not opened for reading.
rb_eFrozenError	`io` is frozen.

Return values

RUBY_Qnil	`io` is at EOF.
otherwise	An instance of rb_cInteger.

Postcondition: io is read.

Definition at line 5037 of file io.c.

◆ rb_io_gets()

VALUE rb_io_gets ( VALUE io )

Reads a "line" from the given IO.

A line here means a chunk of characters which is terminated by either "\n" or an EOF.

Parameters

[in,out] io An IO, opened for reading.

Exceptions

rb_eIOError	`io` isn't opened for reading.
rb_eFrozenError	`io` is frozen.

Return values

RUBY_Qnil	`io` is at EOF.
otherwise	An instance of rb_cString.

Postcondition: io is read.

Note: Unlike IO#gets it doesn't set $_.; Unlike IO#gets it doesn't consider $/.

Definition at line 4262 of file io.c.

Referenced by rb_gets().

◆ rb_io_print()

VALUE rb_io_print	(	int	argc,
		const VALUE *	argv,
		VALUE	io
	)

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 $_.

Parameters

[in]	argc	Number of objects of `argv`.
[in]	argv	An array of strings to display.
[out]	io	An IO, opened for writing.

Exceptions

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.

Returns: Always returns RUBY_Qnil.

Postcondition: argv is written to io.

Note: This function blocks.; This function calls rb_io_write() multiple times. Which means, it is not an atomic operation. Outputs from multiple threads can interleave.

Definition at line 8692 of file io.c.

◆ rb_io_printf()

VALUE rb_io_printf	(	int	argc,
		const VALUE *	argv,
		VALUE	io
	)

This is a rb_f_sprintf() + rb_io_write() combo.

Parameters

[in]	argc	Number of objects of `argv`.
[in]	argv	A format string followed by its arguments.
[out]	io	An IO, opened for writing.

Exceptions

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.

Returns: Always returns RUBY_Qnil.

Postcondition: argv is formatted, then written to io.

Note: This function blocks.

Definition at line 8566 of file io.c.

◆ rb_io_puts()

VALUE rb_io_puts	(	int	argc,
		const VALUE *	argv,
		VALUE	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()).

Parameters

[in]	argc	Number of objects of `argv`.
[in]	argv	An array of strings to display.
[out]	io	An IO, opened for writing.

Exceptions

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.

Returns: Always returns RUBY_Qnil.

Postcondition: argv is written to io.

Note: This function blocks.; This function calls rb_io_write() multiple times. Which means, it is not an atomic operation. Outputs from multiple threads can interleave.

Definition at line 8924 of file io.c.

Referenced by rb_f_abort().

◆ rb_io_ungetbyte()

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.

When an integer is passed, it just casts that value to C's unsigned char, and pushes that back.

Parameters

[out]	io	An IO, opened for reading.
[in]	b	Either a String, or an Integer.

Exceptions

rb_eIOError	`io` is not opened for reading.
rb_eFrozenError	`io` is frozen.
rb_eTypeError	No conversion from `b` to rb_cString.

Returns: Always returns RUBY_Qnil.

Definition at line 5131 of file io.c.

◆ rb_io_ungetc()

VALUE rb_io_ungetc	(	VALUE	io,
		VALUE	c
	)

"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.

Parameters

[out]	io	An IO, opened for reading.
[in]	c	Either a String, or an Integer.

Exceptions

rb_eIOError	`io` is not opened for reading.
rb_eFrozenError	`io` is frozen.
rb_eTypeError	No conversion from `c` to rb_cString.

Returns: Always returns RUBY_Qnil.

Definition at line 5195 of file io.c.

◆ rb_io_write()

VALUE rb_io_write	(	VALUE	io,
		VALUE	str
	)

Writes the given string to the given IO.

Parameters

[out]	io	An IO, opened for writing.
[in]	str	A String-like object to write to `io`.

Exceptions

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.

Returns: The number of bytes written to the io.

Postcondition: str (up to the length of return value) is written to io.

Note: This function blocks.; Partial write is a thing. It must be at least questionable not to check the return value.

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().

◆ rb_pipe()

int rb_pipe ( int * pipes )

This is an rb_cloexec_pipe() + rb_update_max_fd() combo.

Parameters

[out] pipes Return buffer. Must at least hold 2 elements.

Return values

0	Successful creation of a pipe.
-1	Failure in underlying system call(s).

Postcondition: pipes is filled with file descriptors.; errno is set on failure.

Definition at line 7344 of file io.c.

◆ rb_reserved_fd_p()

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.

Parameters

[in] fd Target file descriptor.

Return values

1	`fd` is reserved.
0	Otherwise.

◆ rb_update_max_fd()

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().

Parameters

[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().

◆ rb_write_error()

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.

Warning: IT IS A BAD IDEA to use this function form your C extensions. It is often annoying when GUI applications write to consoles; users don't want to look at there. Programmers also want to control the cause of the message itself, like by rescuing an exception. Just let ruby handle errors. That must be better than going your own way.

Parameters

[in] str Error message to display.

Postcondition: str is written to somewhere.

Definition at line 9121 of file io.c.

◆ rb_write_error2()

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.

Parameters

[in]	str	Error message to display.
[in]	len	Length of `str`, in bytes.

Postcondition: str is written to somewhere.

Definition at line 9101 of file io.c.

Referenced by rb_write_error().

Variable Documentation

◆ rb_default_rs

VALUE rb_default_rs

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().

◆ rb_fs

VALUE rb_fs

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.

Definition at line 669 of file string.c.

◆ rb_output_fs

VALUE rb_output_fs

extern

The field separator character for outputs, or the $,.

This affects how Array#join works.

Deprecated:: Assigning anything other than RUBY_Qnil to this variable is deprecated.

Definition at line 204 of file io.c.

Referenced by rb_io_print().

◆ rb_output_rs

VALUE rb_output_rs

extern

The record separator character for outputs, or the $\.

This affects how IO#print works.

Deprecated:: Assigning anything other than RUBY_Qnil to this variable is deprecated.

Definition at line 206 of file io.c.

Referenced by rb_io_print().

◆ rb_rs

VALUE rb_rs

extern

The record separator character for inputs, or the $/.

This affects how IO#gets works. You can set this via the -0 command line option.

Deprecated:: Assigning anything other than RUBY_Qnil to this variable is deprecated.

Definition at line 205 of file io.c.

Referenced by rb_gets().

(37a72b0150ec36b4ea27175039afc28c62207b0c)

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ rb_defout

◆ RB_RESERVED_FD_P

Function Documentation

◆ rb_cloexec_dup()

◆ rb_cloexec_dup2()

◆ rb_cloexec_fcntl_dupfd()

◆ rb_cloexec_open()

◆ rb_cloexec_pipe()

◆ rb_close_before_exec()

◆ rb_fd_fix_cloexec()

◆ rb_file_open()

◆ rb_file_open_str()

◆ rb_gets()

◆ rb_io_addstr()

◆ rb_io_ascii8bit_binmode()

◆ rb_io_binmode()

◆ rb_io_close()

◆ rb_io_eof()

◆ rb_io_fdopen()

◆ rb_io_flush()

◆ rb_io_getbyte()

◆ rb_io_gets()

◆ rb_io_print()

◆ rb_io_printf()

◆ rb_io_puts()

◆ rb_io_ungetbyte()

◆ rb_io_ungetc()

◆ rb_io_write()

◆ rb_pipe()

◆ rb_reserved_fd_p()

◆ rb_update_max_fd()

◆ rb_write_error()

◆ rb_write_error2()

Variable Documentation

◆ rb_default_rs

◆ rb_fs

◆ rb_output_fs

◆ rb_output_rs

◆ rb_rs