Ruby: include/ruby/ruby.h File Reference

Ruby 4.0.6p0 (2026-07-14 revision 03b6d3f8898a28604fe6cb00eae3226b821168f4)

Macros | Functions
ruby.h File Reference
`#include "ruby/internal/config.h"`
`#include <stdarg.h>`
`#include "defines.h"`
`#include "ruby/internal/abi.h"`
`#include "ruby/internal/anyargs.h"`
`#include "ruby/internal/arithmetic.h"`
`#include "ruby/internal/core.h"`
`#include "ruby/internal/ctype.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/error.h"`
`#include "ruby/internal/eval.h"`
`#include "ruby/internal/event.h"`
`#include "ruby/internal/fl_type.h"`
`#include "ruby/internal/gc.h"`
`#include "ruby/internal/glob.h"`
`#include "ruby/internal/globals.h"`
`#include "ruby/internal/has/warning.h"`
`#include "ruby/internal/interpreter.h"`
`#include "ruby/internal/iterator.h"`
`#include "ruby/internal/memory.h"`
`#include "ruby/internal/method.h"`
`#include "ruby/internal/module.h"`
`#include "ruby/internal/newobj.h"`
`#include "ruby/internal/scan_args.h"`
`#include "ruby/internal/special_consts.h"`
`#include "ruby/internal/symbol.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/value_type.h"`
`#include "ruby/internal/variable.h"`
`#include "ruby/assert.h"`
`#include "ruby/backward/2/assume.h"`
`#include "ruby/backward/2/inttypes.h"`
`#include "ruby/backward/2/limits.h"`
`#include "ruby/intern.h"`
`#include <errno.h>`
`#include "ruby/subst.h"`
`#include "ruby/backward.h"`

Go to the source code of this file.

## Macros
#define | USE_SYMBOL_AS_METHOD_NAME 1
#define | FilePathValue(v)
| Ensures that the parameter object is a path.
#define | FilePathStringValue(v)
| This macro actually does the same thing as FilePathValue now.
#define | RUBY_VM 1 /* YARV */
#define | HAVE_NATIVETHREAD
#define | InitVM(ext)
| This macro is for internal use.
#define | RUBY__ASAN_DEFAULT_OPTIONS
#define | RUBY_GLOBAL_SETUP
#define | ruby_start_main(main, argc, argv)

## Functions
VALUE | rb_get_path (VALUE obj)
| Converts an object to a path.
VALUE | rb_get_path_no_checksafe (VALUE)
const char * | rb_class2name (VALUE klass)
| Queries the name of the passed class.
const char * | rb_obj_classname (VALUE obj)
| Queries the name of the class of the passed object.
void | rb_p (VALUE obj)
| Inspects an object.
VALUE | rb_equal (VALUE lhs, VALUE rhs)
| This function is an optimised version of calling #==.
VALUE | rb_require (const char *feature)
| Identical to rb_require_string(), except it takes C's string instead of Ruby's.
int | ruby_native_thread_p (void)
| Queries if the thread which calls this function is a ruby's thread.
int | ruby_snprintf (char *str, size_t n, char const *fmt,...)
| Our own locale-insensitive version of snprintf(3).
int | ruby_vsnprintf (char *str, size_t n, char const *fmt, va_list ap)
| Identical to ruby_snprintf(), except it takes a va_list.

## Errno handling routines for userland threads
Note POSIX chapter 2 section 3 states that for each thread of a process, the value of errno shall not be affected by function calls or assignments to errno by other threads. Soooo this #define errno below seems like a noob mistake at first sight. If you look at its actual implementation, the functions are just adding one level of indirection. It doesn't make any sense sorry? But yes! @ko1 told @shyouhei that this is inevitable. The ultimate reason is because Ruby now has N:M threads implemented. Threads of that sort change their context in user land. A function can be "transferred" between threads in middle of their executions. Let us for instance consider: void foo() { auto i = errno; close(0); errno = i; } errno #define errno Ractor-aware version of errno. Definition ruby.h:388 This function (if ran under our Ractor) could change its running thread at the close function. But the two errno invocations are different! Look how the source code above is compiled by clang 17 with -O3 flag @ Linux: foo(int): # @foo(int) push rbp push r14 push rbx mov ebx, edi call __errno_location@PLT mov r14, rax mov ebp, dword ptr [rax] mov edi, ebx call close@PLT mov dword ptr [r14], ebp pop rbx pop r14 pop rbp ret Notice how __errno_location@PLT is call-ed only once. The compiler assumes that the location of errno does not change during a function call. Sadly this is no longer true for us. The close@PLT now changes threads, which should also change where errno is stored. With the #define errno below the compilation result changes to this: foo(int): # @foo(int) push rbp push rbx push rax mov ebx, edi call rb_errno_ptr()@PLT mov ebp, dword ptr [rax] mov edi, ebx call close@PLT call rb_errno_ptr()@PLT mov dword ptr [rax], ebp add rsp, 8 pop rbx pop rbp ret rb_errno_ptr int * rb_errno_ptr(void) The location of errno. Definition eval.c:2300 Which fixes the problem.
#define | rb_orig_errno errno
| System-provided original errno.
#define | errno (*rb_errno_ptr())
| Ractor-aware version of errno.
int | rb_errno (void)
| Identical to system errno.
void | rb_errno_set (int err)
| Set the errno.
int * | rb_errno_ptr (void)
| The location of errno.
static int * | rb_orig_errno_ptr (void)
| Not sure if it is necessary for extension libraries but this is where the "bare" errno is located.

## Detailed Description

Author
  $Author$

Date
  Thu Jun 10 14:26:32 JST 1993

Copyright
  Copyright (C) 1993-2008 Yukihiro Matsumoto
  Copyright (C) 2000 Network Applied Communication Laboratory, Inc.
  Copyright (C) 2000 Information-technology Promotion Agency, Japan
  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.

Definition in file ruby.h.

## Macro Definition Documentation

## ◆ errno

#define errno (*rb_errno_ptr())

Ractor-aware version of errno.

Definition at line 388 of file ruby.h.

Referenced by pm_pack_parse(), rb_cloexec_dup2(), rb_cloexec_fcntl_dupfd(), rb_cloexec_open(), rb_cloexec_pipe(), rb_fiber_scheduler_blocking_operation_execute(), rb_fiber_scheduler_io_result_apply(), rb_fiber_scheduler_unblock(), rb_io_wait_readable(), rb_io_wait_writable(), rb_orig_errno_ptr(), rb_proc_exec(), rb_readwrite_sys_fail(), rb_sys_warning(), rb_update_max_fd(), rb_waitpid(), ruby_getcwd(), and ruby_strtoul().

## ◆ FilePathStringValue

#define FilePathStringValue | ( |  | v | ) |

Value:
((v) = rb_get_path(v))

This macro actually does the same thing as FilePathValue now.

The "String" part indicates that this is for when a string is treated like a pathname, rather than the actual pathname on the file systems. For examples: Dir.fnmatch?, File.join, File.basename, etc.

Definition at line 105 of file ruby.h.

## ◆ FilePathValue

#define FilePathValue | ( |  | v | ) |

Value:
(RB_GC_GUARD(v) = rb_get_path(v))
RB_GC_GUARD
#define RB_GC_GUARD(v)
Prevents premature destruction of local objects.
Definition memory.h:167

Ensures that the parameter object is a path.

Parameters

  [in,out] | v | Arbitrary ruby object.

Exceptions

  rb_eArgError | `v` contains a NUL byte.
  rb_eTypeError | `v` is not path-ish.
  rb_eEncCompatError | `v` is not path-compatible.

Postcondition
  v is a path.

Definition at line 90 of file ruby.h.

Referenced by rb_file_open_str(), rb_load(), and rb_require_string().

## ◆ HAVE_NATIVETHREAD

#define HAVE_NATIVETHREAD

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 212 of file ruby.h.

## ◆ InitVM

#define InitVM | ( |  | ext | ) |

Value:
{void InitVM_##ext(void);InitVM_##ext();}

This macro is for internal use.

Must be a mistake to place here.

Definition at line 231 of file ruby.h.

## ◆ rb_orig_errno

#define rb_orig_errno errno

System-provided original errno.

Definition at line 386 of file ruby.h.

## ◆ RUBY__ASAN_DEFAULT_OPTIONS

#define RUBY__ASAN_DEFAULT_OPTIONS

Definition at line 430 of file ruby.h.

## ◆ RUBY_GLOBAL_SETUP

#define RUBY_GLOBAL_SETUP

Value:
RUBY__ASAN_DEFAULT_OPTIONS \
/* RUBY_GLOBAL_SETUP end */

Definition at line 433 of file ruby.h.

## ◆ ruby_start_main

#define ruby_start_main | ( |  | main,
|  |  | argc,
|  |  | argv )

Value:
main(argc, argv)

Definition at line 441 of file ruby.h.

## ◆ RUBY_VM

#define RUBY_VM 1 /* YARV */

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 203 of file ruby.h.

## ◆ USE_SYMBOL_AS_METHOD_NAME

#define USE_SYMBOL_AS_METHOD_NAME 1

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 67 of file ruby.h.

## Function Documentation

## ◆ rb_class2name()

const char * rb_class2name | ( | VALUE | klass | ) |

Queries the name of the passed class.

Parameters

  [in] | klass | An instance of a class.

Returns
  The name of klass.

Note
  Return value is managed by our GC. Don't free.

Definition at line 506 of file variable.c.

Referenced by rb_class2name(), rb_obj_classname(), and rb_profile_frame_classpath().

## ◆ rb_errno()

int rb_errno | ( | void |  | ) |

Identical to system errno.

Returns
  The last set errno number.

Definition at line 2288 of file eval.c.

Referenced by rb_nogvl().

## ◆ rb_errno_ptr()

int * rb_errno_ptr | ( | void |  | ) |

The location of errno.

Returns
  The (thread-specific) location of errno.

Definition at line 2300 of file eval.c.

## ◆ rb_errno_set()

void rb_errno_set | ( | int | err | ) |

Set the errno.

Parameters

  err | New errno.

Postcondition
  errno is now set to err.

Definition at line 2294 of file eval.c.

## ◆ rb_get_path()

VALUE rb_get_path | ( | VALUE | obj | ) |

Converts an object to a path.

It first tries #to_path method if any, then falls back to #to_str method.

Parameters

  [in] | obj | Arbitrary ruby object.

Exceptions

  rb_eArgError | `obj` contains a NUL byte.
  rb_eTypeError | `obj` is not path-ish.
  rb_eEncCompatError | No encoding conversion from `obj` to path.

Returns
  Converted path object.

Definition at line 262 of file file.c.

## ◆ rb_get_path_no_checksafe()

VALUE rb_get_path_no_checksafe | ( | VALUE | obj | ) |

Deprecated
  This function is an alias of rb_get_path() now. The part that did "no_checksafe" was deleted. It remains here because of no harm.

Definition at line 256 of file file.c.

## ◆ rb_obj_classname()

const char * rb_obj_classname | ( | VALUE | obj | ) |

Queries the name of the class of the passed object.

Parameters

  [in] | obj | Arbitrary ruby object.

Returns
  The name of the class of obj.

Note
  Return value is managed by our GC. Don't free.

Definition at line 515 of file variable.c.

Referenced by rb_Hash(), and rb_obj_classname().

## ◆ rb_orig_errno_ptr()

int * rb_orig_errno_ptr | ( | void |  | ) |
| inlinestatic

Not sure if it is necessary for extension libraries but this is where the "bare" errno is located.

Returns
  The location of errno.

Definition at line 381 of file ruby.h.

Referenced by rb_errno(), rb_errno_ptr(), and rb_errno_set().

## ◆ rb_p()

void rb_p | ( | VALUE | obj | ) |

Inspects an object.

It first calls the argument's #inspect method, then feeds its result string into rb_stdout.

This is identical to Ruby level Kernel#p, except it takes only one object.

Definition at line 9056 of file io.c.

## ◆ rb_require()

VALUE rb_require | ( | const char * | feature | ) |

Identical to rb_require_string(), except it takes C's string instead of Ruby's.

Parameters

  [in] | feature | Name of a feature, e.g. "json".

Exceptions

  rb_eLoadError | No such feature.
  rb_eRuntimeError | `$"` is frozen; unable to push. @retval RUBY_Qtrue The feature is loaded for the first time. @retval RUBY_Qfalse The feature has already been loaded. @post <tt>\$\" is updated.

Definition at line 1454 of file load.c.

## ◆ ruby_native_thread_p()

int ruby_native_thread_p | ( | void |  | ) |

Queries if the thread which calls this function is a ruby's thread.

"Ruby's" in this context is a thread created using one of our APIs like rb_thread_create(). There are distinctions between ruby's and other threads. For instance calling ruby methods are allowed only from inside of a ruby's thread.

Return values

  1 | The current thread is a Ruby's thread.
  0 | The current thread is a random thread from outside of Ruby.

Definition at line 5829 of file thread.c.

## ◆ ruby_snprintf()

int ruby_snprintf | ( | char * | str,
|  | size_t | n,
|  | char const * | fmt,
|  |  | ... )

Our own locale-insensitive version of snprintf(3).

It can also be seen as a routine identical to rb_sprintf(), except it writes back to the passed buffer instead of allocating a new Ruby object.

Parameters

  [out] | str | Return buffer
  [in] | n | Number of bytes of str.
  [in] | fmt | A printf-like format specifier.
  [in] | ... | Variadic number of contents to format.

Returns
  Number of bytes that would have been written to str, if n was large enough. Comparing this to n can give you insights that the buffer is too small or too big. Especially passing 0 to n gives you the exact number of bytes necessary to hold the result string without writing anything to anywhere.

Postcondition
  str holds up to n-1 bytes of formatted contents (and the terminating NUL character.)

Definition at line 1041 of file sprintf.c.

Referenced by ruby_snprintf().

## ◆ ruby_vsnprintf()

int ruby_vsnprintf | ( | char * | str,
|  | size_t | n,
|  | char const * | fmt,
|  | va_list | ap )

Identical to ruby_snprintf(), except it takes a va_list.

It can also be seen as a routine identical to rb_vsprintf(), except it writes back to the passed buffer instead of allocating a new Ruby object.

Parameters

  [out] | str | Return buffer
  [in] | n | Number of bytes of str.
  [in] | fmt | A printf-like format specifier.
  [in] | ap | Contents to format.

Returns
  Number of bytes that would have been written to str, if n was large enough. Comparing this to n can give you insights that the buffer is too small or too big. Especially passing 0 to n gives you the exact number of bytes necessary to hold the result string without writing anything to anywhere.

Postcondition
  str holds up to n-1 bytes of formatted contents (and the terminating NUL character.)

Definition at line 1014 of file sprintf.c.

Referenced by ruby_vsnprintf().