Ruby
3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
|
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. 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... | |
Public APIs related to rb_cFile.
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. __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.
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.
[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. |
rb_eArgError | Strings contain NUL bytes. |
rb_eTypeError | Non-string passed. |
rb_eEncCompatError | No conversion from arguments to a path. |
Definition at line 4265 of file file.c.
Referenced by rb_file_s_absolute_path().
Queries if the given path is either a directory, or a symlink that (potentially recursively) points to such thing.
[in] | _ | Ignored (why...?) |
[in] | path | String, or IO. In case of IO it issues fstat(2) instead of stat(2) . |
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. |
RUBY_Qtrue | path is a directory. |
RUBY_Qfalse | Otherwise. |
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:."
.
[in] | fname | File name to strip. |
rb_eTypeError | fname is not a String. |
rb_eArgError | fname contains NUL bytes. |
rb_eEncCompatError | fname 's encoding is not path-compat. |
fname
. 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 ~/
).
[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. |
rb_eArgError | Home directory is not absolute. |
rb_eTypeError | Non-string passed. |
rb_eEncCompatError | No conversion from arguments to a path. |
Definition at line 4211 of file file.c.
Referenced by rb_file_s_expand_path().
Identical to rb_file_absolute_path(), except how arguments are passed.
[in] | argc | Number of objects of argv . |
[in] | argv | Filename, and base directory, in that order. |
rb_eArgError | Wrong argc . |
rb_eTypeError | Non-string passed. |
rb_eEncCompatError | No conversion from arguments to a path. |
Identical to rb_file_expand_path(), except how arguments are passed.
[in] | argc | Number of objects of argv . |
[in] | argv | Filename, and base directory, in that order. |
rb_eArgError | Wrong argc . |
rb_eTypeError | Non-string passed. |
rb_eEncCompatError | No conversion from arguments to a path. |
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.
[in] | file | A file object. |
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 . |
<sys/stat.h>
states that "the use of
this field is unspecified" then. 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.
[in] | path | A path relative to $LOAD_PATH . |
rb_eTypeError | path is not a String. |
rb_eArgError | path contains NUL bytes. |
rb_eEncCompatError | path 's encoding is not path-compat. |
Definition at line 6589 of file file.c.
Referenced by rb_load().
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.
[in,out] | feature | File to search, and return buffer. |
[in] | exts | List of file extensions. |
rb_eTypeError | feature is not a String. |
rb_eArgError | feature contains NUL bytes. |
rb_eEncCompatError | feature 's encoding is not path-compat. |
0 | Not found |
otherwise | Found index in ext , plus one. |
*feature
is a resolved 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.
[in] | path | A possibly relative path string. |
1 | path is absolute. |
0 | path is relative. |
Definition at line 6350 of file file.c.
Referenced by rb_find_file(), and rb_find_file_ext().
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.
[in] | path | An instance of rb_cString. |
rb_eEncCompatError | path 's encoding is not path-compat. |
path
's contents converted to the OS' path encoding.