Ruby: include/ruby/internal/intern/file.h File Reference

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

Functions
file.h File Reference

Public APIs related to rb_cFile. More...

`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
VALUE | rb_file_s_expand_path (int argc, const VALUE *argv)
| Identical to rb_file_expand_path(), except how arguments are passed.
VALUE | rb_file_expand_path (VALUE fname, VALUE dname)
| Identical to rb_file_absolute_path(), except it additionally understands `~`.
VALUE | rb_file_s_absolute_path (int argc, const VALUE *argv)
| Identical to rb_file_absolute_path(), except how arguments are passed.
VALUE | rb_file_absolute_path (VALUE fname, VALUE dname)
| Maps a relative path to its absolute representation.
VALUE | rb_file_dirname (VALUE fname)
| Strips a file path's last component (and trailing separators if any).
int | rb_find_file_ext (VALUE *feature, const char *const *exts)
| Resolves a feature's path.
VALUE | rb_find_file (VALUE path)
| Identical to rb_find_file_ext(), except it takes a feature name and is extension at once, e.g.
VALUE | rb_file_directory_p (VALUE _, VALUE path)
| Queries if the given path is either a directory, or a symlink that (potentially recursively) points to such thing.
VALUE | rb_str_encode_ospath (VALUE path)
| Converts a string into an "OS Path" encoding, if any.
int | rb_is_absolute_path (const char *path)
| Queries if the given path is an absolute path.
rb_off_t | rb_file_size (VALUE file)
| Queries the file size of the given file.

## Detailed Description

Public APIs related to rb_cFile.

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

## Function Documentation

## ◆ rb_file_absolute_path()

VALUE rb_file_absolute_path | ( | VALUE | fname,
|  | VALUE | dname )

Maps a relative path to its absolute representation.

Relative paths are referenced from the passed directory name, or from the process' current working directory in case RUBY_Qnil is passed.

Parameters

  [in] | fname | Relative file name.
  [in] | dname | Lookup base directory name, or in case RUBY_Qnil is passed the process' current working directory is assumed.

Exceptions

  rb_eArgError | Strings contain NUL bytes.
  rb_eTypeError | Non-string passed.
  rb_eEncCompatError | No conversion from arguments to a path.

Returns
  Expanded path.

Definition at line 4167 of file file.c.

## ◆ rb_file_directory_p()

VALUE rb_file_directory_p | ( | VALUE | _,
|  | VALUE | path )

Queries if the given path is either a directory, or a symlink that (potentially recursively) points to such thing.

Parameters

  [in] | _ | Ignored (why...?)
  [in] | path | String, or IO. In case of IO it issues `fstat(2)` instead of `stat(2)`.

Exceptions

  rb_eFrozenError | `path` is a frozen IO (why...?)
  rb_eTypeError | `path` is neither String nor IO.
  rb_eArgError | `path` contains NUL bytes.
  rb_eEncCompatError | `path`'s encoding is not path-compat.

Return values

  RUBY_Qtrue | `path` is a directory.
  RUBY_Qfalse | Otherwise.

Definition at line 1616 of file file.c.

## ◆ rb_file_dirname()

VALUE rb_file_dirname | ( | VALUE | fname | ) |

Strips a file path's last component (and trailing separators if any).

This function is relatively simple on POSIX environments; just splits the input with `/`, strips the last one, if something remains joins them again, otherwise the return value is `"."`. However when it comes to Windows this function is quite very much complicated. We have to take UNC etc. into account. So for instance `"C:foo"`'s dirname is `"C:."`.

Parameters

  [in] | fname | File name to strip.

Exceptions

  rb_eTypeError | `fname` is not a String.
  rb_eArgError | `fname` contains NUL bytes.
  rb_eEncCompatError | `fname`'s encoding is not path-compat.

Returns
  A dirname of `fname`.

Note
  This is a "pure" operation; it computes the return value solely from the passed object and never does any file IO.

Definition at line 4780 of file file.c.

## ◆ rb_file_expand_path()

VALUE rb_file_expand_path | ( | VALUE | fname,
|  | VALUE | dname )

Identical to rb_file_absolute_path(), except it additionally understands `~`.

If a given pathname starts with `~someone/`, that part expands to the user's home directory (or that of current process' owner's in case of `~/`).

Parameters

  [in] | fname | Relative file name.
  [in] | dname | Lookup base directory name, or in case RUBY_Qnil is passed the process' current working directory is assumed.

Exceptions

  rb_eArgError | Home directory is not absolute.
  rb_eTypeError | Non-string passed.
  rb_eEncCompatError | No conversion from arguments to a path.

Returns
  Expanded path.

Definition at line 4113 of file file.c.

## ◆ rb_file_s_absolute_path()

VALUE rb_file_s_absolute_path | ( | int | argc,
|  | const VALUE * | argv )

Identical to rb_file_absolute_path(), except how arguments are passed.

Parameters

  [in] | argc | Number of objects of `argv`.
  [in] | argv | Filename, and base directory, in that order.

Exceptions

  rb_eArgError | Wrong `argc`.
  rb_eTypeError | Non-string passed.
  rb_eEncCompatError | No conversion from arguments to a path.

Returns
  Expanded path.

Definition at line 4174 of file file.c.

## ◆ rb_file_s_expand_path()

VALUE rb_file_s_expand_path | ( | int | argc,
|  | const VALUE * | argv )

Identical to rb_file_expand_path(), except how arguments are passed.

Parameters

  [in] | argc | Number of objects of `argv`.
  [in] | argv | Filename, and base directory, in that order.

Exceptions

  rb_eArgError | Wrong `argc`.
  rb_eTypeError | Non-string passed.
  rb_eEncCompatError | No conversion from arguments to a path.

Returns
  Expanded path.

Definition at line 4126 of file file.c.

## ◆ rb_file_size()

rb_off_t rb_file_size | ( | VALUE | file | ) |

Queries the file size of the given file.

Because this function calls `fstat(2)` internally, it is a failure to pass a closed file to this function.

This function flushes the passed file's buffer if any. Can take time.

Parameters

  [in] | file | A file object.

Exceptions

  rb_eFrozenError | `file` is frozen.
  rb_eIOError | `file` is closed.
  rb_eSystemCallError | Permission denied etc.
  rb_eNoMethodError | The given non-file object doesn't respond to `#size`.

Returns
  The size of the passed file.

Note
  Passing a non-regular file such as a UNIX domain socket to this function is not a failure. But the return value is unpredictable. POSIX's `<sys/stat.h>` states that "the use of this field is unspecified" then.

Definition at line 2528 of file file.c.

## ◆ rb_find_file()

VALUE rb_find_file | ( | VALUE | path | ) |

Identical to rb_find_file_ext(), except it takes a feature name and is extension at once, e.g.

`"json.rb"`. This difference is much like how `require` and `load` are different.

Parameters

  [in] | path | A path relative to `$LOAD_PATH`.

Exceptions

  rb_eTypeError | `path` is not a String.
  rb_eArgError | `path` contains NUL bytes.
  rb_eEncCompatError | `path`'s encoding is not path-compat.

Returns
  Expanded path.

Definition at line 6464 of file file.c.

## ◆ rb_find_file_ext()

int rb_find_file_ext | ( | VALUE * | feature,
|  | const char *const * | exts )

Resolves a feature's path.

This function takes for instance `"json"` and `[".so", ".rb"]`, and iterates over the `$LOAD_PATH` to see if there is either `json.so` or `json.rb` in the directory.

This is not what everything `require` does, but at least `require` is built on top of it.

Parameters

  [in,out] | feature | File to search, and return buffer.
  [in] | exts | List of file extensions.

Exceptions

  rb_eTypeError | `feature` is not a String.
  rb_eArgError | `feature` contains NUL bytes.
  rb_eEncCompatError | `feature`'s encoding is not path-compat.

Return values

  0 | Not found
  otherwise | Found index in `ext`, plus one.

Postcondition
  `*feature` is a resolved path.

Definition at line 6405 of file file.c.

## ◆ rb_is_absolute_path()

int rb_is_absolute_path | ( | const char * | path | ) |

Queries if the given path is an absolute path.

On POSIX environments it is as easy as ‘path[0] == ’/'`. However on Windows, drive letters and UNC paths are also taken into account.

Parameters

  [in] | path | A possibly relative path string.

Return values

  1 | `path` is absolute.
  0 | `path` is relative.

Definition at line 6229 of file file.c.

## ◆ rb_str_encode_ospath()

VALUE rb_str_encode_ospath | ( | VALUE | path | ) |

Converts a string into an "OS Path" encoding, if any.

In most operating systems there are no such things like per-OS default encoding of filename. For them this function is no-op. However most notably on MacOS, pathnames are UTF-8 encoded. It converts the given string into such encoding.

Parameters

  [in] | path | An instance of rb_cString.

Exceptions

  rb_eEncCompatError | `path`'s encoding is not path-compat.

Returns
  `path`'s contents converted to the OS' path encoding.

Definition at line 253 of file file.c.