Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Functions
file.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

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"
Include dependency graph for file.h:
This graph shows which files directly or indirectly include this file:

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. More...
 
VALUE rb_file_expand_path (VALUE fname, VALUE dname)
 Identical to rb_file_absolute_path(), except it additionally understands ~. More...
 
VALUE rb_file_s_absolute_path (int argc, const VALUE *argv)
 Identical to rb_file_absolute_path(), except how arguments are passed. More...
 
VALUE rb_file_absolute_path (VALUE fname, VALUE dname)
 Maps a relative path to its absolute representation. More...
 
VALUE rb_file_dirname (VALUE fname)
 Strips a file path's last component (and trailing separators if any). More...
 
int rb_find_file_ext (VALUE *feature, const char *const *exts)
 Resolves a feature's path. More...
 
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. More...
 
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. More...
 
VALUE rb_str_encode_ospath (VALUE path)
 Converts a string into an "OS Path" encoding, if any. More...
 
int rb_is_absolute_path (const char *path)
 Queries if the given path is an absolute path. More...
 
rb_off_t rb_file_size (VALUE file)
 Queries the file size of the given file. More...
 

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
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]fnameRelative file name.
[in]dnameLookup base directory name, or in case RUBY_Qnil is passed the process' current working directory is assumed.
Exceptions
rb_eArgErrorStrings contain NUL bytes.
rb_eTypeErrorNon-string passed.
rb_eEncCompatErrorNo conversion from arguments to a path.
Returns
Expanded path.

Definition at line 4265 of file file.c.

Referenced by rb_file_s_absolute_path().

◆ 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]pathString, or IO. In case of IO it issues fstat(2) instead of stat(2).
Exceptions
rb_eFrozenErrorpath is a frozen IO (why...?)
rb_eTypeErrorpath is neither String nor IO.
rb_eArgErrorpath contains NUL bytes.
rb_eEncCompatErrorpath's encoding is not path-compat.
Return values
RUBY_Qtruepath is a directory.
RUBY_QfalseOtherwise.

Definition at line 1620 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]fnameFile name to strip.
Exceptions
rb_eTypeErrorfname is not a String.
rb_eArgErrorfname contains NUL bytes.
rb_eEncCompatErrorfname'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 4890 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]fnameRelative file name.
[in]dnameLookup base directory name, or in case RUBY_Qnil is passed the process' current working directory is assumed.
Exceptions
rb_eArgErrorHome directory is not absolute.
rb_eTypeErrorNon-string passed.
rb_eEncCompatErrorNo conversion from arguments to a path.
Returns
Expanded path.

Definition at line 4211 of file file.c.

Referenced by rb_file_s_expand_path().

◆ 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]argcNumber of objects of argv.
[in]argvFilename, and base directory, in that order.
Exceptions
rb_eArgErrorWrong argc.
rb_eTypeErrorNon-string passed.
rb_eEncCompatErrorNo conversion from arguments to a path.
Returns
Expanded path.

Definition at line 4272 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]argcNumber of objects of argv.
[in]argvFilename, and base directory, in that order.
Exceptions
rb_eArgErrorWrong argc.
rb_eTypeErrorNon-string passed.
rb_eEncCompatErrorNo conversion from arguments to a path.
Returns
Expanded path.

Definition at line 4224 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]fileA file object.
Exceptions
rb_eFrozenErrorfile is frozen.
rb_eIOErrorfile is closed.
rb_eSystemCallErrorPermission denied etc.
rb_eNoMethodErrorThe 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 2522 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]pathA path relative to $LOAD_PATH.
Exceptions
rb_eTypeErrorpath is not a String.
rb_eArgErrorpath contains NUL bytes.
rb_eEncCompatErrorpath's encoding is not path-compat.
Returns
Expanded path.

Definition at line 6589 of file file.c.

Referenced by rb_load().

◆ 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]featureFile to search, and return buffer.
[in]extsList of file extensions.
Exceptions
rb_eTypeErrorfeature is not a String.
rb_eArgErrorfeature contains NUL bytes.
rb_eEncCompatErrorfeature's encoding is not path-compat.
Return values
0Not found
otherwiseFound index in ext, plus one.
Postcondition
*feature is a resolved path.

Definition at line 6530 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]pathA possibly relative path string.
Return values
1path is absolute.
0path is relative.

Definition at line 6350 of file file.c.

Referenced by rb_find_file(), and rb_find_file_ext().

◆ 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]pathAn instance of rb_cString.
Exceptions
rb_eEncCompatErrorpath's encoding is not path-compat.
Returns
path's contents converted to the OS' path encoding.

Definition at line 252 of file file.c.