Ruby: include/ruby/ruby.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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/rgengc.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 "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)
#define | RUBY_VM 1 /* YARV */
#define | HAVE_NATIVETHREAD
#define | InitVM(ext)
| This macro is for internal use.

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

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

## ◆ FilePathStringValue

#define FilePathStringValue | ( |  | v | ) |

Value:
((v) = rb_get_path(v))
rb_get_path
VALUE rb_get_path(VALUE obj)
Converts an object to a path.
Definition file.c:247

Deprecated
  This macro is an alias of FilePathValue now. The part that did "String" was deleted. It remains here because of no harm.

Definition at line 104 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:161

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 91 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 211 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 230 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 202 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 68 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 316 of file variable.c.

Referenced by rb_obj_classname(), and rb_profile_frame_classpath().

## ◆ 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 247 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 241 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 325 of file variable.c.

Referenced by rb_Hash().

## ◆ 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 8978 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 1329 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 5443 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 1045 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 1018 of file sprintf.c.

Referenced by ruby_vsnprintf().