/********************************************************************** file.c - $Author$ created at: Mon Nov 15 12:24:34 JST 1993 Copyright (C) 1993-2007 Yukihiro Matsumoto Copyright (C) 2000 Network Applied Communication Laboratory, Inc. Copyright (C) 2000 Information-technology Promotion Agency, Japan **********************************************************************/ #include "ruby/internal/config.h" #include "ruby/internal/attr/nonstring.h" #ifdef _WIN32 # include "missing/file.h" # include "ruby.h" #endif #include #include #ifdef __CYGWIN__ # include #endif #ifdef __APPLE__ # if !(defined(__has_feature) && defined(__has_attribute)) /* Maybe a bug in SDK of Xcode 10.2.1 */ /* In this condition, does not define * API_AVAILABLE and similar, but __API_AVAILABLE and similar which * are defined in */ # define API_AVAILABLE(...) # define API_DEPRECATED(...) # endif # include #endif #ifdef HAVE_UNISTD_H # include #endif #ifdef HAVE_SYS_TIME_H # include #endif #ifdef HAVE_SYS_FILE_H # include #else int flock(int, int); #endif #ifdef HAVE_SYS_PARAM_H # include #endif #ifndef MAXPATHLEN # define MAXPATHLEN 1024 #endif #ifdef HAVE_UTIME_H # include #elif defined HAVE_SYS_UTIME_H # include #endif #ifdef HAVE_PWD_H # include #endif #ifdef HAVE_SYS_SYSMACROS_H # include #endif #include #include #ifdef HAVE_SYS_MKDEV_H # include #endif #if defined(HAVE_FCNTL_H) # include #endif #if defined(HAVE_SYS_TIME_H) # include #endif #if !defined HAVE_LSTAT && !defined lstat # define lstat stat #endif /* define system APIs */ #ifdef _WIN32 # include "win32/file.h" # undef chmod # define chmod(p, m) rb_w32_uchmod((p), (m)) # undef chown # define chown(p, o, g) rb_w32_uchown((p), (o), (g)) # undef lchown # define lchown(p, o, g) rb_w32_ulchown((p), (o), (g)) # undef link # define link(f, t) rb_w32_ulink((f), (t)) # undef readlink # define readlink(f, t, l) rb_w32_ureadlink((f), (t), (l)) # undef symlink # define symlink(s, l) rb_w32_usymlink((s), (l)) # ifdef HAVE_REALPATH /* Don't use native realpath(3) on Windows, as the check for absolute paths does not work for drive letters. */ # undef HAVE_REALPATH # endif #endif /* _WIN32 */ #ifdef HAVE_STRUCT_STATX_STX_BTIME # define ST_(name) stx_ ## name typedef struct statx_timestamp stat_timestamp; #else # define ST_(name) st_ ## name typedef struct timespec stat_timestamp; #endif #if defined _WIN32 || defined __APPLE__ # define USE_OSPATH 1 # define TO_OSPATH(str) rb_str_encode_ospath(str) #else # define USE_OSPATH 0 # define TO_OSPATH(str) (str) #endif /* utime may fail if time is out-of-range for the FS [ruby-dev:38277] */ #if defined DOSISH || defined __CYGWIN__ # define UTIME_EINVAL #endif /* Solaris 10 realpath(3) doesn't support File.realpath */ #if defined HAVE_REALPATH && defined __sun && defined __SVR4 #undef HAVE_REALPATH #endif #ifdef HAVE_REALPATH # include # include #endif #include "dln.h" #include "encindex.h" #include "id.h" #include "internal.h" #include "internal/compilers.h" #include "internal/dir.h" #include "internal/encoding.h" #include "internal/error.h" #include "internal/file.h" #include "internal/io.h" #include "internal/load.h" #include "internal/object.h" #include "internal/process.h" #include "internal/thread.h" #include "internal/vm.h" #include "ruby/encoding.h" #include "ruby/thread.h" #include "ruby/util.h" #define UIANY2NUM(x) \ ((sizeof(x) <= sizeof(unsigned int)) ? \ UINT2NUM((unsigned)(x)) : \ (sizeof(x) <= sizeof(unsigned long)) ? \ ULONG2NUM((unsigned long)(x)) : \ ULL2NUM((unsigned LONG_LONG)(x))) VALUE rb_cFile; VALUE rb_mFileTest; VALUE rb_cStat; static VALUE file_path_convert(VALUE name) { #ifndef _WIN32 /* non Windows == Unix */ int fname_encidx = ENCODING_GET(name); int fs_encidx; if (ENCINDEX_US_ASCII != fname_encidx && ENCINDEX_ASCII_8BIT != fname_encidx && (fs_encidx = rb_filesystem_encindex()) != fname_encidx && rb_default_internal_encoding() && !rb_enc_str_asciionly_p(name)) { /* Don't call rb_filesystem_encoding() before US-ASCII and ASCII-8BIT */ /* fs_encoding should be ascii compatible */ rb_encoding *fname_encoding = rb_enc_from_index(fname_encidx); rb_encoding *fs_encoding = rb_enc_from_index(fs_encidx); name = rb_str_conv_enc(name, fname_encoding, fs_encoding); } #endif return name; } static void check_path_encoding(VALUE str) { if (RB_UNLIKELY(!rb_str_enc_fastpath(str))) { rb_encoding *enc = rb_str_enc_get(str); if (!rb_enc_asciicompat(enc)) { rb_raise(rb_eEncCompatError, "path name must be ASCII-compatible (%s): %"PRIsVALUE, rb_enc_name(enc), rb_str_inspect(str)); } } } VALUE rb_get_path_check_to_string(VALUE obj) { VALUE tmp; ID to_path; if (RB_TYPE_P(obj, T_STRING)) { return obj; } CONST_ID(to_path, "to_path"); tmp = rb_check_funcall_default(obj, to_path, 0, 0, obj); StringValue(tmp); return tmp; } VALUE rb_get_path_check_convert(VALUE obj) { obj = file_path_convert(obj); rb_get_path_check_no_convert(obj); return rb_str_new_frozen(obj); } /* TODO: name */ VALUE rb_get_path_check_no_convert(VALUE obj) { check_path_encoding(obj); if (!rb_str_to_cstr(obj)) { rb_raise(rb_eArgError, "path name contains null byte"); } return obj; } VALUE rb_get_path_no_checksafe(VALUE obj) { return rb_get_path(obj); } VALUE rb_get_path(VALUE obj) { return rb_get_path_check_convert(rb_get_path_check_to_string(obj)); } static inline VALUE check_path(VALUE obj, const char **cstr) { VALUE str = rb_get_path_check_convert(rb_get_path_check_to_string(obj)); #if RUBY_DEBUG str = rb_str_new_frozen(str); #endif *cstr = RSTRING_PTR(str); return str; } #define CheckPath(str, cstr) RB_GC_GUARD(str) = check_path(str, &cstr); VALUE rb_str_encode_ospath(VALUE path) { #if USE_OSPATH int encidx = ENCODING_GET(path); if (encidx != ENCINDEX_ASCII_8BIT && encidx != ENCINDEX_UTF_8) { rb_encoding *enc = rb_enc_from_index(encidx); rb_encoding *utf8 = rb_utf8_encoding(); path = rb_str_conv_enc(path, enc, utf8); } #endif /* USE_OSPATH */ return path; } #ifdef __APPLE__ # define NORMALIZE_UTF8PATH 1 # ifdef HAVE_WORKING_FORK static CFMutableStringRef mutable_CFString_new(CFStringRef *s, const char *ptr, rb_len_t len) { const CFAllocatorRef alloc = kCFAllocatorDefault; *s = CFStringCreateWithBytesNoCopy(alloc, (const UInt8 *)ptr, len, kCFStringEncodingUTF8, FALSE, kCFAllocatorNull); return CFStringCreateMutableCopy(alloc, len, *s); } # define mutable_CFString_release(m, s) (CFRelease(m), CFRelease(s)) static void rb_CFString_class_initialize_before_fork(void) { /* * Since macOS 13, CFString family API used in * rb_str_append_normalized_ospath may internally use Objective-C classes * (NSTaggedPointerString and NSPlaceholderMutableString) for small strings. * * On the other hand, Objective-C classes should not be used for the first * time in a fork()'ed but not exec()'ed process. Violations for this rule * can result deadlock during class initialization, so Objective-C runtime * conservatively crashes on such cases by default. * * Therefore, we need to use CFString API to initialize Objective-C classes * used internally *before* fork(). * * For future changes, please note that this initialization process cannot * be done in ctor because NSTaggedPointerString in CoreFoundation is enabled * after CFStringInitializeTaggedStrings(), which is called during loading * Objective-C runtime after ctor. * For more details, see https://bugs.ruby-lang.org/issues/18912 */ /* Enough small but non-empty ASCII string to fit in NSTaggedPointerString. */ const char small_str[] = "/"; rb_len_t len = sizeof(small_str) - 1; CFStringRef s; /* * Touch `CFStringCreateWithBytesNoCopy` *twice* because the implementation * shipped with macOS 15.0 24A5331b does not return `NSTaggedPointerString` * instance for the first call (totally not sure why). CoreFoundation * shipped with macOS 15.1 does not have this issue. */ for (int i = 0; i < 2; i++) { CFMutableStringRef m = mutable_CFString_new(&s, small_str, len); mutable_CFString_release(m, s); } } # endif /* HAVE_WORKING_FORK */ static VALUE rb_str_append_normalized_ospath(VALUE str, const char *ptr, rb_len_t len) { CFIndex buflen = 0; CFRange all; CFStringRef s; CFMutableStringRef m = mutable_CFString_new(&s, ptr, len); rb_len_t oldlen = RSTRING_LEN(str); CFStringNormalize(m, kCFStringNormalizationFormC); all = CFRangeMake(0, CFStringGetLength(m)); CFStringGetBytes(m, all, kCFStringEncodingUTF8, '?', FALSE, NULL, 0, &buflen); rb_str_modify_expand(str, buflen); CFStringGetBytes(m, all, kCFStringEncodingUTF8, '?', FALSE, (UInt8 *)(RSTRING_PTR(str) + oldlen), buflen, &buflen); rb_str_set_len(str, oldlen + buflen); mutable_CFString_release(m, s); return str; } VALUE rb_str_normalize_ospath(const char *ptr, rb_len_t len) { const char *p = ptr; const char *e = ptr + len; const char *p1 = p; rb_encoding *enc = rb_utf8_encoding(); VALUE str = rb_utf8_str_new(ptr, len); if (RB_LIKELY(rb_enc_str_coderange(str) == ENC_CODERANGE_7BIT)) { return str; } else { str = rb_str_buf_new(len); rb_enc_associate(str, enc); } while (p < e) { int l, c; int r = rb_enc_precise_mbclen(p, e, enc); if (!MBCLEN_CHARFOUND_P(r)) { /* invalid byte shall not happen but */ RBIMPL_ATTR_NONSTRING() static const char invalid[3] = "\xEF\xBF\xBD"; rb_str_append_normalized_ospath(str, p1, p-p1); rb_str_cat(str, invalid, sizeof(invalid)); p += 1; p1 = p; continue; } l = MBCLEN_CHARFOUND_LEN(r); c = rb_enc_mbc_to_codepoint(p, e, enc); if ((0x2000 <= c && c <= 0x2FFF) || (0xF900 <= c && c <= 0xFAFF) || (0x2F800 <= c && c <= 0x2FAFF)) { if (p - p1 > 0) { rb_str_append_normalized_ospath(str, p1, p-p1); } rb_str_cat(str, p, l); p += l; p1 = p; } else { p += l; } } if (p - p1 > 0) { rb_str_append_normalized_ospath(str, p1, p-p1); } return str; } static int ignored_char_p(const char *p, const char *e, rb_encoding *enc) { unsigned char c; if (p+3 > e) return 0; switch ((unsigned char)*p) { case 0xe2: switch ((unsigned char)p[1]) { case 0x80: c = (unsigned char)p[2]; /* c >= 0x200c && c <= 0x200f */ if (c >= 0x8c && c <= 0x8f) return 3; /* c >= 0x202a && c <= 0x202e */ if (c >= 0xaa && c <= 0xae) return 3; return 0; case 0x81: c = (unsigned char)p[2]; /* c >= 0x206a && c <= 0x206f */ if (c >= 0xaa && c <= 0xaf) return 3; return 0; } break; case 0xef: /* c == 0xfeff */ if ((unsigned char)p[1] == 0xbb && (unsigned char)p[2] == 0xbf) return 3; break; } return 0; } #else /* !__APPLE__ */ # define NORMALIZE_UTF8PATH 0 #endif /* __APPLE__ */ #define apply2args(n) (rb_check_arity(argc, n, UNLIMITED_ARGUMENTS), argc-=n) struct apply_filename { const char *ptr; VALUE path; }; struct apply_arg { int i; int argc; int errnum; int (*func)(const char *, void *); void *arg; struct apply_filename fn[FLEX_ARY_LEN]; }; static void * no_gvl_apply2files(void *ptr) { struct apply_arg *aa = ptr; for (aa->i = 0; aa->i < aa->argc; aa->i++) { if (aa->func(aa->fn[aa->i].ptr, aa->arg) < 0) { aa->errnum = errno; break; } } return 0; } #ifdef UTIME_EINVAL NORETURN(static void utime_failed(struct apply_arg *)); static int utime_internal(const char *, void *); #endif static VALUE apply2files(int (*func)(const char *, void *), int argc, VALUE *argv, void *arg) { VALUE v; const size_t size = sizeof(struct apply_filename); const rb_len_t len = (rb_len_t)(offsetof(struct apply_arg, fn) + (size * argc)); struct apply_arg *aa = ALLOCV(v, len); aa->errnum = 0; aa->argc = argc; aa->arg = arg; aa->func = func; for (aa->i = 0; aa->i < argc; aa->i++) { VALUE path = rb_get_path(argv[aa->i]); path = rb_str_encode_ospath(path); aa->fn[aa->i].ptr = RSTRING_PTR(path); aa->fn[aa->i].path = path; } IO_WITHOUT_GVL(no_gvl_apply2files, aa); if (aa->errnum) { #ifdef UTIME_EINVAL if (func == utime_internal) { utime_failed(aa); } #endif rb_syserr_fail_path(aa->errnum, aa->fn[aa->i].path); } if (v) { ALLOCV_END(v); } return LONG2FIX(argc); } static stat_timestamp stat_atimespec(const struct stat *st); static stat_timestamp stat_mtimespec(const struct stat *st); static stat_timestamp stat_ctimespec(const struct stat *st); static const rb_data_type_t stat_data_type = { "stat", { NULL, RUBY_TYPED_DEFAULT_FREE, NULL, // No external memory to report }, 0, 0, RUBY_TYPED_THREAD_SAFE_FREE | RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_EMBEDDABLE }; struct rb_stat { rb_io_stat_data stat; bool initialized; }; static struct rb_stat * stat_alloc(VALUE klass, VALUE *obj) { struct rb_stat *rb_st; *obj = TypedData_Make_Struct(klass, struct rb_stat, &stat_data_type, rb_st); return rb_st; } VALUE rb_stat_new(const struct stat *st) { VALUE obj; struct rb_stat *rb_st = stat_alloc(rb_cStat, &obj); if (st) { #if RUBY_USE_STATX # define CP(m) .stx_ ## m = st->st_ ## m # define CP_32(m) .stx_ ## m = (uint32_t)st->st_ ## m # define CP_TS(m) .stx_ ## m = stat_ ## m ## spec(st) rb_st->stat = (struct statx){ .stx_mask = STATX_BASIC_STATS, CP(mode), CP_32(nlink), CP(uid), CP(gid), CP_TS(atime), CP_TS(mtime), CP_TS(ctime), CP(ino), CP(size), CP(blocks), }; # undef CP # undef CP_TS #else rb_st->stat = *st; #endif rb_st->initialized = true; } return obj; } #ifndef rb_statx_new VALUE rb_statx_new(const rb_io_stat_data *st) { VALUE obj; struct rb_stat *rb_st = stat_alloc(rb_cStat, &obj); if (st) { rb_st->stat = *st; rb_st->initialized = true; } return obj; } #endif static rb_io_stat_data* get_stat(VALUE self) { struct rb_stat* rb_st; TypedData_Get_Struct(self, struct rb_stat, &stat_data_type, rb_st); if (!rb_st->initialized) rb_raise(rb_eTypeError, "uninitialized File::Stat"); return &rb_st->stat; } #if RUBY_USE_STATX static stat_timestamp statx_mtimespec(const rb_io_stat_data *st) { return st->stx_mtime; } #else # define statx_mtimespec stat_mtimespec #endif /* * :markup: markdown * * call-seq: * self <=> other -> -1, 0, 1, or nil * * Compares the [snapshots](rdoc-ref:File::Stat@Snapshot) * in `self` and `other`, by comparing their modification times * `self.mtime` and `other.mtime`. * * Returns: * * - `-1`, if `self.mtime` is earlier. * - `0`, if the two values are equal. * - `1`, if `self.mtime` is later. * - `nil`, if `other` is not a \File::Stat object. * * Examples: * * ```ruby * stat0 = File.stat('/etc') * stat1 = File.stat('/tmp') * stat0.mtime # => 2026-10-02 07:52:03.151556038 -0500 * stat1.mtime # => 2026-10-03 12:22:25.719215899 -0500 * stat0 <=> stat1 # => -1 * stat0 <=> stat0.dup # => 0 * stat1 <=> stat0 # => 1 * stat0 <=> :foo # => nil * ``` * * \Class \File::Stat includes module Comparable, * each of whose methods uses \File::Stat#<=> for comparison. */ static VALUE rb_stat_cmp(VALUE self, VALUE other) { if (rb_obj_is_kind_of(other, rb_obj_class(self))) { stat_timestamp ts1 = statx_mtimespec(get_stat(self)); stat_timestamp ts2 = statx_mtimespec(get_stat(other)); if (ts1.tv_sec == ts2.tv_sec) { if (ts1.tv_nsec == ts2.tv_nsec) return INT2FIX(0); if (ts1.tv_nsec < ts2.tv_nsec) return INT2FIX(-1); return INT2FIX(1); } if (ts1.tv_sec < ts2.tv_sec) return INT2FIX(-1); return INT2FIX(1); } return Qnil; } #define ST2UINT(val) ((val) & ~(~1UL << (sizeof(val) * CHAR_BIT - 1))) #ifndef NUM2DEVT # define NUM2DEVT(v) NUM2UINT(v) #endif #ifndef DEVT2NUM # define DEVT2NUM(v) UINT2NUM(v) #endif #ifndef PRI_DEVT_PREFIX # define PRI_DEVT_PREFIX "" #endif /* * :markup: markdown * * call-seq: * dev -> integer * * Returns the device number for the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc').dev # => 66306 * File.stat('/dev').dev # => 5 * ``` * */ static VALUE rb_stat_dev(VALUE self) { #if RUBY_USE_STATX unsigned int m = get_stat(self)->stx_dev_major; unsigned int n = get_stat(self)->stx_dev_minor; return ULL2NUM(makedev(m, n)); #elif SIZEOF_STRUCT_STAT_ST_DEV <= SIZEOF_DEV_T return DEVT2NUM(get_stat(self)->st_dev); #elif SIZEOF_STRUCT_STAT_ST_DEV <= SIZEOF_LONG return ULONG2NUM(get_stat(self)->st_dev); #else return ULL2NUM(get_stat(self)->st_dev); #endif } /* * :markup: markdown * * call-seq: * dev_major -> integer * * Returns `nil` on Windows. * * On other systems, returns the major part of the device number * for the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc').dev_major # => 259 * File.stat('/dev').dev_major # => 0 * ``` * */ static VALUE rb_stat_dev_major(VALUE self) { #if RUBY_USE_STATX return UINT2NUM(get_stat(self)->stx_dev_major); #elif defined(major) return UINT2NUM(major(get_stat(self)->st_dev)); #else return Qnil; #endif } /* * :markup: markdown * * call-seq: * dev_minor -> integer * * Returns `nil` on Windows. * * On other systems, returns the minor part of the device number * for the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc').dev_minor # => 2 * File.stat('/dev').dev_minor # => 5 * ``` * */ static VALUE rb_stat_dev_minor(VALUE self) { #if RUBY_USE_STATX return UINT2NUM(get_stat(self)->stx_dev_minor); #elif defined(minor) return UINT2NUM(minor(get_stat(self)->st_dev)); #else return Qnil; #endif } /* * :markup: markdown * * call-seq: * ino -> integer * * Returns the inode value for the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc').ino # => 11141121 * File.stat('/etc/passwd').ino # => 11141413 * ``` * */ static VALUE rb_stat_ino(VALUE self) { rb_io_stat_data *ptr = get_stat(self); #ifdef HAVE_STRUCT_STAT_ST_INOHIGH /* assume INTEGER_PACK_LSWORD_FIRST and st_inohigh is just next of st_ino */ return rb_integer_unpack(&ptr->st_ino, 2, SIZEOF_STRUCT_STAT_ST_INO, 0, INTEGER_PACK_LSWORD_FIRST|INTEGER_PACK_NATIVE_BYTE_ORDER| INTEGER_PACK_2COMP); #else return UIANY2NUM(ptr->ST_(ino)); #endif } /* * :markup: markdown * * call-seq: * mode -> integer * * Returns an integer representing the permissions of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`; * see [Filesystem Modes](rdoc-ref:file/filesystem_modes.md). * * The integer is most usefully formatted as six octal digits: * * ```ruby * '%06o' % File.stat('/etc').mode # => "040755" * '%06o' % File.stat('/etc/passwd').mode # => "100644" * ``` * */ static VALUE rb_stat_mode(VALUE self) { return UINT2NUM(ST2UINT(get_stat(self)->ST_(mode))); } /* * :markup: markdown * * call-seq: * nlink -> integer * * Returns the number of [hard links](rdoc-ref:file/hard_links.md) to the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * filepath = '/tmp/t.txt' * File.write(filepath, 'foo') # Creates hard link. * stat0 = File.stat(filepath) # Take snapshot. * stat0.nlink # => 1 # One hard link. * linkpath = '/tmp/t.bak' * File.link(filepath, linkpath) # Creates another hard link. * stat0.nlink # => 1 # Snapshot not updated. * stat1 = File.stat(filepath) # Take new snapshot. * stat1.nlink # => 2 # Updated nlink count. * File.unlink(linkpath) # Remove one hard link. * stat1.nlink # => 2 # Snapshot not updated. * stat2 = File.stat(filepath) # Take new shapshot. * stat2.nlink # => 1 # Updated nlink count. * File.unlink(filepath) # Clean up. * ``` * */ static VALUE rb_stat_nlink(VALUE self) { /* struct stat::st_nlink is nlink_t in POSIX. Not the case for Windows. */ const rb_io_stat_data *ptr = get_stat(self); return UIANY2NUM(ptr->ST_(nlink)); } /* * :markup: markdown * * call-seq: * uid -> integer * * Returns the integer id of the owner of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * Process.uid # => 0 # Superuser; can change owner. * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') # Create file. * stat0 = File.stat(filepath) # Take snapshot. * stat0.uid # => 0 # Snapshot has uid. * File.chown(1000, 1000, filepath) # Change owner. * stat0.uid # => 0 # Snapshot not updated. * stat1 = File.stat(filepath) # Take new snapshot. * stat1.uid # => 1000 # Snapshot has new uid. * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_stat_uid(VALUE self) { return UIDT2NUM(get_stat(self)->ST_(uid)); } /* * :markup: markdown * * call-seq: * gid -> integer * * On Windows, returns `0`. * * On other systems, returns the group identifier of the owner of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc').gid # => 0 * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.stat(filepath).gid # => 1000 * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_stat_gid(VALUE self) { return GIDT2NUM(get_stat(self)->ST_(gid)); } /* * :markup: markdown * * call-seq: * rdev -> integer or nil * * Returns the integer device type of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`. * * On a non-Windows system, returns a filesystem-dependent device type; * the returned value is non-zero only for character-special * and block-special devices. * * In these hexadecimal-formatted examples: * * - The two-low order digits contain the device-type minor value, * which identifies a specific instance, port, or partition managed by a device driver; * see #rdev_minor. * - The higher-order digits contain the device-type major value, * which identifies the device driver; * see #rdev_major. * * ```ruby * # Character-special devices. * '%08x' % File.stat('/dev/null').rdev # => "00000103" * '%08x' % File.stat('/dev/zero').rdev # => "00000105" * '%08x' % File.stat('/dev/random').rdev # => "00000108" * '%08x' % File.stat('/dev/tty').rdev # => "00000500" * '%08x' % File.stat('/dev/tty0').rdev # => "00000400" * '%08x' % File.stat('/dev/tty1').rdev # => "00000401" * # Block-special devices. * '%08x' % File.stat('/dev/nvme0n1').rdev # => "00010300" * '%08x' % File.stat('/dev/nvme0n1p1').rdev # => "00010301" * '%08x' % File.stat('/dev/nvme0n1p2').rdev # => "00010302" * ``` * * On Windows, returns a number corresponding to the given device: * * ```ruby * File.stat('C:/').rdev # => 2 * File.stat('C:/Users').rdev # => 2 * File.stat('D:/').rdev # => 3 * ``` * */ static VALUE rb_stat_rdev(VALUE self) { #if RUBY_USE_STATX unsigned int m = get_stat(self)->stx_rdev_major; unsigned int n = get_stat(self)->stx_rdev_minor; return ULL2NUM(makedev(m, n)); #elif !defined(HAVE_STRUCT_STAT_ST_RDEV) return Qnil; #elif SIZEOF_STRUCT_STAT_ST_RDEV <= SIZEOF_DEV_T return DEVT2NUM(get_stat(self)->ST_(rdev)); #elif SIZEOF_STRUCT_STAT_ST_RDEV <= SIZEOF_LONG return ULONG2NUM(get_stat(self)->ST_(rdev)); #else return ULL2NUM(get_stat(self)->ST_(rdev)); #endif } /* * :markup: markdown * * call-seq: * rdev_major -> integer * * Returns the integer major portion of the device type of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`; * see also #rdev, which returns the entire device type (major and minor). * * On a non-Windows system, returns a filesystem-dependent major device type, * which identifies the device driver; * the returned value is non-zero only for character-special * and block-special devices: * * ```ruby * # Character-special devices. * '%04x' % File.stat('/dev/null').rdev_major # => "0001" * '%04x' % File.stat('/dev/zero').rdev_major # => "0001" * '%04x' % File.stat('/dev/random').rdev_major # => "0001" * '%04x' % File.stat('/dev/tty').rdev_major # => "0005" * '%04x' % File.stat('/dev/tty0').rdev_major # => "0004" * '%04x' % File.stat('/dev/tty1').rdev_major # => "0004" * # Block-special devices. * '%04x' % File.stat('/dev/nvme0n1').rdev_major # => "0103" * '%04x' % File.stat('/dev/nvme0n1p1').rdev_major # => "0103" * '%04x' % File.stat('/dev/nvme0n1p2').rdev_major # => "0103" * ``` * * On Windows, returns `nil`. */ static VALUE rb_stat_rdev_major(VALUE self) { #if RUBY_USE_STATX return UINT2NUM(get_stat(self)->stx_rdev_major); #elif defined(HAVE_STRUCT_STAT_ST_RDEV) && defined(major) return UINT2NUM(major(get_stat(self)->ST_(rdev))); #else return Qnil; #endif } /* * :markup: markdown * * call-seq: * rdev_minor -> integer * * Returns the integer minor portion of the device type of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`; * see also #rdev, which returns the entire device type (major and minor). * * On a non-Windows system, returns a filesystem-dependent minor device type, * which identifies a specific instance, port, or partition on its device; * the returned value is non-zero only for character-special * and block-special devices: * * ```ruby * # Character-special devices. * '%02x' % File.stat('/dev/null').rdev_minor # => "03" * '%02x' % File.stat('/dev/zero').rdev_minor # => "05" * '%02x' % File.stat('/dev/random').rdev_minor # => "08" * '%02x' % File.stat('/dev/tty').rdev_minor # => "00" * '%02x' % File.stat('/dev/tty0').rdev_minor # => "00" * '%02x' % File.stat('/dev/tty1').rdev_minor # => "01" * # Block-special devices. * '%02x' % File.stat('/dev/nvme0n1').rdev_minor # => "00" * '%02x' % File.stat('/dev/nvme0n1p1').rdev_minor # => "01" * '%02x' % File.stat('/dev/nvme0n1p2').rdev_minor # => "02" * ``` * * On Windows, returns `nil`. */ static VALUE rb_stat_rdev_minor(VALUE self) { #if RUBY_USE_STATX return UINT2NUM(get_stat(self)->stx_rdev_minor); #elif defined(HAVE_STRUCT_STAT_ST_RDEV) && defined(minor) return UINT2NUM(minor(get_stat(self)->ST_(rdev))); #else return Qnil; #endif } /* * :markup: markdown * * call-seq: * size -> integer * * Returns the size (in bytes) of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc/passwd').size # => 3092 # Regular file. * File.stat('/etc').size # => 12288 # Directory. * # When the file size changes. * filepath = '/tmp/t.tmp' * file = File.new(filepath, 'w+') * file.write('foo') * file.size # => 3 * stat0 = File.stat(filepath) # Take snapshot. * stat0.size # => 3 * file.write('bar') # Change file size. * file.size # => 6 * stat0.size # => 3 # Snapshot not updated. * stat1 = File.stat(filepath) # Take new snapshot. * stat1.size # => 6 # Snapshot has updated size. * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_stat_size(VALUE self) { return OFFT2NUM(get_stat(self)->ST_(size)); } /* * :markup: markdown * * call-seq: * blksize -> integer or nil * * Returns the block size of the filesystem * of the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`, * or `nil` on Windows: * * ```ruby * File.stat('/etc').blksize # => 4096 * File.stat('/etc/passwd').blksize # => 4096 * File.stat('nosuch').blksize # Raises Errno::ENOENT: No such file or directory. * ``` * */ static VALUE rb_stat_blksize(VALUE self) { #ifdef HAVE_STRUCT_STAT_ST_BLKSIZE return ULONG2NUM(get_stat(self)->ST_(blksize)); #else return Qnil; #endif } /* * :markup: markdown * * call-seq: * blocks -> integer or nil * * Returns the number of filesystem blocks allocated for the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * File.stat('/etc').blocks # => 24 * File.stat('/etc/passwd').blocks # => 8 * ``` * * Returns `nil` on Windows. */ static VALUE rb_stat_blocks(VALUE self) { #ifdef HAVE_STRUCT_STAT_ST_BLOCKS # if SIZEOF_STRUCT_STAT_ST_BLOCKS > SIZEOF_LONG return ULL2NUM(get_stat(self)->ST_(blocks)); # else return ULONG2NUM(get_stat(self)->ST_(blocks)); # endif #else return Qnil; #endif } static stat_timestamp stat_atimespec(const struct stat *st) { stat_timestamp ts; ts.tv_sec = st->st_atime; #if defined(HAVE_STRUCT_STAT_ST_ATIM) ts.tv_nsec = (uint32_t)st->st_atim.tv_nsec; #elif defined(HAVE_STRUCT_STAT_ST_ATIMESPEC) ts.tv_nsec = (uint32_t)st->st_atimespec.tv_nsec; #elif defined(HAVE_STRUCT_STAT_ST_ATIMENSEC) ts.tv_nsec = (uint32_t)st->st_atimensec; #else ts.tv_nsec = 0 #endif return ts; } #if RUBY_USE_STATX static stat_timestamp statx_atimespec(const rb_io_stat_data *st) { return st->stx_atime; } #else # define statx_atimespec stat_atimespec #endif static VALUE stat_time(const stat_timestamp ts) { return rb_time_nano_new(ts.tv_sec, ts.tv_nsec); } static VALUE stat_atime(const struct stat *st) { return stat_time(stat_atimespec(st)); } static stat_timestamp stat_mtimespec(const struct stat *st) { stat_timestamp ts; ts.tv_sec = st->st_mtime; #if defined(HAVE_STRUCT_STAT_ST_MTIM) ts.tv_nsec = (uint32_t)st->st_mtim.tv_nsec; #elif defined(HAVE_STRUCT_STAT_ST_MTIMESPEC) ts.tv_nsec = (uint32_t)st->st_mtimespec.tv_nsec; #elif defined(HAVE_STRUCT_STAT_ST_MTIMENSEC) ts.tv_nsec = (uint32_t)st->st_mtimensec; #else ts.tv_nsec = 0; #endif return ts; } static VALUE stat_mtime(const struct stat *st) { return stat_time(stat_mtimespec(st)); } static stat_timestamp stat_ctimespec(const struct stat *st) { stat_timestamp ts; ts.tv_sec = st->st_ctime; #if defined(HAVE_STRUCT_STAT_ST_CTIM) ts.tv_nsec = (uint32_t)st->st_ctim.tv_nsec; #elif defined(HAVE_STRUCT_STAT_ST_CTIMESPEC) ts.tv_nsec = (uint32_t)st->st_ctimespec.tv_nsec; #elif defined(HAVE_STRUCT_STAT_ST_CTIMENSEC) ts.tv_nsec = (uint32_t)st->st_ctimensec; #else ts.tv_nsec = 0; #endif return ts; } #if RUBY_USE_STATX static stat_timestamp statx_ctimespec(const rb_io_stat_data *st) { return st->stx_ctime; } #else # define statx_ctimespec stat_ctimespec #endif static VALUE stat_ctime(const struct stat *st) { return stat_time(stat_ctimespec(st)); } #define HAVE_STAT_BIRTHTIME #if defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC) static VALUE statx_birthtime(const rb_io_stat_data *st) { const stat_timestamp *ts = &st->ST_(birthtimespec); return rb_time_nano_new(ts->tv_sec, ts->tv_nsec); } #elif defined(HAVE_STRUCT_STATX_STX_BTIME) static VALUE statx_birthtime(const rb_io_stat_data *st); #elif defined(_WIN32) # define statx_birthtime stat_ctime #else # undef HAVE_STAT_BIRTHTIME #endif /* defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC) */ /* * :markup: markdown * * call-seq: * atime -> time * * Returns a new Time object containing the access time * of the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`. * See {File System Timestamps}[rdoc-ref:file/timestamps.md]. * * Access time for a file is established when it is created, * and may be updated when the file content is read: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.atime(filepath) # => 2026-10-04 14:58:58.805179514 -0500 * stat0 = File.stat(filepath) # Take snapshot. * stat0.atime # => 2026-10-04 14:58:58.805179514 -0500 * File.read(filepath) # Updates file atime. * File.atime(filepath) # => 2026-10-04 14:59:47.707059351 -0500 * stat0.atime # => 2026-10-04 14:58:58.805179514 -0500 # Not updated. * stat1 = File.stat(filepath) # Take new snapshot. * stat1.atime # => 2026-10-04 14:59:47.707059351 -0500 # Updated. * File.delete(filepath) # Clean up. * ``` * * Access time for a directory is established when it is created, * and may be updated when its entries are read: * * ```ruby * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) * File.atime(dirpath) # => 2026-10-04 15:07:26.194548647 -0500 * stat0 = File.stat(dirpath) # Take snapshot. * stat0.atime # => 2026-10-04 15:07:26.194548647 -0500 * Dir.entries(dirpath) # Updates directory atime. * File.atime(dirpath) # => 2026-10-04 15:08:14.818746815 -0500 # Updated. * stat0.atime # => 2026-10-04 15:07:26.194548647 -0500 # Not updated. * stat1 = File.stat(dirpath) # Take new shapshot. * stat1.atime # => 2026-10-04 15:08:14.818746815 -0500 # Updated. * Dir.rmdir(dirpath) # Clean up. * */ static VALUE rb_stat_atime(VALUE self) { return stat_time(statx_atimespec(get_stat(self))); } /* * :markup: markdown * call-seq: * mtime -> time * * Returns a new Time object containing * the [modification time](rdoc-ref:file/timestamps.md@Modification+Time) * of the object in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') # Create file. * File.mtime(filepath) # => 2026-10-13 10:48:10.477675435 -0500 # File mtime. * stat0 = File.stat(filepath) # Take snapshot. * stat0.mtime # => 2026-10-13 10:48:10.477675435 -0500 # Snapshot mtime. * File.write(filepath, 'bar') # Modify file. * File.mtime(filepath) # => 2026-10-13 10:48:37.584264035 -0500 # File mtime updated. * stat0.mtime # => 2026-10-13 10:48:10.477675435 -0500 # Snapshot mtime not updated. * stat1 = File.stat(filepath) # Take new snapshot. * stat1.mtime # => 2026-10-13 10:48:37.584264035 -0500 # New snapshot mtime. * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_stat_mtime(VALUE self) { return stat_time(statx_mtimespec(get_stat(self))); } /* * :markup: markdown * * call-seq: * ctime -> time * * On Windows, returns the birthtime for the entry in `self`. * * On other systems, returns the time of the most recent metadata change * to the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) # Establishes directory ctime. * dirstat0 = File.stat(dirpath) # Take directory snapshot. * dirstat0.ctime # => 2026-10-06 11:07:18.073533542 -0500 # Initial directory ctime. * filepath = File.join(dirpath, 't.tmp') # => "/tmp/dir/t.tmp" * File.write(filepath, 'foo') # Establishes file ctime; upates directory ctime. * filestat0 = File.stat(filepath) # Take file snapshot. * filestat0.ctime # => 2026-10-06 11:07:52.555027213 -0500 # Initial file ctime. * dirstat0.ctime # => 2026-10-06 11:07:18.073533542 -0500 # Directory snapshot unchanged. * dirstat1 = File.stat(dirpath) # Take new directory snapshot. * dirstat1.ctime # => 2026-10-06 11:07:52.555027213 -0500 # Snapshot has new ctime. * File.write(filepath, 'bar') # Updates file ctime. * filestat0.ctime # => 2026-10-06 11:07:52.555027213 -0500 # Old file snapshot unchanged. * filestat1 = File.stat(filepath) # Take new file snapshot. * filestat1.ctime # => 2026-10-06 11:14:11.19290223 -0500 # Snapshot shows change. * FileUtils.rmtree(dirpath) # Clean up. * ``` * * See {File System Timestamps}[rdoc-ref:file/timestamps.md]. */ static VALUE rb_stat_ctime(VALUE self) { return stat_time(statx_ctimespec(get_stat(self))); } #if defined(HAVE_STAT_BIRTHTIME) /* * :markup: markdown * * call-seq: * birthtime -> new_time * * Returns a new Time object containing the creation time * of the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`. * See {File System Timestamps}[rdoc-ref:file/timestamps.md]: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * stat = File.stat(filepath) # Take shapshot. * stat.birthtime # => 2026-10-05 13:14:24.844158315 -0500 * File.delete(filepath) * stat.birthtime # => 2026-10-05 13:14:24.844158315 -0500 # Unchanged. * ``` * */ static VALUE rb_stat_birthtime(VALUE self) { return statx_birthtime(get_stat(self)); } #else # define rb_stat_birthtime rb_f_notimplement #endif /* * :markup: markdown * * call-seq: * inspect -> string * * Returns a string representation of the entry * in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`; * here we split the returned strings for readability: * * ```ruby * puts File.stat('/etc/passwd').inspect.split(', ') * ``` * * Output: * * ```text * # * ``` * * ```ruby * puts File.stat('/etc').inspect.split(', ') * ``` * * Output: * * ```text * # * ``` * */ static VALUE rb_stat_inspect(VALUE self) { VALUE str; size_t i; static const struct { const char *name; VALUE (*func)(VALUE); } member[] = { {"dev", rb_stat_dev}, {"ino", rb_stat_ino}, {"mode", rb_stat_mode}, {"nlink", rb_stat_nlink}, {"uid", rb_stat_uid}, {"gid", rb_stat_gid}, {"rdev", rb_stat_rdev}, {"size", rb_stat_size}, {"blksize", rb_stat_blksize}, {"blocks", rb_stat_blocks}, {"atime", rb_stat_atime}, {"mtime", rb_stat_mtime}, {"ctime", rb_stat_ctime}, #if defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC) {"birthtime", rb_stat_birthtime}, #endif }; struct rb_stat* rb_st; TypedData_Get_Struct(self, struct rb_stat, &stat_data_type, rb_st); if (!rb_st->initialized) { return rb_sprintf("#<%s: uninitialized>", rb_obj_classname(self)); } str = rb_str_buf_new2("#<"); rb_str_buf_cat2(str, rb_obj_classname(self)); rb_str_buf_cat2(str, " "); for (i = 0; i < sizeof(member)/sizeof(member[0]); i++) { VALUE v; if (i > 0) { rb_str_buf_cat2(str, ", "); } rb_str_buf_cat2(str, member[i].name); rb_str_buf_cat2(str, "="); v = (*member[i].func)(self); if (i == 2) { /* mode */ rb_str_catf(str, "0%lo", (unsigned long)NUM2ULONG(v)); } else if (i == 0 || i == 6) { /* dev/rdev */ rb_str_catf(str, "0x%"PRI_DEVT_PREFIX"x", NUM2DEVT(v)); } else { rb_str_append(str, rb_inspect(v)); } } rb_str_buf_cat2(str, ">"); return str; } typedef struct no_gvl_stat_data { struct stat *st; union { const char *path; int fd; } file; } no_gvl_stat_data; static VALUE no_gvl_fstat(void *data) { no_gvl_stat_data *arg = data; return (VALUE)fstat(arg->file.fd, arg->st); } static int fstat_without_gvl(rb_io_t *fptr, struct stat *st) { no_gvl_stat_data data; data.file.fd = fptr->fd; data.st = st; return (int)rb_io_blocking_region(fptr, no_gvl_fstat, &data); } static void * no_gvl_stat(void * data) { no_gvl_stat_data *arg = data; return (void *)(VALUE)stat(arg->file.path, arg->st); } static int stat_without_gvl(const char *path, struct stat *st) { no_gvl_stat_data data; data.file.path = path; data.st = st; return IO_WITHOUT_GVL_INT(no_gvl_stat, &data); } #if !defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC) && \ defined(HAVE_STRUCT_STATX_STX_BTIME) # define STATX(path, st, mask) statx(AT_FDCWD, path, 0, mask, st) # ifndef HAVE_STATX # ifdef HAVE_SYSCALL_H # include # elif defined HAVE_SYS_SYSCALL_H # include # endif # if defined __linux__ # include static inline int statx(int dirfd, const char *pathname, int flags, unsigned int mask, struct statx *statxbuf) { return (int)syscall(__NR_statx, dirfd, pathname, flags, mask, statxbuf); } # endif /* __linux__ */ # endif /* HAVE_STATX */ typedef struct no_gvl_rb_io_stat_data { struct statx *stx; int fd; const char *path; int flags; unsigned int mask; } no_gvl_rb_io_stat_data; static VALUE io_blocking_statx(void *data) { no_gvl_rb_io_stat_data *arg = data; return (VALUE)statx(arg->fd, arg->path, arg->flags, arg->mask, arg->stx); } static void * no_gvl_statx(void *data) { return (void *)io_blocking_statx(data); } static int statx_without_gvl(const char *path, rb_io_stat_data *stx, unsigned int mask) { no_gvl_rb_io_stat_data data = {stx, AT_FDCWD, path, 0, mask}; /* call statx(2) with pathname */ return IO_WITHOUT_GVL_INT(no_gvl_statx, &data); } static int lstatx_without_gvl(const char *path, rb_io_stat_data *stx, unsigned int mask) { no_gvl_rb_io_stat_data data = {stx, AT_FDCWD, path, AT_SYMLINK_NOFOLLOW, mask}; /* call statx(2) with pathname */ return IO_WITHOUT_GVL_INT(no_gvl_statx, &data); } static int fstatx_without_gvl(rb_io_t *fptr, rb_io_stat_data *stx, unsigned int mask) { no_gvl_rb_io_stat_data data = {stx, fptr->fd, "", AT_EMPTY_PATH, mask}; /* call statx(2) with fd */ return (int)rb_io_blocking_region(fptr, io_blocking_statx, &data); } #define FSTATX(fd, st) statx(fd, "", AT_EMPTY_PATH, STATX_ALL, st) static int rb_statx(VALUE file, struct statx *stx, unsigned int mask) { VALUE tmp; int result; tmp = rb_check_convert_type_with_id(file, T_FILE, "IO", idTo_io); if (!NIL_P(tmp)) { rb_io_t *fptr; GetOpenFile(tmp, fptr); result = fstatx_without_gvl(fptr, stx, mask); file = tmp; } else { FilePathValue(file); file = rb_str_encode_ospath(file); result = statx_without_gvl(RSTRING_PTR(file), stx, mask); } RB_GC_GUARD(file); return result; } # define statx_has_birthtime(st) ((st)->stx_mask & STATX_BTIME) NORETURN(static void statx_notimplement(const char *field_name)); /* rb_notimplement() shows "function is unimplemented on this machine". It is not applicable to statx which behavior depends on the filesystem. */ static void statx_notimplement(const char *field_name) { rb_raise(rb_eNotImpError, "%s is unimplemented on this filesystem", field_name); } static VALUE statx_birthtime(const rb_io_stat_data *stx) { if (!statx_has_birthtime(stx)) { /* birthtime is not supported on the filesystem */ statx_notimplement("birthtime"); } return rb_time_nano_new((time_t)stx->stx_btime.tv_sec, stx->stx_btime.tv_nsec); } #else # define statx_without_gvl(path, st, mask) stat_without_gvl(path, st) # define fstatx_without_gvl(fptr, st, mask) fstat_without_gvl(fptr, st) # define lstatx_without_gvl(path, st, mask) lstat_without_gvl(path, st) # define rb_statx(file, stx, mask) rb_stat(file, stx) # define STATX(path, st, mask) stat(path, st) #if defined(HAVE_STAT_BIRTHTIME) # define statx_has_birthtime(st) 1 #else # define statx_has_birthtime(st) 0 #endif #endif /* !defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC) && \ defined(HAVE_STRUCT_STATX_STX_BTIME) */ #ifndef FSTAT # define FSTAT(fd, st) fstat(fd, st) #endif static int rb_stat(VALUE file, struct stat *st) { VALUE tmp; int result; tmp = rb_check_convert_type_with_id(file, T_FILE, "IO", idTo_io); if (!NIL_P(tmp)) { rb_io_t *fptr; GetOpenFile(tmp, fptr); result = fstat_without_gvl(fptr, st); file = tmp; } else { FilePathValue(file); file = rb_str_encode_ospath(file); result = stat_without_gvl(RSTRING_PTR(file), st); } RB_GC_GUARD(file); return result; } /* * :markup: markdown * * call-seq: * File.stat(path) -> stat * * Returns a new File::Stat object for the entry at `path`. * Unlike File.lstat, _does follow_ [symbolic links](file/symbolic_links.md); * therefore if the entry is a symbolic link, * the returned object contains information for the target entry, not the symbolic link: * * ```ruby * filepath = '/etc/passwd' * linkpath = '/tmp/foo' * File.symlink(filepath, linkpath) * # Method File.stat follows the symlink, so the birthtimes are the same. * File.stat(filepath).birthtime # => 2025-06-10 11:10:47.358999941 -0500 * File.stat(linkpath).birthtime # => 2025-06-10 11:10:47.358999941 -0500 * # Method File.lstat does not follow the symlink, so the birthtimes are different. * File.lstat(filepath).birthtime # => 2025-06-10 11:10:47.358999941 -0500 * File.lstat(linkpath).birthtime # => 2026-09-23 14:01:18.248754979 -0500 * File.delete(linkpath) # Clean up. * ``` * */ static VALUE rb_file_s_stat(VALUE klass, VALUE fname) { rb_io_stat_data st; FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (statx_without_gvl(RSTRING_PTR(fname), &st, STATX_ALL) < 0) { rb_sys_fail_path(fname); } return rb_statx_new(&st); } /* * :markup: markdown * * call-seq: * stat -> stat * * Returns a new File::Stat object for `self`. * Unlike File#lstat, _does follow_ symbolic links; * therefore if `self` is a symbolic link, * the returned object contains information for the target entry, not `self`: * * ```ruby * file_path = '/etc/passwd' * link_path = '/tmp/foo' * File.symlink(file_path, link_path) * file = File.new(file_path) # => # * link = File.new(link_path) # => # * # Method stat does follow the symlink, so the birthtimes are the same. * file.stat.birthtime # => 2025-06-10 11:10:47.358999941 -0500 * link.stat.birthtime # => 2025-06-10 11:10:47.358999941 -0500 * # Method lstat does not follow the symlink, so the birthtimes are different. * file.lstat.birthtime # => 2025-06-10 11:10:47.358999941 -0500 * link.lstat.birthtime # => 2026-09-23 16:35:59.321566598 -0500 * File.delete(link_path) # Clean up. * ``` * */ static VALUE rb_io_stat(VALUE obj) { rb_io_t *fptr; rb_io_stat_data st; GetOpenFile(obj, fptr); if (fstatx_without_gvl(fptr, &st, STATX_ALL) == -1) { rb_sys_fail_path(fptr->pathv); } return rb_statx_new(&st); } #ifdef HAVE_LSTAT static void * no_gvl_lstat(void *ptr) { no_gvl_stat_data *arg = ptr; return (void *)(VALUE)lstat(arg->file.path, arg->st); } static int lstat_without_gvl(const char *path, struct stat *st) { no_gvl_stat_data data; data.file.path = path; data.st = st; return IO_WITHOUT_GVL_INT(no_gvl_lstat, &data); } #endif /* HAVE_LSTAT */ /* * :markup: markdown * * call-seq: * File.lstat(path) -> stat * * Returns a new File::Stat object for the entry at `path`. * Unline File.stat, _does not follow_ [symbolic links](file/symbolic_links.md); * therefore the returned object contains information for the entry at `path`, * regardless of whether is a symbolic link: * * ```ruby * filepath = '/etc/passwd' * linkpath = '/tmp/foo' * File.symlink(filepath, linkpath) * # Method File.lstat does not follow the symlink, so the birthtimes are different. * File.lstat(filepath).birthtime # => 2025-06-10 11:10:47.358999941 -0500 * File.lstat(linkpath).birthtime # => 2026-09-23 14:01:18.248754979 -0500 * # Method File.stat follows the symlink, so the birthtimes are the same. * File.stat(filepath).birthtime # => 2025-06-10 11:10:47.358999941 -0500 * File.stat(linkpath).birthtime # => 2025-06-10 11:10:47.358999941 -0500 * File.delete(linkpath) # Clean up. * ``` * */ static VALUE rb_file_s_lstat(VALUE klass, VALUE fname) { #ifdef HAVE_LSTAT rb_io_stat_data st; FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (lstatx_without_gvl(StringValueCStr(fname), &st, STATX_ALL) == -1) { rb_sys_fail_path(fname); } return rb_statx_new(&st); #else return rb_file_s_stat(klass, fname); #endif } /* * :markup: markdown * call-seq: * lstat -> stat * * Returns a new File::Stat object for `self`. * Unlike File#stat, _does not follow_ symbolic links; * therefore if `self` is a symbolic link, * the returned object contains information for `self`, not the target entry: * * ```ruby * file_path = '/etc/passwd' * link_path = '/tmp/foo' * File.symlink(file_path, link_path) * file = File.new(file_path) # => # * link = File.new(link_path) # => # * # Method lstat does not follow the symlink, so the birthtimes are different. * file.lstat.birthtime # => 2025-06-10 11:10:47.358999941 -0500 * link.lstat.birthtime # => 2026-09-23 16:35:59.321566598 -0500 * # Method stat does follow the symlink, so the birthtimes are the same. * file.stat.birthtime # => 2025-06-10 11:10:47.358999941 -0500 * link.stat.birthtime # => 2025-06-10 11:10:47.358999941 -0500 * File.delete(link_path) # Clean up. * ``` * */ static VALUE rb_file_lstat(VALUE obj) { #ifdef HAVE_LSTAT rb_io_t *fptr; rb_io_stat_data st; VALUE path; GetOpenFile(obj, fptr); if (NIL_P(fptr->pathv)) return Qnil; path = rb_str_encode_ospath(fptr->pathv); if (lstatx_without_gvl(RSTRING_PTR(path), &st, STATX_ALL) == -1) { rb_sys_fail_path(fptr->pathv); } return rb_statx_new(&st); #else return rb_io_stat(obj); #endif } static int rb_group_member(GETGROUPS_T gid) { #if !defined(HAVE_GETGROUPS) return FALSE; #else int rv = FALSE; int groups; VALUE v = 0; GETGROUPS_T *gary; int anum = -1; if (getgid() == gid || getegid() == gid) return TRUE; groups = getgroups(0, NULL); gary = ALLOCV_N(GETGROUPS_T, v, groups); anum = getgroups(groups, gary); while (--anum >= 0) { if (gary[anum] == gid) { rv = TRUE; break; } } if (v) ALLOCV_END(v); return rv; #endif /* !defined(HAVE_GETGROUPS) */ } #ifndef S_IXUGO # define S_IXUGO (S_IXUSR | S_IXGRP | S_IXOTH) #endif #if defined(S_IXGRP) && !defined(_WIN32) && !defined(__CYGWIN__) #define USE_GETEUID 1 #endif #ifndef HAVE_EACCESS int eaccess(const char *path, int mode) { #ifdef USE_GETEUID struct stat st; rb_uid_t euid; euid = geteuid(); /* no setuid nor setgid. run shortcut. */ if (getuid() == euid && getgid() == getegid()) return access(path, mode); if (stat(path, &st) < 0) return -1; if (euid == 0) { /* Root can read or write any file. */ if (!(mode & X_OK)) return 0; /* Root can execute any file that has any one of the execute bits set. */ if (st.st_mode & S_IXUGO) return 0; return -1; } if (st.st_uid == euid) /* owner */ mode <<= 6; else if (rb_group_member(st.st_gid)) mode <<= 3; if ((int)(st.st_mode & mode) == mode) return 0; return -1; #else return access(path, mode); #endif /* USE_GETEUID */ } #endif /* HAVE_EACCESS */ struct access_arg { const char *path; int mode; }; static void * nogvl_eaccess(void *ptr) { struct access_arg *aa = ptr; return (void *)(VALUE)eaccess(aa->path, aa->mode); } static int rb_eaccess(VALUE fname, int mode) { struct access_arg aa; FilePathValue(fname); fname = rb_str_encode_ospath(fname); aa.path = StringValueCStr(fname); aa.mode = mode; return IO_WITHOUT_GVL_INT(nogvl_eaccess, &aa); } static void * nogvl_access(void *ptr) { struct access_arg *aa = ptr; return (void *)(VALUE)access(aa->path, aa->mode); } static int rb_access(VALUE fname, int mode) { struct access_arg aa; FilePathValue(fname); fname = rb_str_encode_ospath(fname); aa.path = StringValueCStr(fname); aa.mode = mode; return IO_WITHOUT_GVL_INT(nogvl_access, &aa); } /* * Document-class: FileTest * * FileTest implements file test operations similar to those used in * File::Stat. It exists as a standalone module, and its methods are * also insinuated into the File class. (Note that this is not done * by inclusion: the interpreter cheats). * */ /* * :markup: markdown * * call-seq: * File.directory?(object) -> true or false * * Returns whether the given `object` represents a directory; * `object` may be a string path or an IO object: * * ```ruby * File.directory?('/etc') # => true * File.directory?('/etc/passwd') # => false * File.directory?($stdin) # => false * File.directory?('nosuch') # => false * ``` * */ VALUE rb_file_directory_p(VALUE obj, VALUE fname) { #ifndef S_ISDIR # define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR) #endif struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; if (S_ISDIR(st.st_mode)) return Qtrue; return Qfalse; } /* * :markup: markdown * * call-seq: * File.pipe?(path) -> true or false * * Returns whether the entry at the given `path` is a pipe: * * ```ruby * pipepath = '/tmp/pipe' * File.pipe?(pipepath) # => false * File.mkfifo(pipepath) * File.pipe?(pipepath) # => true * File.pipe?('/etc') # => false * File.pipe?('/etc/passwd') # => false * File.delete(pipepath) # Clean up. * ``` * */ static VALUE rb_file_pipe_p(VALUE obj, VALUE fname) { #ifdef S_IFIFO # ifndef S_ISFIFO # define S_ISFIFO(m) (((m) & S_IFMT) == S_IFIFO) # endif struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; if (S_ISFIFO(st.st_mode)) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * File.symlink?(path) -> true or false * * Returns whether the entry at `path` * is a [symbolic link](rdoc-ref:file/symbolic_links.md): * * ```ruby * filepath = '/etc/passwd' * linkpath = '/tmp/foo' * File.symlink(filepath, linkpath) * File.symlink?(filepath) # => false * File.symlink?(linkpath) # => true * File.symlink?('.') # => false * File.delete(linkpath) # Clean up. * ``` * */ static VALUE rb_file_symlink_p(VALUE obj, VALUE fname) { #ifndef S_ISLNK # ifdef _S_ISLNK # define S_ISLNK(m) _S_ISLNK(m) # else # ifdef _S_IFLNK # define S_ISLNK(m) (((m) & S_IFMT) == _S_IFLNK) # else # ifdef S_IFLNK # define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK) # endif # endif # endif #endif #ifdef S_ISLNK struct stat st; FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (lstat_without_gvl(StringValueCStr(fname), &st) < 0) return Qfalse; if (S_ISLNK(st.st_mode)) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * File.socket?(object) -> true or false * * Returns whether the given `object` represents a socket; * the `object` may be a path or an IO object: * * ```ruby * require 'socket' * socket_path = '/tmp/socket' * server = UNIXServer.new(socket_path) * File.socket?(socket_path) # => true * server.close # Clean up. * File.delete(socket_path) # Clean up. * file_path = '/etc/passwd' * File.file?(file_path) # => true * File.socket?(file_path) # => false * File.socket?($stdin) # => false * File.socket?('nosuch') # => false * ``` * */ static VALUE rb_file_socket_p(VALUE obj, VALUE fname) { #ifndef S_ISSOCK # ifdef _S_ISSOCK # define S_ISSOCK(m) _S_ISSOCK(m) # else # ifdef _S_IFSOCK # define S_ISSOCK(m) (((m) & S_IFMT) == _S_IFSOCK) # else # ifdef S_IFSOCK # define S_ISSOCK(m) (((m) & S_IFMT) == S_IFSOCK) # endif # endif # endif #endif #ifdef S_ISSOCK struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; if (S_ISSOCK(st.st_mode)) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * File.blockdev?(object) -> true or false * * Returns whether `object` (a path or IO object) * represents a block device (i.e., a direct-access device): * * ```ruby * File.blockdev?('/dev/nvme0n1') # => true * File.blockdev?('/dev/loop0') # => true * File.blockdev?('/dev/tty') # => false * File.blockdev?('/dev/null') # => false * File.blockdev?('nosuch') # => false * File.blockdev?($stdin) # => false * ``` * * The returned value is filesystem-dependent; returns `false` on Windows or MacOS. */ static VALUE rb_file_blockdev_p(VALUE obj, VALUE fname) { #ifndef S_ISBLK # ifdef S_IFBLK # define S_ISBLK(m) (((m) & S_IFMT) == S_IFBLK) # else # define S_ISBLK(m) (0) /* anytime false */ # endif #endif #ifdef S_ISBLK struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; if (S_ISBLK(st.st_mode)) return Qtrue; #endif return Qfalse; } /* * call-seq: * File.chardev?(object) -> true or false * * Returns whether +object+ (a path or IO object) * represents a character device (i.e., a sequential-access device): * * File.chardev?('/dev/tty') # => true * File.chardev?('/dev/null') # => true * File.chardev?($stdin) # => true * File.chardev?('/dev/nvme0n1') # => false * File.chardev?('/dev/loop0') # => false * File.chardev?('nosuch') # => false * * * The returned value is filesystem-dependent; on Windows, always +false+. */ static VALUE rb_file_chardev_p(VALUE obj, VALUE fname) { #ifndef S_ISCHR # define S_ISCHR(m) (((m) & S_IFMT) == S_IFCHR) #endif struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; if (S_ISCHR(st.st_mode)) return Qtrue; return Qfalse; } /* * call-seq: * File.exist?(object) -> true or false * * Return whether the specified +object+, a string path or IO object, exists: * * # String paths. * File.exist?('README.md') # => true * File.exist?('.') # => true * filepath = 't.tmp' * File.exist?(filepath) # => false * File.write(filepath, 'foo') * File.exist?(filepath) # => true * # File (IO object). * file = File.new(filepath) * File.exist?(file) # => true * file.close # Clean up. * File.unlink(filepath) # Clean up. * * Follows symbolic links: * * # Symbolic links. * File.symlink('README.md', 'README.link') * File.symlink('nosuch', 'BROKEN.link') * File.exist?('README.link') # => true * File.exist?('BROKEN.link') # => false * File.unlink('README.link') # Clean up. * File.unlink('BROKEN.link') # Clean up. * */ static VALUE rb_file_exist_p(VALUE obj, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; return Qtrue; } /* * :markup: markdown * * call-seq: * File.readable?(path) -> true or false * * Returns whether the entry at the given `path` * exists and is readable by the owner and group of the current process; * see [Permissions](rdoc-ref:file/filesystem_modes.md@Permissions): * * ```ruby * path = '/tmp/secret.txt' * File.write(path, 'foo') * File.readable?(path) # => true * File.chmod(0o000, path) * File.readable?(path) # => false * File.delete(path) # Clean up. * File.readable?('nosuch') # => false * ``` * */ static VALUE rb_file_readable_p(VALUE obj, VALUE fname) { return RBOOL(rb_eaccess(fname, R_OK) >= 0); } /* * :markup: markdown * * call-seq: * File.readable_real?(path) -> true or false * * Like File.readable?, but checks against the real owner and group ids * instead of the effective ids. */ static VALUE rb_file_readable_real_p(VALUE obj, VALUE fname) { return RBOOL(rb_access(fname, R_OK) >= 0); } #ifndef S_IRUGO # define S_IRUGO (S_IRUSR | S_IRGRP | S_IROTH) #endif #ifndef S_IWUGO # define S_IWUGO (S_IWUSR | S_IWGRP | S_IWOTH) #endif /* * :markup: markdown * * call-seq: * File.world_readable?(object) -> integer or nil * * Returns the integer [permissions](rdoc-ref:file/filesystem_modes.md@Permissions) * for the given `object` * if it exists and is readable by others; * otherwise, returns `nil`: * * ```ruby * filepath = '/tmp/t.tmp' * File.world_readable?(filepath) # => nil # Non-existent. * File.write(filepath, 'foo') # Create file. * File.world_readable?(filepath).to_s(8) # => "664" # World-readable. * File.chmod(0o000, filepath) # Change to unreadable. * File.world_readable?(filepath) # => nil # Not world-readable. * File.delete(filepath) # Clean up. * File.world_readable?('.').to_s(8) # => "775" # Directory. * File.world_readable?($stdin) # => nil # IO object. * ``` * */ static VALUE rb_file_world_readable_p(VALUE obj, VALUE fname) { #ifdef S_IROTH struct stat st; if (rb_stat(fname, &st) < 0) return Qnil; if ((st.st_mode & (S_IROTH)) == S_IROTH) { return UINT2NUM(st.st_mode & (S_IRUGO|S_IWUGO|S_IXUGO)); } #endif return Qnil; } /* * :markup: markdown * * call-seq: * File.writable?(object) -> true or false * * Returns whether given `object` exists and is writable by the owner and group * in the current process: * * ```ruby * filepath = '/tmp/secret.txt' * File.writable?(filepath) # => false # Non-existent. * File.write(filepath, 'foo') # Create file. * File.writable?(filepath) # => true # Writable. * File.chmod(0o000, filepath) # Make non-writable. * File.writable?(filepath) # => false # Not writable. * File.delete(filepath) # Clean up. * File.writable?('/etc') # => false # Directory. * File.writable?($stdin) # => false # IO object. * ``` * * Note that filesystem security features may cause this method to return `true` * even when the file is not writable by the owner and group. */ static VALUE rb_file_writable_p(VALUE obj, VALUE fname) { return RBOOL(rb_eaccess(fname, W_OK) >= 0); } /* * :markup: markdown * * call-seq: * File.writable_real?(object) -> true or false * * Like File.writable?, but checks against the real owner and group * instead of the effective owner and group. * * Note that filesystem security features may cause this method to return `true` * even when the object is not writable by the real owner and group. */ static VALUE rb_file_writable_real_p(VALUE obj, VALUE fname) { return RBOOL(rb_access(fname, W_OK) >= 0); } /* * :markup: markdown * * call-seq: * File.world_writable?(object) -> integer or nil * * If the given `object` exists and is writable by others, * returns the integer [permissions](rdoc-ref:file/filesystem_modes.md@Permissions) * for the entry; * otherwise, returns `nil`: * * ```ruby * filepath = '/tmp/t.tmp' * File.world_writable?(filepath) # => nil # Non-existent. * File.write(filepath, 'foo') # Create file. * File.world_writable?(filepath) # => nil # Not world-writable. * File.chmod(0o777, filepath) # Make world-writable. * File.world_writable?(filepath).to_s(8) # => "777" # World-writable. * File.delete(filepath) # Clean up. * File.world_writable?('/tmp').to_s(8) # => "777" # Directory. * File.world_writable?($stdin) # => nil # IO object. * ``` * */ static VALUE rb_file_world_writable_p(VALUE obj, VALUE fname) { #ifdef S_IWOTH struct stat st; if (rb_stat(fname, &st) < 0) return Qnil; if ((st.st_mode & (S_IWOTH)) == S_IWOTH) { return UINT2NUM(st.st_mode & (S_IRUGO|S_IWUGO|S_IXUGO)); } #endif return Qnil; } /* * :markup: markdown * * call-seq: * File.executable?(path) -> true or false * * Returns whether the filesystem entry at the given `path` * is [executable](rdoc-ref:file/filesystem_modes.md@Executable+Files) * by the effective owner/group of the current process: * * ```ruby * File.executable?('/bin/ruby') # => true * File.executable?('/etc') # => true * File.executable?('/etc/passwd') # => false * File.executable?('nosuch') # => false * ``` * * Note that some filesystem settings may cause this method to return `true` * even though the entry is not executable by the effective owner/group. */ static VALUE rb_file_executable_p(VALUE obj, VALUE fname) { return RBOOL(rb_eaccess(fname, X_OK) >= 0); } /* * :markup: markdown * * call-seq: * File.executable_real?(path) -> true or false * * Like File.executable?, but checks against the real owner/group * instead of the effective owner/group. */ static VALUE rb_file_executable_real_p(VALUE obj, VALUE fname) { return RBOOL(rb_access(fname, X_OK) >= 0); } #ifndef S_ISREG # define S_ISREG(m) (((m) & S_IFMT) == S_IFREG) #endif /* * :markup: markdown * * call-seq: * File.file?(object) -> true or false * * Returns whether the given `object`, a string path or IO object, * represents a filesystem entry that exists and is a regular file; * see File.ftype: * * ```ruby * File.file?('/etc/passwd') # => true * File.file?('/etc') # => false * File.file?($stdin) # => false * File.file?('nosuch') # => false * ``` * */ static VALUE rb_file_file_p(VALUE obj, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; return RBOOL(S_ISREG(st.st_mode)); } /* * :markup: markdown * call-seq: * File.zero?(object) -> true or false * File.empty?(object) -> true or false * * Returns whether the given `object` exists and has size zero. * * The given `object` may be the path to a file: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') # File has non-zero size. * File.zero?(filepath) # => false * File.truncate(filepath, 0) # File has zero size. * File.zero?(filepath) # => true * File.delete(filepath) # Clean up. * ``` * * The given `object` may be the path to a directory: * * ```ruby * dirpath = '/tmp/foo' * Dir.mkdir(dirpath) * Dir.new(dirpath).children.size # => 0 * # Size is filesystem-dependent; may or may not be zero. * File.size(dirpath) # => 4096 * File.zero?(dirpath) # => false * filepath = '/tmp/foo/t.tmp' # => "/tmp/foo/t.tmp" * File.write(filepath, 'foo') # Add a child. * Dir.new(dirpath).children.size # => 1 * File.size(dirpath) # => 4096 * File.zero?(dirpath) # => false * FileUtils.rm_rf(dirpath) # Clean up. * ``` * * The given `object` may be an IO object: * * ```ruby * File.zero?($stdin) # => true * ``` * * The given object may be none of the above: * * ```ruby * File.zero?('nosuch') # => false * ``` * */ static VALUE rb_file_zero_p(VALUE obj, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; return RBOOL(st.st_size == 0); } /* * :markup: markdown * * call-seq: * File.size?(object) -> integer or nil * * Returns the size in bytes of the given `object` * if the entry exists and has non-zero size, `nil` otherwise; * the `object` may be a string path or an IO object: * * ```ruby * # Regular file. * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.size?(filepath) # => 3 # Non-zero size. * File.write(filepath, '') * File.size?(filepath) # => nil # Zero size. * File.delete(filepath) # Clean up. * File.size?(filepath) # => nil # Non-existent. * # Directory. * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) * File.size?(dirpath) # => 4096 # Non-zero size. * Dir.rmdir(dirpath) # Clean up. * File.size?(dirpath) # => nil # Non-existent. * ``` * */ static VALUE rb_file_size_p(VALUE obj, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) return Qnil; if (st.st_size == 0) return Qnil; return OFFT2NUM(st.st_size); } /* * :markup: markdown * * call-seq: * File.owned?(object) -> true or false * * Returns whether the given `object` represents a filesystem entry or IO object * that exists and is owned by the owner of the current process: * * ```ruby * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) * File.owned?(dirpath) # => true * filepath = File.join(dirpath, 't.tmp') * File.write(filepath, 'foo') * File.owned?(filepath) # => true * File.owned?($stdin) # => true * File.owned?('/tmp') # => false * File.owned?('nosuch') # => false * FileUtils.rm_rf(dirpath) # Clean up. * * ``` * */ static VALUE rb_file_owned_p(VALUE obj, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; return RBOOL(st.st_uid == geteuid()); } static VALUE rb_file_rowned_p(VALUE obj, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; return RBOOL(st.st_uid == getuid()); } /* * :markup: markdown * call-seq: * File.grpowned?(object) -> true or false * * Returns `false` on Windows. * * On other systems returns whether the effective group id of the calling process * is the owner of the given `object`. * * The given +object+ may be the string path or an IO object: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.grpowned?(filepath) # => true * File.grpowned?('/etc') # => false * File.grpowned?('/etc/passwd') # => false * File.grpowned?($stdin) # => false * File.grpowned?('nosuch') # => false * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_file_grpowned_p(VALUE obj, VALUE fname) { #ifndef _WIN32 struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; if (rb_group_member(st.st_gid)) return Qtrue; #endif return Qfalse; } #if defined(S_ISUID) || defined(S_ISGID) || defined(S_ISVTX) static VALUE check3rdbyte(VALUE fname, int mode) { struct stat st; if (rb_stat(fname, &st) < 0) return Qfalse; return RBOOL(st.st_mode & mode); } #endif /* * :markup: markdown * * call-seq: * File.setuid?(object) -> true or false * * Returns whether the setuid bit is set * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits) * for the given `object`, which may be a path or an IO object: * * ```ruby * path = '/tmp/t.tmp' * File.write(path, 'foo') * mode = File.stat(path).mode.to_s(8) # => "100664" * File.setuid?(path) # => false * File.chmod(0o4644, path) # Set the bit. * mode = File.stat(path).mode.to_s(8) # => "104644" * File.setuid?(path) # => true * File.delete(path) # Clean up. * File.setuid?($stdin) # => false * ``` * * On Windows, the bit is never set; the method always returns `false`. */ static VALUE rb_file_suid_p(VALUE obj, VALUE fname) { #ifdef S_ISUID return check3rdbyte(fname, S_ISUID); #else return Qfalse; #endif } /* * :markup: markdown * * call-seq: * File.setgid?(object) -> true or false * * Returns whether the setgid bit is set * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits) * for the given `object`, which may be a path or an IO object: * * ```ruby * path = '/tmp/t.tmp' * File.write(path, 'foo') * mode = File.stat(path).mode.to_s(8) # => "100664" * File.setgid?(path) # => false * File.chmod(0o2644, path) # Set the bit. * mode = File.stat(path).mode.to_s(8) # => "102644" * File.setgid?(path) # => true * File.delete(path) # Clean up. * File.setgid?($stdin) # => false * ``` * * On Windows, the bit is never set; the method always returns `false`. */ static VALUE rb_file_sgid_p(VALUE obj, VALUE fname) { #ifdef S_ISGID return check3rdbyte(fname, S_ISGID); #else return Qfalse; #endif } /* * :markup: markdown * call-seq: * File.sticky?(object) -> true or false * * Returns whether the sticky bit is set * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits) * for the given `object`, which may be a path or an IO object: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * mode = File.stat(filepath).mode.to_s(8) # => "100664" * File.sticky?(filepath) # => false * File.chmod(01644, filepath) # Set sticky bit. * mode = File.stat(filepath).mode.to_s(8) # => "101644" * File.sticky?(filepath) # => true * File.delete(filepath) # Clean up. * File.sticky?($stdin) # => false * File.sticky?('nosuch') # => false * ``` * * Returns `false` on Windows. */ static VALUE rb_file_sticky_p(VALUE obj, VALUE fname) { #ifdef S_ISVTX return check3rdbyte(fname, S_ISVTX); #else return Qfalse; #endif } /* * call-seq: * File.identical?(object_0, object_1) -> true or false * * Returns whether the given objects represent filesystem entries that are identical; * each object may be a string path or an IO object: * * # Paths. * File.identical?('README.md', 'README.md') # => true # Same path. * File.identical?('README.md', './README.md') # => true # Same entry. * File.identical?('.', '.') # => true # Directory. * File.identical?('README.md', 'LEGAL') # => false * File.identical?('README.md', 'nosuch') # => false # Non-existent entry. * # Links and File object. * File.link('README.md', 'link') # Symbolic link. * File.symlink('README.md', 'symlink') # Hard link. * file = File.open('README.md', 'r') # File object. * File.identical?('README.md', 'link') # => true * File.identical?('README.md', 'symlink') # => true * File.identical?('README.md', file) # => true * # Clean up. * File.unlink('link') * File.unlink('symlink') * file.close * */ static VALUE rb_file_identical_p(VALUE obj, VALUE fname1, VALUE fname2) { #ifndef _WIN32 struct stat st1, st2; if (rb_stat(fname1, &st1) < 0) return Qfalse; if (rb_stat(fname2, &st2) < 0) return Qfalse; if (st1.st_dev != st2.st_dev) return Qfalse; if (st1.st_ino != st2.st_ino) return Qfalse; return Qtrue; #else extern VALUE rb_w32_file_identical_p(VALUE, VALUE); return rb_w32_file_identical_p(fname1, fname2); #endif } /* * :markup: markdown * * call-seq: * File.size(object) -> integer * * Returns the size in bytes of the given `object`, * which may be a string path or an IO object: * * ```ruby * File.size('/etc/passwd') # => 3092 # Regular file. * File.size('/etc') # => 12288 # Directory. * File.size($stdin) # => 0 # IO object. * ``` * */ static VALUE rb_file_s_size(VALUE klass, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) { int e = errno; FilePathValue(fname); rb_syserr_fail_path(e, fname); } return OFFT2NUM(st.st_size); } static VALUE rb_file_ftype(mode_t mode) { const char *t; if (S_ISREG(mode)) { t = "file"; } else if (S_ISDIR(mode)) { t = "directory"; } else if (S_ISCHR(mode)) { t = "characterSpecial"; } #ifdef S_ISBLK else if (S_ISBLK(mode)) { t = "blockSpecial"; } #endif #ifdef S_ISFIFO else if (S_ISFIFO(mode)) { t = "fifo"; } #endif #ifdef S_ISLNK else if (S_ISLNK(mode)) { t = "link"; } #endif #ifdef S_ISSOCK else if (S_ISSOCK(mode)) { t = "socket"; } #endif else { t = "unknown"; } return rb_fstring_cstr(t); } /* * :markup: markdown * * call-seq: * File.ftype(path) -> string * * Returns the string type of the object at `path`, one of: * * - `'file'`. * - `'directory'`. * - `'characterSpecial'`. * - `'blockSpecial'`. * - `'fifo'`. * - `'link'`. * - `'socket'`. * * Examples: * * ```ruby * File.ftype('/etc/passwd') # => "file" * File.ftype('/etc') # => "directory" * File.ftype("/dev/null") # => "characterSpecial" * File.ftype("/dev/loop0") # => "blockSpecial" * * File.mkfifo('/tmp/pipe', 0o666) * File.ftype('/tmp/pipe') # => "fifo" * * File.symlink('/etc/passwd', '/tmp/link') * File.ftype('/tmp/link') # => "link" * * require 'socket' * UNIXServer.new('/tmp/socket') * File.ftype('/tmp/socket') # => "socket" * * File.delete('/tmp/link', '/tmp/pipe', '/tmp/socket') # Clean up. * ``` * * Returns `'unknown'` if the type cannot be determined. */ static VALUE rb_file_s_ftype(VALUE klass, VALUE fname) { struct stat st; FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (lstat_without_gvl(StringValueCStr(fname), &st) == -1) { rb_sys_fail_path(fname); } return rb_file_ftype(st.st_mode); } /* * :markup: markdown * call-seq: * File.atime(object) -> time * * Returns a new Time object containing the time of the most recent * access to the given `object`. * See {File System Timestamps}[rdoc-ref:file/timestamps.md]. * * Access time for a file is established when it is created, * and may be updated when the file content is read: * * ```ruby * filepath = '/tmp/t.tmp' * File.exist?(filepath) # => false * File.atime(filepath) # Raises Errno::ENOENT: No such file or directory. * File.write(filepath, 'foo') # Establishes access time. * File.atime(filepath) # => 2026-10-04 14:23:12.421395099 -0500 * File.read(filepath) # Updates access time. * File.atime(filepath) # => 2026-10-04 14:23:21.848886816 -0500 * File.delete(filepath) # Clean up. * ``` * * Access time for a directory is established when it is created, * and may updated when its entries are read: * * ```ruby * dirpath = '/tmp/foo' * File.exist?(dirpath) # => false * File.atime(dirpath) # Raises Errno::ENOENT: No such file or directory. * Dir.mkdir(dirpath) # Establishes access time. * File.atime(dirpath) # => 2026-10-04 14:35:53.940716253 -0500 * Dir.entries(dirpath) # Updates access time. * File.atime(dirpath) # => 2026-10-04 14:36:24.316018872 -0500 * Dir.rmdir(dirpath) # Clean up. * ``` * * Argument `object` may be a string path (as above), * a File object, or a Dir object: * * ```ruby * File.atime(File.new('/etc/passwd')) # => 2026-10-04 11:25:01.259278928 -0500 * File.atime('.') # => 2026-10-04 14:40:42.141637825 -0500 * ``` * */ static VALUE rb_file_s_atime(VALUE klass, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) { int e = errno; FilePathValue(fname); rb_syserr_fail_path(e, fname); } return stat_time(stat_atimespec(&st)); } /* * :markup: markdown * * call-seq: * atime -> time * * Returns a new Time object containing the time of the most recent * access to `self`. * See {File System Timestamps}[rdoc-ref:file/timestamps.md]. * * Access time for a file is established when it is created, * and may be updated when the file content is read: * * ``` * filepath = '/tmp/t.tmp' * File.exist?(filepath) # => false * File.write(filepath, 'foo') # Establishes access time. * file = File.new(filepath) * file.atime # => 2026-10-04 14:48:30.323100327 -0500 * file.read # Updates access time. * file.atime # => 2026-10-04 14:49:01.104340829 -0500 * # Clean up. * file.close * File.delete(filepath) * ``` * */ static VALUE rb_file_atime(VALUE obj) { rb_io_t *fptr; struct stat st; GetOpenFile(obj, fptr); if (fstat(fptr->fd, &st) == -1) { rb_sys_fail_path(fptr->pathv); } return stat_time(stat_atimespec(&st)); } /* * :markup: markdown * * call-seq: * File.mtime(object) -> time * * Returns a new Time object containing * the [modification time](rdoc-ref:file/timestamps.md@Modification+Time) * of the given `object`, which may be a string path or an IO object; * * ```ruby * # Create directory; establishes directory mtime. * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) * File.mtime(dirpath) # => 2026-10-12 12:24:08.542476612 -0500 * # Create file therein; establishes file mtime, updates directory mtime. * filepath = File.join(dirpath, 't.tmp') # => "/tmp/dir/t.tmp" * File.write(filepath, 'foo') * File.mtime(filepath) # => 2026-10-12 12:28:41.261675035 -0500 * File.mtime(dirpath) # => 2026-10-12 12:28:41.261675035 -0500 * # Modify file; updates file mtime, does not update directory mtime. * File.write(filepath, 'bar') * File.mtime(filepath) # => 2026-10-12 12:30:09.113910789 -0500 * File.mtime(dirpath) # => 2026-10-12 12:28:41.261675035 -0500 * FileUtils.rm_rf(dirpath) # Clean up. * File.mtime($stdout) # => 2026-10-12 12:31:28 -0500 * $stdout.flush * File.mtime($stdout) # => 2026-10-12 12:31:36 -0500 * ``` * */ static VALUE rb_file_s_mtime(VALUE klass, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) { int e = errno; FilePathValue(fname); rb_syserr_fail_path(e, fname); } return stat_time(stat_mtimespec(&st)); } /* * :markup: markdown * * call-seq: * mtime -> time * * Returns a new Time object containing * the [modification time](rdoc-ref:file/timestamps.md@Modification+Time) * for `self`: * * ```ruby * filepath = '/tmp/t.tmp' * file = File.new(filepath, 'w+') * file.mtime # => 2026-10-13 10:27:02.446070725 -0500 * file.write('foo') * file.flush * file.mtime # => 2026-10-13 10:27:49.252424006 -0500 * # Clean up. * file.close * File.delete(filepath) * ``` * */ static VALUE rb_file_mtime(VALUE obj) { rb_io_t *fptr; struct stat st; GetOpenFile(obj, fptr); if (fstat(fptr->fd, &st) == -1) { rb_sys_fail_path(fptr->pathv); } return stat_time(stat_mtimespec(&st)); } /* * :markup: markdown * * call-seq: * File.ctime(object) -> time * * On Windows, returns the birthtime for `object`. * * On other systems, * returns a new Time object containing the time of the most recent * metadata change to the entry represented by `object`, * which is a string path or an IO object; * see [File System Timestamps](rdoc-ref:file/timestamps.md): * * ```ruby * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) * File.ctime(dirpath) # => 2026-10-05 16:24:40.347201215 -0500 * # Create file therein; file ctime established; directory ctime updated. * filepath = File.join(dirpath, 't.tmp') # => "/tmp/dir/t.tmp" * File.write(filepath, 'foo') * File.ctime(dirpath) # => 2026-10-05 16:25:34.790762181 -0500 * File.ctime(filepath) # => 2026-10-05 16:25:34.790762181 -0500 * # Write file; file ctime updated; directory ctime not updated. * File.write(filepath, 'bar') * File.ctime(dirpath) # => 2026-10-05 16:25:34.790762181 -0500 * File.ctime(filepath) # => 2026-10-05 16:26:23.030432041 -0500 * # Read file; neither ctime updated. * File.read(filepath) * File.ctime(dirpath) # => 2026-10-05 16:25:34.790762181 -0500 * File.ctime(filepath) # => 2026-10-05 16:26:23.030432041 -0500 * FileUtils.rm_rf(dirpath) # Clean up. * ``` * */ static VALUE rb_file_s_ctime(VALUE klass, VALUE fname) { struct stat st; if (rb_stat(fname, &st) < 0) { int e = errno; FilePathValue(fname); rb_syserr_fail_path(e, fname); } return stat_time(stat_ctimespec(&st)); } /* * :markup: markdown * * call-seq: * ctime -> time * * On Windows, returns the birthtime for the entry in `self`. * * On other systems, * returns a new Time object containing the time of the most recent * metadata change to the entry in `self`; * see [File System Timestamps](rdoc-ref:file/timestamps.md): * * ```ruby * # A directory. * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) # Establishes directory ctime. * dir = File.new(dirpath) # (Dir does not have method ctime; we use File.) * dir.ctime # => 2026-10-05 17:23:49.406452569 -0500 * # A file therein. * filepath = File.join(dirpath, 't.tmp') # => "/tmp/dir/t.tmp" * File.write(filepath, 'foo') # Establishes file ctime. * file = File.new(filepath) * file.ctime # => 2026-10-05 17:26:26.467758515 -0500 * dir.ctime # => 2026-10-05 17:26:26.467758515 -0500 * File.write(filepath, 'bar') # Updates file ctime; not directory ctime. * file.ctime # => 2026-10-05 17:28:26.307497599 -0500 * dir.ctime # => 2026-10-05 17:26:26.467758515 -0500 * FileUtils.rm_rf(dirpath) # Clean up. * ``` * */ static VALUE rb_file_ctime(VALUE obj) { rb_io_t *fptr; struct stat st; GetOpenFile(obj, fptr); if (fstat(fptr->fd, &st) == -1) { rb_sys_fail_path(fptr->pathv); } return stat_time(stat_ctimespec(&st)); } #if defined(HAVE_STAT_BIRTHTIME) /* * :markup: markdown * * call-seq: * File.birthtime(path) -> time * * Returns a new Time object containing the creation time * of the entry at the given `path`; * see [File System Timestamps](rdoc-ref:file/timestamps.md): * * ```ruby * filepath = '/tmp/t.tmp' * File.birthtime(filepath) # Raises Errno::ENOENT: No such file or directory. * File.write(filepath, 'foo') * File.birthtime(filepath) # => 2026-10-05 13:41:02.330337383 -0500 * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_file_s_birthtime(VALUE klass, VALUE fname) { rb_io_stat_data st; if (rb_statx(fname, &st, STATX_BTIME) < 0) { int e = errno; FilePathValue(fname); rb_syserr_fail_path(e, fname); } return statx_birthtime(&st); } #else # define rb_file_s_birthtime rb_f_notimplement #endif #if defined(HAVE_STAT_BIRTHTIME) /* * call-seq: * birthtime -> new_time * * Returns a new Time object containing the create time for +self+: * * filepath = 't.tmp' * File.write(filepath, 'foo') * file = File.new(filepath) * file.birthtime # => 2026-04-14 15:53:45.002656 -0500 * File.write(filepath, 'bar') * file.birthtime # => 2026-04-14 15:53:45.002656 -0500 * file.close * File.delete(filepath) * file.birthtime # Raises IOError: closed stream * * See {File System Timestamps}[rdoc-ref:file/timestamps.md]. */ static VALUE rb_file_birthtime(VALUE obj) { rb_io_t *fptr; rb_io_stat_data st; GetOpenFile(obj, fptr); if (fstatx_without_gvl(fptr, &st, STATX_BTIME) == -1) { rb_sys_fail_path(fptr->pathv); } return statx_birthtime(&st); } #else # define rb_file_birthtime rb_f_notimplement #endif rb_off_t rb_file_size(VALUE file) { if (RB_TYPE_P(file, T_FILE)) { rb_io_t *fptr; struct stat st; RB_IO_POINTER(file, fptr); if (fptr->mode & FMODE_WRITABLE) { rb_io_flush_raw(file, 0); } if (fstat(fptr->fd, &st) == -1) { rb_sys_fail_path(fptr->pathv); } return st.st_size; } else { return NUM2OFFT(rb_funcall(file, idSize, 0)); } } /* * :markup: markdown * * call-seq: * size -> integer * * Returns the size of `self` in bytes: * * ```ruby * File.new('/etc/passwd').size # => 3092 # Regular file. * File.new('/etc').size # => 12288 # Directory. * ``` * */ static VALUE file_size(VALUE self) { return OFFT2NUM(rb_file_size(self)); } struct nogvl_chmod_data { const char *path; mode_t mode; }; static void * nogvl_chmod(void *ptr) { struct nogvl_chmod_data *data = ptr; int ret = chmod(data->path, data->mode); return (void *)(VALUE)ret; } static int rb_chmod(const char *path, mode_t mode) { struct nogvl_chmod_data data = { .path = path, .mode = mode, }; return IO_WITHOUT_GVL_INT(nogvl_chmod, &data); } static int chmod_internal(const char *path, void *mode) { return chmod(path, *(mode_t *)mode); } /* * call-seq: * File.chmod(mode, *paths) -> integer * * Changes the modes of each of the entries at each the given +paths+; * returns the count of the given +paths+. * See {Filesystem Modes}[rdoc-ref:file/filesystem_modes.md] * and especially {Setting a Mode}[rdoc-ref:file/filesystem_modes.md@Setting+a+Mode]. * * file0path = '/tmp/t0.tmp' * file1path = '/tmp/t1.tmp' * File.write(file0path, 'foo') * File.write(file1path, 'bar') * '%06o' % File.stat(file0path).mode # => "100664" * '%06o' % File.stat(file1path).mode # => "100664" * File.chmod(0o755, file0path, file1path) * '%06o' % File.stat(file0path).mode # => "100755" * '%06o' % File.stat(file1path).mode # => "100755" * File.delete(file0path, file1path) # Clean up. * */ static VALUE rb_file_s_chmod(int argc, VALUE *argv, VALUE _) { mode_t mode; apply2args(1); mode = NUM2MODET(*argv++); return apply2files(chmod_internal, argc, argv, &mode); } #ifdef HAVE_FCHMOD struct nogvl_fchmod_data { int fd; mode_t mode; }; static VALUE io_blocking_fchmod(void *ptr) { struct nogvl_fchmod_data *data = ptr; int ret = fchmod(data->fd, data->mode); return (VALUE)ret; } static int rb_fchmod(struct rb_io* io, mode_t mode) { (void)rb_chmod; /* suppress unused-function warning when HAVE_FCHMOD */ struct nogvl_fchmod_data data = {.fd = io->fd, .mode = mode}; return (int)rb_thread_io_blocking_region(io, io_blocking_fchmod, &data); } #endif /* * call-seq: * chmod(mode) -> 0 * * Changes the mode of +self+; returns '0'. * See {Filesystem Modes}[rdoc-ref:file/filesystem_modes.md] * and especially {Setting a Mode}[rdoc-ref:file/filesystem_modes.md@Setting+a+Mode]. * * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * '%06o' % File.stat(filepath).mode # => "100664" * file = File.new(filepath) * file.chmod(0o755) * '%06o' % File.stat(filepath).mode # => "100755" * # Clean up. * file.close * File.delete(filepath) * */ static VALUE rb_file_chmod(VALUE obj, VALUE vmode) { rb_io_t *fptr; mode_t mode; #if !defined HAVE_FCHMOD || !HAVE_FCHMOD VALUE path; #endif mode = NUM2MODET(vmode); GetOpenFile(obj, fptr); #ifdef HAVE_FCHMOD if (rb_fchmod(fptr, mode) == -1) { if (HAVE_FCHMOD || errno != ENOSYS) rb_sys_fail_path(fptr->pathv); } else { if (!HAVE_FCHMOD) return INT2FIX(0); } #endif #if !defined HAVE_FCHMOD || !HAVE_FCHMOD if (NIL_P(fptr->pathv)) return Qnil; path = rb_str_encode_ospath(fptr->pathv); if (rb_chmod(RSTRING_PTR(path), mode) == -1) rb_sys_fail_path(fptr->pathv); #endif return INT2FIX(0); } #if defined(HAVE_LCHMOD) static int lchmod_internal(const char *path, void *mode) { return lchmod(path, *(mode_t *)mode); } /* * :markup: markdown * * call-seq: * File.lchmod(mode, *paths) -> paths_count * * Not supported on Linux or Windows (raises NotImplementedError). * * When supported: like File::chmod, * but does not follow [symbolic links](rdoc-ref:file/symbolic_links.md), * and therefore changes the mode of the entries given by `paths`; * returns the number of paths given: * * ```ruby * File.write('t.tmp', '') * File.symlink('t.tmp', 'link') * File.lstat('t.tmp').mode.to_s(8) # => "100664" * File.lstat('link').mode.to_s(8) # => "120755" * File.lchmod(0777, 'link') * File.lstat('t.tmp').mode.to_s(8) # => "100664" * File.lstat('link').mode.to_s(8) # => "120777" * File.delete('t.tmp') * File.delete('link') * ``` */ static VALUE rb_file_s_lchmod(int argc, VALUE *argv, VALUE _) { mode_t mode; apply2args(1); mode = NUM2MODET(*argv++); return apply2files(lchmod_internal, argc, argv, &mode); } #else #define rb_file_s_lchmod rb_f_notimplement #endif static inline rb_uid_t to_uid(VALUE u) { if (NIL_P(u)) { return (rb_uid_t)-1; } return NUM2UIDT(u); } static inline rb_gid_t to_gid(VALUE g) { if (NIL_P(g)) { return (rb_gid_t)-1; } return NUM2GIDT(g); } struct chown_args { rb_uid_t owner; rb_gid_t group; }; static int chown_internal(const char *path, void *arg) { struct chown_args *args = arg; return chown(path, args->owner, args->group); } /* * call-seq: * File.chown(owner_int, group_int, *paths) -> integer * * Changes the owner and group of the entry at each of the given +paths+; * returns the count of the given +paths+: * * # Super user; all privileges. * Process.uid => 0 * Process.gid => 0 * # Create a directory and a file. * dirpath = 'doc/foo' * Dir.mkdir(dirpath) * filepath = 't.tmp' * File.write(filepath, 'foo') * # Get their user and group ids. * dirstat = File::Stat.new(dirpath) * dirstat.uid => 0 * dirstat.gid => 0 * filestat = File::Stat.new(filepath) * filestat.uid => 0 * filestat.gid => 0 * # Change ownership of both. * File.chown(1000, 1000, filepath, dirpath) => 2 * dirstat = File::Stat.new(dirpath) * dirstat.uid => 1000 * dirstat.gid => 1000 * filestat = File::Stat.new(filepath) * filestat.uid => 1000 * filestat.gid => 1000 * # Clean up. * Dir.rmdir(dirpath) * File.delete(filepath) * * Notes: * * - On Windows, the owner and group are not changed. * - Only a process with superuser privileges can change the owner of an entry. * - The owner of an entry can change its group to any group * to which the owner belongs. * - A +nil+ or +-1+ owner or group id is ignored. * - The method follows symbolic links to the target entry. * */ static VALUE rb_file_s_chown(int argc, VALUE *argv, VALUE _) { struct chown_args arg; apply2args(2); arg.owner = to_uid(*argv++); arg.group = to_gid(*argv++); return apply2files(chown_internal, argc, argv, &arg); } struct nogvl_chown_data { union { const char *path; int fd; } as; struct chown_args new; }; static void * nogvl_chown(void *ptr) { struct nogvl_chown_data *data = ptr; return (void *)(VALUE)chown(data->as.path, data->new.owner, data->new.group); } static int rb_chown(const char *path, rb_uid_t owner, rb_gid_t group) { struct nogvl_chown_data data = { .as = {.path = path}, .new = {.owner = owner, .group = group}, }; return IO_WITHOUT_GVL_INT(nogvl_chown, &data); } #ifdef HAVE_FCHOWN static void * nogvl_fchown(void *ptr) { struct nogvl_chown_data *data = ptr; return (void *)(VALUE)fchown(data->as.fd, data->new.owner, data->new.group); } static int rb_fchown(int fd, rb_uid_t owner, rb_gid_t group) { (void)rb_chown; /* suppress unused-function warning when HAVE_FCHMOD */ struct nogvl_chown_data data = { .as = {.fd = fd}, .new = {.owner = owner, .group = group}, }; return IO_WITHOUT_GVL_INT(nogvl_fchown, &data); } #endif /* * call-seq: * file.chown(owner_int, group_int ) -> 0 * * Changes the owner and group of file to the given numeric * owner and group id's. Only a process with superuser privileges may * change the owner of a file. The current owner of a file may change * the file's group to any group to which the owner belongs. A +nil+ * or -1 owner or group id is ignored. Follows symbolic links. See * also File#lchown. * * File.new("testfile").chown(502, 1000) * */ static VALUE rb_file_chown(VALUE obj, VALUE owner, VALUE group) { rb_io_t *fptr; rb_uid_t o; rb_gid_t g; #ifndef HAVE_FCHOWN VALUE path; #endif o = to_uid(owner); g = to_gid(group); GetOpenFile(obj, fptr); #ifndef HAVE_FCHOWN if (NIL_P(fptr->pathv)) return Qnil; path = rb_str_encode_ospath(fptr->pathv); if (rb_chown(RSTRING_PTR(path), o, g) == -1) rb_sys_fail_path(fptr->pathv); #else if (rb_fchown(fptr->fd, o, g) == -1) rb_sys_fail_path(fptr->pathv); #endif return INT2FIX(0); } #if defined(HAVE_LCHOWN) static int lchown_internal(const char *path, void *arg) { struct chown_args *args = arg; return lchown(path, args->owner, args->group); } /* * :markup: markdown * * call-seq: * File.lchown(uid, gid, *paths ) -> paths_count * * Not supported on some platforms (raises exception). * * Calling process must have superuser privileges. * * When supported: like File::chown, * but does not follow [symbolic links](rdoc-ref:file/symbolic_links.md), * and therefore changes the ownership of the entries given by `paths`; * returns the number of paths given: * * ```ruby * # Super user; all privileges. * Process.uid # => 0 * Process.gid # => 0 * # Create regular file and symbolic link to it. * File.write('t.tmp', '') * File.symlink('t.tmp', 'link') * Capture original statuses. * fstat0 = File.stat('t.tmp') # Method ::stat; status of file. * lstat0 = File.lstat('link') # Method ::lstat; status of link. * # Original user ids and group ids. * fstat0.uid => 0 * fstat0.gid => 0 * lstat0.uid => 0 * lstat0.gid => 0 * # Change ids for link. * File.lchown(1000, 1000, 'link') # => 1 * # Capture new statuses. * fstat1 = File.stat('t.tmp') * lstat1 = File.stat('link') * # User id and group id for file not changed.. * fstat1.uid # => 0 * fstat1.gid # => 0 * # User is and group id for link changed. * lstat1.uid # => 1000 * lstat1.gid # => 1000 * Clean up. * File.delete('t.tmp') * File.delete('link') * ``` * */ static VALUE rb_file_s_lchown(int argc, VALUE *argv, VALUE _) { struct chown_args arg; apply2args(2); arg.owner = to_uid(*argv++); arg.group = to_gid(*argv++); return apply2files(lchown_internal, argc, argv, &arg); } #else #define rb_file_s_lchown rb_f_notimplement #endif struct utime_args { const struct timespec* tsp; VALUE atime, mtime; int follow; /* Whether to act on symlinks (1) or their referent (0) */ }; #ifdef UTIME_EINVAL NORETURN(static void utime_failed(struct apply_arg *)); static void utime_failed(struct apply_arg *aa) { int e = aa->errnum; VALUE path = aa->fn[aa->i].path; struct utime_args *ua = aa->arg; if (ua->tsp && e == EINVAL) { VALUE e[2], a = Qnil, m = Qnil; int d = 0; VALUE atime = ua->atime; VALUE mtime = ua->mtime; if (!NIL_P(atime)) { a = rb_inspect(atime); } if (!NIL_P(mtime) && mtime != atime && !rb_equal(atime, mtime)) { m = rb_inspect(mtime); } if (NIL_P(a)) e[0] = m; else if (NIL_P(m) || rb_str_cmp(a, m) == 0) e[0] = a; else { e[0] = rb_str_plus(a, rb_str_new_cstr(" or ")); rb_str_append(e[0], m); d = 1; } if (!NIL_P(e[0])) { if (path) { if (!d) e[0] = rb_str_dup(e[0]); rb_str_append(rb_str_cat2(e[0], " for "), path); } e[1] = INT2FIX(EINVAL); rb_exc_raise(rb_class_new_instance(2, e, rb_eSystemCallError)); } } rb_syserr_fail_path(e, path); } #endif /* UTIME_EINVAL */ #if defined(HAVE_UTIMES) # if !defined(HAVE_UTIMENSAT) /* utimensat() is not found, runtime check is not needed */ # elif defined(__APPLE__) && \ (!defined(MAC_OS_X_VERSION_13_0) || (MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_13_0)) # if __has_attribute(availability) && __has_warning("-Wunguarded-availability-new") typedef int utimensat_func(int, const char *, const struct timespec [2], int); RBIMPL_WARNING_PUSH() RBIMPL_WARNING_IGNORED(-Wunguarded-availability-new) static inline utimensat_func * rb_utimensat(void) { return &utimensat; } RBIMPL_WARNING_POP() # define utimensat rb_utimensat() # else /* __API_AVAILABLE macro does nothing on gcc */ __attribute__((weak)) int utimensat(int, const char *, const struct timespec [2], int); # endif /* utimesat availability */ # endif /* __APPLE__ && < MAC_OS_X_VERSION_13_0 */ static int utime_internal(const char *path, void *arg) { struct utime_args *v = arg; const struct timespec *tsp = v->tsp; struct timeval tvbuf[2], *tvp = NULL; #if defined(HAVE_UTIMENSAT) # if defined(__APPLE__) const int try_utimensat = utimensat != NULL; const int try_utimensat_follow = utimensat != NULL; # else /* !__APPLE__ */ # define TRY_UTIMENSAT 1 static int try_utimensat = 1; # ifdef AT_SYMLINK_NOFOLLOW static int try_utimensat_follow = 1; # else const int try_utimensat_follow = 0; # endif # endif /* __APPLE__ */ int flags = 0; if (v->follow ? try_utimensat_follow : try_utimensat) { # ifdef AT_SYMLINK_NOFOLLOW if (v->follow) { flags = AT_SYMLINK_NOFOLLOW; } # endif int result = utimensat(AT_FDCWD, path, tsp, flags); # ifdef TRY_UTIMENSAT if (result < 0 && errno == ENOSYS) { # ifdef AT_SYMLINK_NOFOLLOW try_utimensat_follow = 0; # endif /* AT_SYMLINK_NOFOLLOW */ if (!v->follow) try_utimensat = 0; } else # endif /* TRY_UTIMESAT */ return result; } #endif /* defined(HAVE_UTIMENSAT) */ if (tsp) { tvbuf[0].tv_sec = tsp[0].tv_sec; tvbuf[0].tv_usec = (int)(tsp[0].tv_nsec / 1000); tvbuf[1].tv_sec = tsp[1].tv_sec; tvbuf[1].tv_usec = (int)(tsp[1].tv_nsec / 1000); tvp = tvbuf; } #ifdef HAVE_LUTIMES if (v->follow) return lutimes(path, tvp); #endif return utimes(path, tvp); } #else /* !defined(HAVE_UTIMES) */ #if !defined HAVE_UTIME_H && !defined HAVE_SYS_UTIME_H struct utimbuf { long actime; long modtime; }; #endif static int utime_internal(const char *path, void *arg) { struct utime_args *v = arg; const stat_timestamp *tsp = v->tsp; struct utimbuf utbuf, *utp = NULL; if (tsp) { utbuf.actime = tsp[0].tv_sec; utbuf.modtime = tsp[1].tv_sec; utp = &utbuf; } return utime(path, utp); } #endif /* !defined(HAVE_UTIMES) */ static VALUE utime_internal_i(int argc, VALUE *argv, int follow) { struct utime_args args; struct timespec tss[2], *tsp = NULL; apply2args(2); args.atime = *argv++; args.mtime = *argv++; args.follow = follow; if (!NIL_P(args.atime) || !NIL_P(args.mtime)) { tsp = tss; tsp[0] = rb_time_timespec(args.atime); if (args.atime == args.mtime) tsp[1] = tsp[0]; else tsp[1] = rb_time_timespec(args.mtime); } args.tsp = tsp; return apply2files(utime_internal, argc, argv, &args); } /* * :markup: markdown * * call-seq: * File.utime(atime, mtime, *paths) -> integer * * For the entry at the paths in `paths`, * updates its access time to the given `atime` * and its modification time to the given `mtime`; * see [Filesystem Timestamps](rdoc-ref:file/timestamps.md). * Returns the number of entries updated. * Each path points to a file or directory. * * Each given time may be a Time object, an integer representing a time, * or `nil` (meaning Time.now): * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.atime(filepath) # => 2026-09-29 12:38:29.889703781 -0500 * File.mtime(filepath) # => 2026-09-29 12:38:29.889703781 -0500 * time = Time.now * File.utime(time, time, filepath) * File.atime(filepath) # => 2026-09-29 12:38:52.533160634 -0500 * File.mtime(filepath) # => 2026-09-29 12:38:52.533160634 -0500 * File.utime(0, 0, filepath) * File.atime(filepath) # => 1969-12-31 18:00:00 -0600 * File.mtime(filepath) # => 1969-12-31 18:00:00 -0600 * File.utime(nil, nil, filepath) * File.atime(filepath) # => 2026-09-29 12:39:50.859421265 -0500 * File.mtime(filepath) # => 2026-09-29 12:39:50.859421265 -0500 * File.delete(filepath) # Clean up. * ``` * * Raises an exception if any entry cannot be updated; * some entries may have already been updated. * * Follows symbolic links; use File.lutime to update the times for symbolic links. */ static VALUE rb_file_s_utime(int argc, VALUE *argv, VALUE _) { return utime_internal_i(argc, argv, FALSE); } #if defined(HAVE_UTIMES) && (defined(HAVE_LUTIMES) || (defined(HAVE_UTIMENSAT) && defined(AT_SYMLINK_NOFOLLOW))) /* * :markup: markdown * * call-seq: * File.lutime(atime, mtime, *paths) -> path_count * * Like File::utime, * but does not follow [symbolic links](rdoc-ref:file/symbolic_links.md), * and therefore changes the times of the entries given by `paths`, * regardless of whether they are symbolic links; * returns the number of `paths` given: * * ```ruby * # Create a file and a link to it. * file_path = 't.tmp' * File.write(file_path, '') * link_path = 'link' * File.symlink(file_path, link_path) * # Take snapshots of both. * file_stat = File.stat(file_path) * link_stat = File.lstat(link_path) * # Fetch access times and modification times of both. * file_stat.atime # => 2026-06-15 10:45:11.376753268 -0500 * file_stat.mtime # => 2026-06-15 10:44:47.335854904 -0500 * link_stat.atime # => 2026-06-15 10:44:59.788801128 -0500 * link_stat.mtime # => 2026-06-15 10:44:49.367845961 -0500 * # Update access time and modification time of the link. * time = Time.now # => 2026-06-15 10:48:57.847422496 -0500 * File.lutime(time, time, link_path) * # Take fresh snapshots of both. * file_stat = File.stat(file_path) * link_stat = File.lstat(link_path) * # Fetch access time and modification time of file (not changed). * file_stat.atime # => 2026-06-15 10:45:11.376753268 -0500 * file_stat.mtime # => 2026-06-15 10:44:47.335854904 -0500 * # Fetch access time and modification time of link (changed). * link_stat.atime # => 2026-06-15 10:49:27.119146136 -0500 * link_stat.mtime # => 2026-06-15 10:48:57.847422496 -0500 * # Clean up. * File.delete(file_path) * File.delete(link_path) * ``` * * Arguments `atime` and `mtime` may be Time objects (as above). * * Either or both may be integers; * when an integer `i` is passed, `Time.new(i)` is used. * * Either or both may be `nil`, in which case `Time.now` is used. * * See {File System Timestamps}[rdoc-ref:file/timestamps.md]. */ static VALUE rb_file_s_lutime(int argc, VALUE *argv, VALUE _) { return utime_internal_i(argc, argv, TRUE); } #else #define rb_file_s_lutime rb_f_notimplement #endif #ifdef RUBY_FUNCTION_NAME_STRING # define syserr_fail2(e, s1, s2) syserr_fail2_in(RUBY_FUNCTION_NAME_STRING, e, s1, s2) #else # define syserr_fail2_in(func, e, s1, s2) syserr_fail2(e, s1, s2) #endif #define sys_fail2(s1, s2) syserr_fail2(errno, s1, s2) NORETURN(static void syserr_fail2_in(const char *,int,VALUE,VALUE)); static void syserr_fail2_in(const char *func, int e, VALUE s1, VALUE s2) { VALUE str; #ifdef MAX_PATH const int max_pathlen = MAX_PATH; #else const int max_pathlen = MAXPATHLEN; #endif if (e == EEXIST) { rb_syserr_fail_path(e, rb_str_ellipsize(s2, max_pathlen)); } str = rb_str_new_cstr("("); rb_str_append(str, rb_str_ellipsize(s1, max_pathlen)); rb_str_cat2(str, ", "); rb_str_append(str, rb_str_ellipsize(s2, max_pathlen)); rb_str_cat2(str, ")"); #ifdef RUBY_FUNCTION_NAME_STRING rb_syserr_fail_path_in(func, e, str); #else rb_syserr_fail_path(e, str); #endif } #ifdef HAVE_LINK /* * :markup: markdown * call-seq: * File.link(path, new_path) -> 0 * * Not available on some systems. * * Creates a new entry at `new_path` for the existing entry at `path` * using a [hard link](https://en.wikipedia.org/wiki/Hard_link): * * ```ruby * File.write('doc/t.tmp', 'foo') * File.link('doc/t.tmp', 'lib/u.tmp') * File.read('lib/u.tmp') # => "foo" * File.write('lib/u.tmp', 'bar') * File.read('doc/t.tmp') # => "bar" * File.delete('doc/t.tmp') * File.read('lib/u.tmp') # => "bar" * File.delete('lib/u.tmp') * ``` * * Raises an exception if the entry at `new_path` exists. */ static VALUE rb_file_s_link(VALUE klass, VALUE from, VALUE to) { FilePathValue(from); FilePathValue(to); from = rb_str_encode_ospath(from); to = rb_str_encode_ospath(to); if (link(StringValueCStr(from), StringValueCStr(to)) < 0) { sys_fail2(from, to); } return INT2FIX(0); } #else #define rb_file_s_link rb_f_notimplement #endif #ifdef HAVE_SYMLINK /* * :markup: markdown * * call-seq: * File.symlink(target_path, link_path) -> 0 * * Not supported on some platforms. * * Creates a [symbolic link](rdoc-ref:file/symbolic_links.md) * at `link_path` to the entry at `target_path`: * * ```ruby * filepath = '/etc/passwd' # Regular file. * linkpath = '/tmp/foo' * File.symlink(filepath, linkpath) * File.readlink(linkpath) # => "/etc/passwd" * File.read(filepath) == File.read(linkpath) # => true * ``` * * If the entry at `target_path` is itself a symbolic link, * that link is _not_ followed: * * ```ruby * link2path = '/tmp/bar' * File.symlink(linkpath, link2path) * File.readlink(link2path) # => "/tmp/foo" * File.read(filepath) == File.read(link2path) # => true * File.delete(linkpath, link2path) # Clean up. * ``` * */ static VALUE rb_file_s_symlink(VALUE klass, VALUE from, VALUE to) { FilePathValue(from); FilePathValue(to); from = rb_str_encode_ospath(from); to = rb_str_encode_ospath(to); if (symlink(StringValueCStr(from), StringValueCStr(to)) < 0) { sys_fail2(from, to); } return INT2FIX(0); } #else #define rb_file_s_symlink rb_f_notimplement #endif #ifdef HAVE_READLINK /* * :markup: markdown * * call-seq: * File.readlink(link_path) -> string * * Returns the string path to the entry referenced * by the [symbolic link](rdoc-ref:file/symbolic_links.md) at `link_path`: * * ```ruby * filepath = 'doc/maintainers.md' * linkpath = '/tmp/link' * File.symlink(filepath, linkpath) * File.readlink(linkpath) # => "doc/maintainers.md" * File.delete(linkpath) # Clean up. * ``` * * Raises Errno::EINVAL if the entry referenced by `link_path` * is not a symbolic link. */ static VALUE rb_file_s_readlink(VALUE klass, VALUE path) { return rb_readlink(path, rb_filesystem_encoding()); } struct readlink_arg { const char *path; char *buf; size_t size; }; static void * nogvl_readlink(void *ptr) { struct readlink_arg *ra = ptr; return (void *)(VALUE)readlink(ra->path, ra->buf, ra->size); } static ssize_t readlink_without_gvl(VALUE path, VALUE buf, size_t size) { struct readlink_arg ra; ra.path = RSTRING_PTR(path); ra.buf = RSTRING_PTR(buf); ra.size = size; return (ssize_t)IO_WITHOUT_GVL(nogvl_readlink, &ra); } VALUE rb_readlink(VALUE path, rb_encoding *enc) { int size = 100; ssize_t rv; VALUE v; FilePathValue(path); path = rb_str_encode_ospath(path); v = rb_enc_str_new(0, size, enc); while ((rv = readlink_without_gvl(path, v, size)) == size #ifdef _AIX || (rv < 0 && errno == ERANGE) /* quirky behavior of GPFS */ #endif ) { rb_str_modify_expand(v, size); size *= 2; rb_str_set_len(v, size); } if (rv < 0) { int e = errno; rb_str_resize(v, 0); rb_syserr_fail_path(e, path); } rb_str_resize(v, rv); return v; } #else #define rb_file_s_readlink rb_f_notimplement #endif static int unlink_internal(const char *path, void *arg) { return unlink(path); } /* * :markup: markdown * * call-seq: * File.delete(*paths) -> integer * File.unlink(*paths) -> integer * * Removes the entry ([hard link](rdoc-ref:file/hard_links.md)) at each path in `paths`; * returns the count of removed entries: * * ```ruby * filepath0 = '/tmp/t0.tmp' * filepath1 = '/tmp/t1.tmp' * File.write(filepath0, 'foo') * File.write(filepath1, 'bar') * File.unlink(filepath0, filepath1) # => 2 * ``` * * If the removed hard link is the last one associated with the inode, * also removes the inode; otherwise, not. * See [Unlinking](rdoc-ref:file/hard_links.md@Unlinking). * * Does not follow [symbolic links](rdoc-ref:file/symbolic_links.md); * if the entry is a symbolic link, removes the entry itself (not the link target). * * ```ruby * filepath = '/tmp/t.tmp' * linkpath = '/tmp/link' * File.write(filepath, 'foo') * File.symlink(filepath, linkpath) * File.unlink(linkpath) # => 1 * File.exist?(filepath) # => true * File.unlink(filepath) # => 1 * ``` * * Raises an exception on any error; * some entries may have been deleted before the error occurs. */ static VALUE rb_file_s_unlink(int argc, VALUE *argv, VALUE klass) { return apply2files(unlink_internal, argc, argv, 0); } struct rename_args { const char *src; const char *dst; }; static void * no_gvl_rename(void *ptr) { struct rename_args *ra = ptr; return (void *)(VALUE)rename(ra->src, ra->dst); } /* * :markup: markdown * * call-seq: * File.rename(path, new_path) -> 0 * * Moves the entry at the given `path` to the given `new_path`. * * Does not follow [symbolic links](rdoc-ref:file/symbolic_links.md); * if the entry is a symlink, the link itself is renamed. * * The examples below use two temporary directories: * * ```ruby * src_dirpath = '/tmp/src/' # => "/tmp/src/" * dst_dirpath = '/tmp/dst/' # => "/tmp/dst/" * Dir.mkdir(src_dirpath) * Dir.mkdir(dst_dirpath) * ``` * * The entry to be renamed may be a file: * * ```ruby * src_filepath = File.join(src_dirpath, 't.tmp') # => "/tmp/src/t.tmp" * File.write(src_filepath, 'foo') * dst_filepath = File.join(dst_dirpath, 'u.tmp') # => "/tmp/dst/u.tmp" * File.rename(src_filepath, dst_filepath) * File.exist?(src_filepath) # => false * File.exist?(dst_filepath) # => true * File.delete(dst_filepath) # Clean up. * ``` * * The entry to be renamed may be a symbolic link: * * ```ruby * filepath = File.join(src_dirpath, 't.tmp') # => "/tmp/src/t.tmp" * File.write(src_filepath, 'foo') * linkpath = File.join(src_dirpath, 'u.tmp') # => "/tmp/src/u.tmp" * File.symlink(filepath, linkpath) * File.readlink(linkpath) # => "/tmp/src/t.tmp" * newpath = File.join(dst_dirpath, 'v.tmp') # => "/tmp/dst/v.tmp" * File.rename(linkpath, newpath) # Symlink not followed. * File.readlink(newpath) # => "/tmp/src/t.tmp" * File.delete(filepath, newpath) # Clean up. * ``` * * The entry to be renamed may be a directory: * * ```ruby * old_dirpath = File.join(src_dirpath, 'olddir') # => "/tmp/src/olddir" * Dir.mkdir(old_dirpath) * new_dirpath = File.join(dst_dirpath, 'newdir') # => "/tmp/dst/newdir" * File.rename(old_dirpath, new_dirpath) * File.directory?(new_dirpath) # => true * Dir.rmdir(new_dirpath) # Clean up. * ``` * * Clean up: * * ```ruby * FileUtils.rm_rf(src_dirpath) # => ["/tmp/src/"] * FileUtils.rm_rf(dst_dirpath) # => ["/tmp/dst/"] * ``` * * Raises SystemCallError if the file cannot be renamed. */ static VALUE rb_file_s_rename(VALUE klass, VALUE from, VALUE to) { struct rename_args ra; VALUE f, t; FilePathValue(from); FilePathValue(to); f = rb_str_encode_ospath(from); t = rb_str_encode_ospath(to); ra.src = StringValueCStr(f); ra.dst = StringValueCStr(t); #if defined __CYGWIN__ errno = 0; #endif if (IO_WITHOUT_GVL_INT(no_gvl_rename, &ra) < 0) { int e = errno; #if defined DOSISH switch (e) { case EEXIST: if (chmod(ra.dst, 0666) == 0 && unlink(ra.dst) == 0 && rename(ra.src, ra.dst) == 0) return INT2FIX(0); } #endif syserr_fail2(e, from, to); } return INT2FIX(0); } /* * call-seq: * File.umask() -> integer * File.umask(integer) -> integer * * Returns the current umask value for this process. If the optional argument * is given, set the umask to that value and return the previous value. Umask * values are subtracted from the default permissions, so a umask of * +0222+ would make a file read-only for everyone. * * File.umask(0006) #=> 18 * File.umask #=> 6 */ static VALUE rb_file_s_umask(int argc, VALUE *argv, VALUE _) { mode_t omask = 0; switch (argc) { case 0: omask = umask(0); umask(omask); break; case 1: omask = umask(NUM2MODET(argv[0])); break; default: rb_error_arity(argc, 0, 1); } return MODET2NUM(omask); } #ifdef __CYGWIN__ #undef DOSISH #endif #if defined __CYGWIN__ || defined DOSISH #define DOSISH_UNC #define DOSISH_DRIVE_LETTER #define FILE_ALT_SEPARATOR '\\' #endif #ifdef FILE_ALT_SEPARATOR #define isdirsep(x) ((x) == '/' || (x) == FILE_ALT_SEPARATOR) # ifdef DOSISH static const char file_alt_separator[] = {FILE_ALT_SEPARATOR, '\0'}; # endif #else #define isdirsep(x) ((x) == '/') #endif #ifndef USE_NTFS # if defined _WIN32 # define USE_NTFS 1 # else # define USE_NTFS 0 # endif #endif #if USE_NTFS #define istrailinggarbage(x) ((x) == '.' || (x) == ' ') #define isADS(x) ((x) == ':') #else #define istrailinggarbage(x) 0 #endif #define enc_mbclen_needed(enc) (!rb_str_encindex_fastpath(rb_enc_to_index(enc))) #define Next(p, e, mb_enc, enc) ((p) + ((mb_enc) ? rb_enc_mbclen((p), (e), (enc)) : 1)) #define Inc(p, e, mb_enc, enc) ((p) = Next((p), (e), (mb_enc), (enc))) #if defined(DOSISH_UNC) #define has_unc(buf) (isdirsep((buf)[0]) && isdirsep((buf)[1])) #else #define has_unc(buf) 0 #endif #ifdef DOSISH_DRIVE_LETTER static inline int has_drive_letter(const char *buf) { if (ISALPHA(buf[0]) && buf[1] == ':') { return 1; } else { return 0; } } #ifndef _WIN32 static VALUE getcwdofdrv(int drv) { char drive[4]; char *oldcwd; VALUE drvcwd; drive[0] = drv; drive[1] = ':'; drive[2] = '\0'; /* the only way that I know to get the current directory of a particular drive is to change chdir() to that drive, so save the old cwd before chdir() */ oldcwd = ruby_getcwd(); if (chdir(drive) == 0) { drvcwd = rb_dir_getwd_ospath(); chdir(oldcwd); xfree(oldcwd); } else { /* perhaps the drive is not exist. we return only drive letter */ drvcwd = rb_enc_str_new_cstr(drive, rb_filesystem_encoding()); } return drvcwd; } static inline int not_same_drive(VALUE path, int drive) { const char *p = RSTRING_PTR(path); if (RSTRING_LEN(path) < 2) return 0; if (has_drive_letter(p)) { return TOLOWER(p[0]) != TOLOWER(drive); } else { return has_unc(p); } } #endif /* _WIN32 */ #endif /* DOSISH_DRIVE_LETTER */ static inline char * skiproot(const char *path, const char *end) { #ifdef DOSISH_DRIVE_LETTER if (path + 2 <= end && has_drive_letter(path)) path += 2; #endif while (path < end && isdirsep(*path)) path++; return (char *)path; } static inline char * enc_path_next(const char *s, const char *e, bool mb_enc, rb_encoding *enc) { while (s < e && !isdirsep(*s)) { Inc(s, e, mb_enc, enc); } return (char *)s; } #define nextdirsep rb_enc_path_next char * rb_enc_path_next(const char *s, const char *e, rb_encoding *enc) { return enc_path_next(s, e, enc_mbclen_needed(enc), enc); } #if defined(DOSISH_UNC) || defined(DOSISH_DRIVE_LETTER) #define skipprefix enc_path_skip_prefix #else #define skipprefix(path, end, mb_enc, enc) (path) #endif static inline char * enc_path_skip_prefix(const char *path, const char *end, bool mb_enc, rb_encoding *enc) { #if defined(DOSISH_UNC) || defined(DOSISH_DRIVE_LETTER) #ifdef DOSISH_UNC if (path + 2 <= end && isdirsep(path[0]) && isdirsep(path[1])) { path += 2; while (path < end && isdirsep(*path)) path++; if ((path = enc_path_next(path, end, mb_enc, enc)) < end && path + 2 <= end && !isdirsep(path[1])) { path = enc_path_next(path + 1, end, mb_enc, enc); } return (char *)path; } #endif #ifdef DOSISH_DRIVE_LETTER if (path + 2 <= end && has_drive_letter(path)) return (char *)(path + 2); #endif #endif /* defined(DOSISH_UNC) || defined(DOSISH_DRIVE_LETTER) */ return (char *)path; } char * rb_enc_path_skip_prefix(const char *path, const char *end, rb_encoding *enc) { return enc_path_skip_prefix(path, end, enc_mbclen_needed(enc), enc); } static inline char * skipprefixroot(const char *path, const char *end, rb_encoding *enc) { #if defined(DOSISH_UNC) || defined(DOSISH_DRIVE_LETTER) char *p = skipprefix(path, end, enc_mbclen_needed(enc), enc); while (p < end && isdirsep(*p)) p++; return p; #else return skiproot(path, end); #endif } char * rb_enc_path_skip_prefix_root(const char *path, const char *end, rb_encoding *enc) { return skipprefixroot(path, end, enc); } static char * enc_path_last_separator(const char *path, const char *end, bool mb_enc, rb_encoding *enc) { char *last = NULL; while (path < end) { if (isdirsep(*path)) { const char *tmp = path++; while (path < end && isdirsep(*path)) path++; if (path >= end) break; last = (char *)tmp; } else { Inc(path, end, mb_enc, enc); } } return last; } char * rb_enc_path_last_separator(const char *path, const char *end, rb_encoding *enc) { return enc_path_last_separator(path, end, enc_mbclen_needed(enc), enc); } static inline char * strrdirsep(const char *path, const char *end, bool mb_enc, rb_encoding *enc) { if (RB_UNLIKELY(mb_enc)) { return enc_path_last_separator(path, end, mb_enc, enc); } const char *cursor = end - 1; while (cursor >= path && isdirsep(cursor[0])) { cursor--; } while (cursor >= path) { if (isdirsep(cursor[0])) { while (cursor > path && isdirsep(cursor[-1])) { cursor--; } return (char *)cursor; } cursor--; } return NULL; } static char * chompdirsep(const char *path, const char *end, bool mb_enc, rb_encoding *enc) { while (path < end) { if (isdirsep(*path)) { const char *last = path++; while (path < end && isdirsep(*path)) path++; if (path >= end) return (char *)last; } else { Inc(path, end, mb_enc, enc); } } return (char *)path; } char * rb_enc_path_end(const char *path, const char *end, rb_encoding *enc) { if (path < end && isdirsep(*path)) path++; return chompdirsep(path, end, enc_mbclen_needed(enc), enc); } static rb_encoding * fs_enc_check(VALUE path1, VALUE path2) { rb_encoding *enc = rb_enc_check_str(path1, path2); int encidx = rb_enc_to_index(enc); if (encidx == ENCINDEX_US_ASCII) { encidx = rb_enc_get_index(path1); if (encidx == ENCINDEX_US_ASCII) encidx = rb_enc_get_index(path2); enc = rb_enc_from_index(encidx); } return enc; } #if USE_NTFS static char * ntfs_tail(const char *path, const char *end, bool mb_enc, rb_encoding *enc) { while (path < end && *path == '.') path++; while (path < end && !isADS(*path)) { if (istrailinggarbage(*path)) { const char *last = path++; while (path < end && istrailinggarbage(*path)) path++; if (path >= end || isADS(*path)) return (char *)last; } else if (isdirsep(*path)) { const char *last = path++; while (path < end && isdirsep(*path)) path++; if (path >= end) return (char *)last; if (isADS(*path)) path++; } else { Inc(path, end, mb_enc, enc); } } return (char *)path; } #endif /* USE_NTFS */ #define BUFCHECK(cond) do {\ bdiff = p - buf;\ if (cond) {\ do {buflen *= 2;} while (cond);\ rb_str_resize(result, buflen);\ buf = RSTRING_PTR(result);\ p = buf + bdiff;\ pend = buf + buflen;\ }\ } while (0) #define BUFINIT(result, buf, p, pend) do {\ if (!result) { result = rb_usascii_str_new(0, 1); } \ p = buf = RSTRING_PTR(result); \ buflen = RSTRING_LEN(result); \ pend = p + buflen; \ } while (0) #ifdef __APPLE__ # define SKIPPATHSEP(p) ((*(p)) ? 1 : 0) #else # define SKIPPATHSEP(p) 1 #endif #define BUFCOPY(srcptr, srclen) do { \ const int skip = SKIPPATHSEP(p); \ rb_str_set_len(result, p-buf+skip); \ BUFCHECK(bdiff + ((srclen)+skip) >= buflen); \ p += skip; \ memcpy(p, (srcptr), (srclen)); \ p += (srclen); \ } while (0) #define WITH_ROOTDIFF(stmt) do { \ rb_len_t rootdiff = root - buf; \ stmt; \ root = buf + rootdiff; \ } while (0) static VALUE copy_home_path(VALUE result, const char *dir) { char *buf; rb_len_t dirlen; int encidx; dirlen = strlen(dir); rb_str_resize(result, dirlen); memcpy(buf = RSTRING_PTR(result), dir, dirlen); encidx = rb_filesystem_encindex(); rb_enc_associate_index(result, encidx); #if defined FILE_ALT_SEPARATOR rb_encoding *enc = rb_enc_from_index(encidx); bool mb_enc = enc_mbclen_needed(enc); for (char *p = buf, *bend = p + dirlen; p < bend; Inc(p, bend, mb_enc, enc)) { if (*p == FILE_ALT_SEPARATOR) { *p = '/'; } } #endif return result; } VALUE rb_home_dir_of(VALUE user, VALUE result) { #ifdef HAVE_PWD_H VALUE dirname = rb_getpwdirnam_for_login(user); if (dirname == Qnil) { rb_raise(rb_eArgError, "user %"PRIsVALUE" doesn't exist", user); } const char *dir = RSTRING_PTR(dirname); #else extern char *getlogin(void); const char *pwPtr = 0; const char *login; # define endpwent() ((void)0) const char *dir, *username = RSTRING_PTR(user); rb_encoding *enc = rb_enc_get(user); #if defined _WIN32 rb_encoding *fsenc = rb_utf8_encoding(); #else rb_encoding *fsenc = rb_filesystem_encoding(); #endif if (enc != fsenc) { dir = username = RSTRING_PTR(rb_str_conv_enc(user, enc, fsenc)); } if ((login = getlogin()) && strcasecmp(username, login) == 0) dir = pwPtr = getenv("HOME"); if (!pwPtr) { rb_raise(rb_eArgError, "user %"PRIsVALUE" doesn't exist", user); } #endif copy_home_path(result, dir); return result; } #ifndef _WIN32 /* this encompasses rb_file_expand_path_internal */ VALUE rb_default_home_dir(VALUE result) { const char *dir = getenv("HOME"); #if defined HAVE_PWD_H if (!dir) { /* We'll look up the user's default home dir in the password db by * login name, if possible, and failing that will fall back to looking * the information up by uid (as would be needed for processes that * are not a descendant of login(1) or a work-alike). * * While the lookup by uid is more likely to succeed (since we always * have a uid, but may or may not have a login name), we prefer first * looking up by name to accommodate the possibility of multiple login * names (each with its own record in the password database, so each * with a potentially different home directory) being mapped to the * same uid (as explicitly allowed for by POSIX; see getlogin(3posix)). */ VALUE login_name = rb_getlogin(); # if !defined(HAVE_GETPWUID_R) && !defined(HAVE_GETPWUID) /* This is a corner case, but for backward compatibility reasons we * want to emit this error if neither the lookup by login name nor * lookup by getuid() has a chance of succeeding. */ if (NIL_P(login_name)) { rb_raise(rb_eArgError, "couldn't find login name -- expanding '~'"); } # endif /* !defined(HAVE_GETPWUID_R) && !defined(HAVE_GETPWUID) */ VALUE pw_dir = rb_getpwdirnam_for_login(login_name); if (NIL_P(pw_dir)) { pw_dir = rb_getpwdiruid(); if (NIL_P(pw_dir)) { rb_raise(rb_eArgError, "couldn't find home for uid '%ld'", (long)getuid()); } } /* found it */ copy_home_path(result, RSTRING_PTR(pw_dir)); rb_str_resize(pw_dir, 0); return result; } #endif /* defined HAVE_PWD_H */ if (!dir) { rb_raise(rb_eArgError, "couldn't find HOME environment -- expanding '~'"); } return copy_home_path(result, dir); } static VALUE ospath_new(const char *ptr, rb_len_t len, rb_encoding *fsenc) { #if NORMALIZE_UTF8PATH VALUE path = rb_str_normalize_ospath(ptr, len); rb_enc_associate(path, fsenc); return path; #else return rb_enc_str_new(ptr, len, fsenc); #endif } static char * append_fspath(VALUE result, VALUE fname, VALUE dirname, rb_encoding **enc, rb_encoding *fsenc) { if (RB_UNLIKELY(!rb_enc_asciicompat(fsenc) || rb_enc_str_coderange(dirname) != ENC_CODERANGE_7BIT)) { dirname = rb_str_new_shared(dirname); rb_enc_associate(dirname, fsenc); } char *buf, *cwdp; size_t dirlen = RSTRING_LEN(dirname); size_t buflen = rb_str_capacity(result); if (NORMALIZE_UTF8PATH || *enc != fsenc) { if (!rb_enc_compatible(fname, dirname)) { /* rb_enc_check must raise because the two encodings are not * compatible. */ rb_enc_check(fname, dirname); rb_bug("unreachable"); } rb_encoding *direnc = fs_enc_check(fname, dirname); if (direnc != fsenc) { dirname = rb_str_conv_enc(dirname, fsenc, direnc); } *enc = direnc; } RSTRING_GETMEM(dirname, cwdp, dirlen); do {buflen *= 2;} while (dirlen > buflen); rb_str_resize(result, buflen); buf = RSTRING_PTR(result); memcpy(buf, cwdp, dirlen); rb_enc_associate(result, *enc); return buf + dirlen; } VALUE rb_file_expand_path_internal(VALUE fname, VALUE dname, int abs_mode, int long_name, VALUE result) { const char *s, *b, *fend; char *buf, *p, *pend, *root; size_t buflen, bdiff; rb_encoding *enc, *fsenc = rb_filesystem_encoding(); s = StringValuePtr(fname); fend = s + RSTRING_LEN(fname); enc = rb_str_enc_get(fname); bool mb_enc = enc_mbclen_needed(enc); if (!mb_enc && RTEST(dname)) { mb_enc = enc_mbclen_needed(rb_str_enc_get(dname)); } if (s < fend && s[0] == '~' && abs_mode == 0) { /* execute only if NOT absolute_path() */ BUFINIT(result, buf, p, pend); // TOOD: right size the buffer rb_len_t userlen = 0; if (s + 1 == fend || isdirsep(s[1])) { buf = 0; b = 0; rb_str_set_len(result, 0); if (++s < fend) ++s; rb_default_home_dir(result); } else { s = nextdirsep(b = s, fend, enc); b++; /* b[0] is '~' */ userlen = s - b; BUFCHECK(bdiff + userlen >= buflen); memcpy(p, b, userlen); ENC_CODERANGE_CLEAR(result); rb_str_set_len(result, userlen); rb_enc_associate(result, enc); rb_home_dir_of(result, result); buf = p + 1; p += userlen; } if (!rb_is_absolute_path(RSTRING_PTR(result))) { if (userlen) { rb_enc_raise(enc, rb_eArgError, "non-absolute home of %.*s%.0"PRIsVALUE, (int)userlen, b, fname); } else { rb_raise(rb_eArgError, "non-absolute home"); } } BUFINIT(result, buf, p, pend); p = pend; } #ifdef DOSISH_DRIVE_LETTER /* skip drive letter */ else if (s + 1 < fend && has_drive_letter(s)) { BUFINIT(result, buf, p, pend); // TOOD: right size the buffer if (s + 2 < fend && isdirsep(s[2])) { /* specified drive letter, and full path */ /* skip drive letter */ BUFCHECK(bdiff + 2 >= buflen); memcpy(p, s, 2); p += 2; s += 2; rb_enc_copy(result, fname); } else { /* specified drive, but not full path */ int same = 0; if (!NIL_P(dname) && !not_same_drive(dname, s[0])) { rb_file_expand_path_internal(dname, Qnil, abs_mode, long_name, result); BUFINIT(result, buf, p, pend); if (has_drive_letter(p) && TOLOWER(p[0]) == TOLOWER(s[0])) { /* ok, same drive */ same = 1; } } if (!same) { char *e = append_fspath(result, fname, getcwdofdrv(*s), &enc, fsenc); BUFINIT(result, buf, p, pend); p = e; } else { rb_enc_associate(result, enc = fs_enc_check(result, fname)); p = pend; } p = chompdirsep(skiproot(buf, p), p, mb_enc, enc); s += 2; } } #endif /* DOSISH_DRIVE_LETTER */ else if (s == fend || !rb_is_absolute_path(s)) { if (!NIL_P(dname)) { if (result) { rb_file_expand_path_internal(dname, Qnil, abs_mode, long_name, result); } else { result = rb_usascii_str_new(0, RSTRING_LEN(dname) + RSTRING_LEN(fname) + 1); rb_file_expand_path_internal(dname, Qnil, abs_mode, long_name, result); if (RB_UNLIKELY(RSTRING_LEN(result) > RSTRING_LEN(dname))) { VALUE resized_result = rb_usascii_str_new(0, RSTRING_LEN(result) + RSTRING_LEN(fname) + 1); rb_str_set_len(resized_result, 0); rb_str_buf_append(resized_result, result); rb_str_set_len(result, 0); result = resized_result; } } rb_enc_associate(result, fs_enc_check(result, fname)); BUFINIT(result, buf, p, pend); p = pend; } else { VALUE cwd = rb_dir_getwd_ospath(); if (!result) { result = rb_usascii_str_new(0, RSTRING_LEN(cwd) + RSTRING_LEN(fname) + 1); } char *e = append_fspath(result, fname, rb_dir_getwd_ospath(), &enc, fsenc); BUFINIT(result, buf, p, pend); p = e; } #if defined DOSISH_DRIVE_LETTER || defined DOSISH_UNC if (s < fend && isdirsep(*s)) { /* specified full path, but not drive letter nor UNC */ /* we need to get the drive letter or UNC share name */ p = skipprefix(buf, p, mb_enc, enc); } else #endif /* defined DOSISH_DRIVE_LETTER || defined DOSISH_UNC */ p = chompdirsep(skiproot(buf, p), p, mb_enc, enc); } else { BUFINIT(result, buf, p, pend); size_t len; b = s; do s++; while (s < fend && isdirsep(*s)); len = s - b; p = buf + len; BUFCHECK(bdiff >= buflen); memset(buf, '/', len); rb_str_set_len(result, len); rb_enc_associate(result, fs_enc_check(result, fname)); } if (p > buf && p[-1] == '/') --p; else { rb_str_set_len(result, p-buf); BUFCHECK(bdiff + 1 >= buflen); *p = '/'; } rb_str_set_len(result, p-buf+1); BUFCHECK(bdiff + 1 >= buflen); p[1] = 0; root = skipprefix(buf, p+1, mb_enc, enc); b = s; while (s < fend) { switch (*s) { case '.': if (b == s++) { /* beginning of path element */ if (s == fend) { b = s; break; } switch (*s) { case '.': if (s+1 == fend || isdirsep(*(s+1))) { /* We must go back to the parent */ char *n; *p = '\0'; if (!(n = strrdirsep(root, p, mb_enc, enc))) { *p = '/'; } else { p = n; } b = ++s; } break; case '/': #if defined FILE_ALT_SEPARATOR case FILE_ALT_SEPARATOR: #endif b = ++s; break; default: /* ordinary path element, beginning don't move */ break; } } break; case '/': #if defined FILE_ALT_SEPARATOR case FILE_ALT_SEPARATOR: #endif if (s > b) { WITH_ROOTDIFF(BUFCOPY(b, s-b)); *p = '/'; } b = ++s; break; default: #ifdef __APPLE__ { int n = ignored_char_p(s, fend, enc); if (n) { if (s > b) { WITH_ROOTDIFF(BUFCOPY(b, s-b)); *p = '\0'; } b = s += n; break; } } #endif /* __APPLE__ */ Inc(s, fend, mb_enc, enc); break; } } if (s > b) { BUFCOPY(b, s-b); rb_str_set_len(result, p-buf); } if (p == skiproot(buf, p + !!*p) - 1) p++; rb_str_set_len(result, p - buf); rb_enc_check(fname, result); ENC_CODERANGE_CLEAR(result); return result; } #endif /* !_WIN32 (this ifdef started above rb_default_home_dir) */ static VALUE str_shrink(VALUE str) { rb_str_resize(str, RSTRING_LEN(str)); return str; } #define expand_path(fname, dname, abs_mode, long_name, result) \ str_shrink(rb_file_expand_path_internal(fname, dname, abs_mode, long_name, result)) #define check_expand_path_args(fname, dname) \ (((fname) = rb_get_path(fname)), \ (void)(NIL_P(dname) ? (dname) : ((dname) = rb_get_path(dname)))) static VALUE file_expand_path_1(VALUE fname, rb_len_t extra_capa) { VALUE buffer = rb_usascii_str_new(0, RSTRING_LEN(fname) + extra_capa); return rb_file_expand_path_internal(fname, Qnil, 0, 0, buffer); } VALUE rb_file_expand_path(VALUE fname, VALUE dname) { check_expand_path_args(fname, dname); return expand_path(fname, dname, 0, 1, Qfalse); } VALUE rb_file_expand_path_fast(VALUE fname, VALUE dname) { return expand_path(fname, dname, 0, 0, Qfalse); } VALUE rb_file_s_expand_path(int argc, const VALUE *argv) { rb_check_arity(argc, 1, 2); return rb_file_expand_path(argv[0], argc > 1 ? argv[1] : Qnil); } /* * :markup: markdown * * call-seq: * File.expand_path(path, dirpath = '.') -> absolute_path * * Returns the string absolute path for the given `path`. * * Evaluates a relative path with respect to the directory given by `dirpath`: * * ```ruby * Dir.chdir('/snap') * # Default dirpath. * File.expand_path('README') # => "/snap/README" * File.expand_path('bin') # => "/snap/bin" * File.expand_path('bin/../var') # => "/snap/var" # Cleaned. * # Other dirpath. * File.expand_path('../zip', '/usr/bin/ruby') # => "/usr/bin/zip" * Dir.chdir('/usr/bin') * File.expand_path('../../snap', __FILE__) # => "/usr/snap" * ``` * * Evaluates an absolute path without respect to `dirpath`: * * ```ruby * File.expand_path('/snap') # => "/snap" * File.expand_path('/snap', 'nosuch') # => "/snap" * File.expand_path('/snap/../snap') # => "/snap" # Cleaned. * ``` * * More examples: * * ``` * Dir.chdir('/usr/bin') * File.expand_path('../../snap', __FILE__) # => "/usr/snap" * File.expand_path('../../snap') # => "/snap" * ``` * */ static VALUE s_expand_path(int c, const VALUE * v, VALUE _) { return rb_file_s_expand_path(c, v); } VALUE rb_file_absolute_path(VALUE fname, VALUE dname) { check_expand_path_args(fname, dname); return expand_path(fname, dname, 1, 1, Qfalse); } VALUE rb_file_s_absolute_path(int argc, const VALUE *argv) { rb_check_arity(argc, 1, 2); return rb_file_absolute_path(argv[0], argc > 1 ? argv[1] : Qnil); } /* * :markup: markdown * * call-seq: * File.absolute_path(path, dirpath = '.') -> absolute_path * * Returns the string absolute path for the given `path`. * * Evaluates a relative path with respect to the directory given by `dirpath`: * * ```ruby * Dir.chdir('/snap') * # Default dirpath. * File.absolute_path('README') # => "/snap/README" * File.absolute_path('bin') # => "/snap/bin" * File.absolute_path('bin/../var') # => "/snap/var" * # Other dirpath. * File.absolute_path('../zip', '/usr/bin/ruby') # => "/usr/bin/zip" * ``` * * For an absolute path, argument `dirpath` is ignored: * * ```ruby * File.absolute_path('/snap', '/usr/bin') # => "/snap" * File.absolute_path('/snap', 'nosuch') # => "/snap" * ``` * * A leading tilde character (`'~'`), is not expanded: * * ```ruby * Dir.chdir('/usr/bin') * File.absolute_path("~") # => "/usr/bin/~" * File.absolute_path("~/Documents") # => "/usr/bin/~/Documents" * ``` * */ static VALUE s_absolute_path(int c, const VALUE * v, VALUE _) { return rb_file_s_absolute_path(c, v); } /* * :markup: markdown * * call-seq: * File.absolute_path?(path) -> true or false * * Returns whether the given `path` is an absolute path: * * ```ruby * File.absolute_path?('/home') # => true * File.absolute_path?('lib') # => false * ``` * * The result is OS-dependent for some paths: * * ```ruby * File.absolute_path?('C:/') # => true # On Windows. * File.absolute_path?('C:/') # => false # Elsewhere. * ``` * */ static VALUE s_absolute_path_p(VALUE klass, VALUE fname) { VALUE path = rb_get_path(fname); if (!rb_is_absolute_path(RSTRING_PTR(path))) return Qfalse; return Qtrue; } enum rb_realpath_mode { RB_REALPATH_CHECK, RB_REALPATH_DIR, RB_REALPATH_STRICT, RB_REALPATH_MODE_MAX }; static int realpath_rec(rb_len_t *prefixlenp, VALUE *resolvedp, const char *unresolved, VALUE fallback, VALUE loopcheck, enum rb_realpath_mode mode, int last) { const char *pend = unresolved + strlen(unresolved); rb_encoding *enc = rb_enc_get(*resolvedp); ID resolving; CONST_ID(resolving, "resolving"); while (unresolved < pend) { const char *testname = unresolved; const char *unresolved_firstsep = rb_enc_path_next(unresolved, pend, enc); rb_len_t testnamelen = unresolved_firstsep - unresolved; const char *unresolved_nextname = unresolved_firstsep; while (unresolved_nextname < pend && isdirsep(*unresolved_nextname)) unresolved_nextname++; unresolved = unresolved_nextname; if (testnamelen == 1 && testname[0] == '.') { } else if (testnamelen == 2 && testname[0] == '.' && testname[1] == '.') { if (*prefixlenp < RSTRING_LEN(*resolvedp)) { bool mb_enc = enc_mbclen_needed(enc); const char *resolved_str = RSTRING_PTR(*resolvedp); const char *resolved_names = resolved_str + *prefixlenp; const char *lastsep = strrdirsep(resolved_names, resolved_str + RSTRING_LEN(*resolvedp), mb_enc, enc); rb_len_t len = lastsep ? lastsep - resolved_names : 0; rb_str_resize(*resolvedp, *prefixlenp + len); } } else { VALUE checkval; VALUE testpath = rb_str_dup(*resolvedp); if (*prefixlenp < RSTRING_LEN(testpath)) rb_str_cat2(testpath, "/"); #if defined(DOSISH_UNC) || defined(DOSISH_DRIVE_LETTER) if (*prefixlenp > 1 && *prefixlenp == RSTRING_LEN(testpath)) { const char *prefix = RSTRING_PTR(testpath); const char *last = rb_enc_left_char_head(prefix, prefix + *prefixlenp - 1, prefix + *prefixlenp, enc); if (!isdirsep(*last)) rb_str_cat2(testpath, "/"); } #endif rb_str_cat(testpath, testname, testnamelen); checkval = rb_hash_aref(loopcheck, testpath); if (!NIL_P(checkval)) { if (checkval == ID2SYM(resolving)) { if (mode == RB_REALPATH_CHECK) { errno = ELOOP; return -1; } rb_syserr_fail_path(ELOOP, testpath); } else { *resolvedp = rb_str_dup(checkval); } } else { struct stat sbuf; int ret; ret = lstat_without_gvl(RSTRING_PTR(testpath), &sbuf); if (ret == -1) { int e = errno; if (e == ENOENT && !NIL_P(fallback)) { if (stat_without_gvl(RSTRING_PTR(fallback), &sbuf) == 0) { rb_str_replace(*resolvedp, fallback); return 0; } } if (mode == RB_REALPATH_CHECK) return -1; if (e == ENOENT) { if (mode == RB_REALPATH_STRICT || !last || *unresolved_firstsep) rb_syserr_fail_path(e, testpath); *resolvedp = testpath; break; } else { rb_syserr_fail_path(e, testpath); } } #ifdef HAVE_READLINK if (S_ISLNK(sbuf.st_mode)) { VALUE link; VALUE link_orig = Qnil; const char *link_prefix, *link_names; rb_len_t link_prefixlen; rb_hash_aset(loopcheck, testpath, ID2SYM(resolving)); link = rb_readlink(testpath, enc); link_prefix = RSTRING_PTR(link); link_names = skipprefixroot(link_prefix, link_prefix + RSTRING_LEN(link), rb_enc_get(link)); link_prefixlen = link_names - link_prefix; if (link_prefixlen > 0) { rb_encoding *tmpenc, *linkenc = rb_enc_get(link); link_orig = link; link = rb_str_subseq(link, 0, link_prefixlen); tmpenc = fs_enc_check(*resolvedp, link); if (tmpenc != linkenc) link = rb_str_conv_enc(link, linkenc, tmpenc); *resolvedp = link; *prefixlenp = link_prefixlen; } if (realpath_rec(prefixlenp, resolvedp, link_names, testpath, loopcheck, mode, !*unresolved_firstsep)) return -1; RB_GC_GUARD(link_orig); RB_GC_GUARD(link); rb_hash_aset(loopcheck, testpath, rb_str_dup_frozen(*resolvedp)); } else #endif /* HAVE_READLINK */ { VALUE s = rb_str_dup_frozen(testpath); rb_hash_aset(loopcheck, s, s); *resolvedp = testpath; } } } } return 0; } #ifdef DOSISH_DRIVE_LETTER /* expand_path on Windows builds the result in the code page of the * argument encoding, which may not represent the current directory */ static VALUE ospath_for_expand(VALUE path) { switch (ENCODING_GET(path)) { case ENCINDEX_ASCII_8BIT: case ENCINDEX_US_ASCII: return rb_enc_associate_index(rb_str_dup(path), rb_filesystem_encindex()); } return TO_OSPATH(path); } #endif static VALUE rb_check_realpath_emulate(VALUE basedir, VALUE path, rb_encoding *origenc, enum rb_realpath_mode mode) { rb_len_t prefixlen; VALUE resolved; VALUE unresolved_path; VALUE loopcheck; VALUE curdir = Qnil; rb_encoding *enc; char *path_names = NULL, *basedir_names = NULL, *curdir_names = NULL; char *ptr, *prefixptr = NULL, *pend; rb_len_t len; #ifdef DOSISH_DRIVE_LETTER VALUE rootdir = path; RSTRING_GETMEM(path, ptr, len); if (!NIL_P(basedir) && skipprefixroot(ptr, ptr + len, rb_enc_get(path)) == ptr) { FilePathValue(basedir); rootdir = basedir; } RSTRING_GETMEM(rootdir, ptr, len); if (len >= 2 && has_drive_letter(ptr) && (len == 2 || !isdirsep(ptr[2]))) { /* Expand a drive-relative path or basedir against the current * directory of the drive, as File.absolute_path does */ if (!NIL_P(basedir)) basedir = ospath_for_expand(rb_get_path(basedir)); path = rb_file_absolute_path(ospath_for_expand(path), basedir); basedir = Qnil; } #endif unresolved_path = rb_str_dup_frozen(path); if (!NIL_P(basedir)) { FilePathValue(basedir); basedir = TO_OSPATH(rb_str_dup_frozen(basedir)); } enc = rb_enc_get(unresolved_path); unresolved_path = TO_OSPATH(unresolved_path); RSTRING_GETMEM(unresolved_path, ptr, len); path_names = skipprefixroot(ptr, ptr + len, rb_enc_get(unresolved_path)); if (ptr != path_names) { resolved = rb_str_subseq(unresolved_path, 0, path_names - ptr); goto root_found; } if (!NIL_P(basedir)) { RSTRING_GETMEM(basedir, ptr, len); basedir_names = skipprefixroot(ptr, ptr + len, rb_enc_get(basedir)); if (ptr != basedir_names) { resolved = rb_str_subseq(basedir, 0, basedir_names - ptr); goto root_found; } } curdir = rb_dir_getwd_ospath(); RSTRING_GETMEM(curdir, ptr, len); curdir_names = skipprefixroot(ptr, ptr + len, rb_enc_get(curdir)); resolved = rb_str_subseq(curdir, 0, curdir_names - ptr); root_found: RSTRING_GETMEM(resolved, prefixptr, prefixlen); pend = prefixptr + prefixlen; bool mb_enc = enc_mbclen_needed(enc); ptr = chompdirsep(prefixptr, pend, mb_enc, enc); if (ptr < pend) { prefixlen = ++ptr - prefixptr; rb_str_set_len(resolved, prefixlen); } #ifdef FILE_ALT_SEPARATOR while (prefixptr < ptr) { if (*prefixptr == FILE_ALT_SEPARATOR) { *prefixptr = '/'; } Inc(prefixptr, pend, mb_enc, enc); } #endif switch (rb_enc_to_index(enc)) { case ENCINDEX_ASCII_8BIT: case ENCINDEX_US_ASCII: rb_enc_associate_index(resolved, rb_filesystem_encindex()); } loopcheck = rb_hash_new(); if (curdir_names) { if (realpath_rec(&prefixlen, &resolved, curdir_names, Qnil, loopcheck, mode, 0)) return Qnil; } if (basedir_names) { if (realpath_rec(&prefixlen, &resolved, basedir_names, Qnil, loopcheck, mode, 0)) return Qnil; } if (realpath_rec(&prefixlen, &resolved, path_names, Qnil, loopcheck, mode, 1)) return Qnil; if (origenc && origenc != rb_enc_get(resolved)) { if (rb_enc_str_asciionly_p(resolved)) { rb_enc_associate(resolved, origenc); } else { resolved = rb_str_conv_enc(resolved, NULL, origenc); } } RB_GC_GUARD(unresolved_path); RB_GC_GUARD(curdir); return resolved; } static VALUE rb_file_join(rb_len_t argc, VALUE *args); #ifndef HAVE_REALPATH static VALUE rb_check_realpath_emulate_try(VALUE arg) { VALUE *args = (VALUE *)arg; return rb_check_realpath_emulate(args[0], args[1], (rb_encoding *)args[2], RB_REALPATH_CHECK); } static VALUE rb_check_realpath_emulate_rescue(VALUE arg, VALUE exc) { return Qnil; } #endif /* HAVE_REALPATH */ static VALUE rb_check_realpath_internal(VALUE basedir, VALUE path, rb_encoding *origenc, enum rb_realpath_mode mode) { #ifdef HAVE_REALPATH VALUE unresolved_path; char *resolved_ptr = NULL; VALUE resolved; if (mode == RB_REALPATH_DIR) { return rb_check_realpath_emulate(basedir, path, origenc, mode); } unresolved_path = rb_str_dup_frozen(path); if (*RSTRING_PTR(unresolved_path) != '/' && !NIL_P(basedir)) { VALUE paths[2] = {basedir, unresolved_path}; unresolved_path = rb_file_join(2, paths); } if (origenc) unresolved_path = TO_OSPATH(unresolved_path); if ((resolved_ptr = realpath(RSTRING_PTR(unresolved_path), NULL)) == NULL) { /* wasi-libc 22 and later support realpath(3) but return ENOTSUP when the underlying host syscall returns it. glibc realpath(3) does not allow /path/to/file.rb/../other_file.rb, returning ENOTDIR in that case. glibc realpath(3) can also return ENOENT for paths that exist, such as /dev/fd/5. Fallback to the emulated approach in either of those cases. */ if (errno == ENOTSUP || errno == ENOTDIR || (errno == ENOENT && rb_file_exist_p(0, unresolved_path))) { return rb_check_realpath_emulate(basedir, path, origenc, mode); } if (mode == RB_REALPATH_CHECK) { return Qnil; } rb_sys_fail_path(unresolved_path); } resolved = ospath_new(resolved_ptr, strlen(resolved_ptr), rb_filesystem_encoding()); free(resolved_ptr); # if !defined(__linux__) && !defined(__APPLE__) /* As `resolved` is a String in the filesystem encoding, no * conversion is needed */ struct stat st; if (stat_without_gvl(RSTRING_PTR(resolved), &st) < 0) { if (mode == RB_REALPATH_CHECK) { return Qnil; } rb_sys_fail_path(unresolved_path); } # endif /* !defined(__linux__) && !defined(__APPLE__) */ if (origenc && origenc != rb_enc_get(resolved)) { if (!rb_enc_str_asciionly_p(resolved)) { resolved = rb_str_conv_enc(resolved, NULL, origenc); } rb_enc_associate(resolved, origenc); } if (is_broken_string(resolved)) { rb_enc_associate(resolved, rb_filesystem_encoding()); if (is_broken_string(resolved)) { rb_enc_associate(resolved, rb_ascii8bit_encoding()); } } RB_GC_GUARD(unresolved_path); return resolved; #else /* !HAVE_REALPATH */ if (mode == RB_REALPATH_CHECK) { VALUE arg[3]; arg[0] = basedir; arg[1] = path; arg[2] = (VALUE)origenc; return rb_rescue(rb_check_realpath_emulate_try, (VALUE)arg, rb_check_realpath_emulate_rescue, Qnil); } else { return rb_check_realpath_emulate(basedir, path, origenc, mode); } #endif /* HAVE_REALPATH */ } VALUE rb_realpath_internal(VALUE basedir, VALUE path, int strict) { const enum rb_realpath_mode mode = strict ? RB_REALPATH_STRICT : RB_REALPATH_DIR; return rb_check_realpath_internal(basedir, path, rb_enc_get(path), mode); } VALUE rb_check_realpath(VALUE basedir, VALUE path, rb_encoding *enc) { return rb_check_realpath_internal(basedir, path, enc, RB_REALPATH_CHECK); } /* * call-seq: * File.realpath(pathname [, dir_string]) -> real_pathname * * Returns the real (absolute) pathname of _pathname_ in the actual * filesystem not containing symlinks or useless dots. * * If _dir_string_ is given, it is used as a base directory * for interpreting relative pathname instead of the current directory. * * All components of the pathname must exist when this method is * called. */ static VALUE rb_file_s_realpath(int argc, VALUE *argv, VALUE klass) { VALUE basedir = (rb_check_arity(argc, 1, 2) > 1) ? argv[1] : Qnil; VALUE path = argv[0]; FilePathValue(path); return rb_realpath_internal(basedir, path, 1); } /* * call-seq: * File.realdirpath(pathname [, dir_string]) -> real_pathname * * Returns the real (absolute) pathname of _pathname_ in the actual filesystem. * The real pathname doesn't contain symlinks or useless dots. * * If _dir_string_ is given, it is used as a base directory * for interpreting relative pathname instead of the current directory. * * The last component of the real pathname can be nonexistent. */ static VALUE rb_file_s_realdirpath(int argc, VALUE *argv, VALUE klass) { VALUE basedir = (rb_check_arity(argc, 1, 2) > 1) ? argv[1] : Qnil; VALUE path = argv[0]; FilePathValue(path); return rb_realpath_internal(basedir, path, 0); } static size_t rmext(const char *p, rb_len_t l0, rb_len_t l1, const char *e, rb_len_t l2, rb_encoding *enc) { int len1, len2; unsigned int c; const char *s, *last; if (!e || !l2) return 0; c = rb_enc_codepoint_len(e, e + l2, &len1, enc); if (rb_enc_ascget(e + len1, e + l2, &len2, enc) == '*' && len1 + len2 == l2) { if (c == '.') return l0; s = p; e = p + l1; last = e; while (s < e) { if (rb_enc_codepoint_len(s, e, &len1, enc) == c) last = s; s += len1; } return last - p; } if (l1 < l2) return l1; s = p+l1-l2; if (!at_char_boundary(p, s, p+l1, enc)) return 0; #if CASEFOLD_FILESYSTEM #define fncomp strncasecmp #else #define fncomp strncmp #endif if (fncomp(s, e, l2) == 0) { return l1-l2; } return 0; } static inline const char * enc_find_basename(const char *name, rb_len_t *baselen, rb_len_t *alllen, bool mb_enc, rb_encoding *enc) { const char *p, *q, *e, *end; rb_len_t f = 0, n = -1; rb_len_t len = (alllen ? (size_t)*alllen : strlen(name)); if (len <= 0) { return name; } end = name + len; name = skipprefix(name, end, mb_enc, enc); #if defined DOSISH_DRIVE_LETTER || defined DOSISH_UNC const char *root = name; #endif while (name < end && isdirsep(*name)) { name++; } if (name == end) { p = name - 1; f = 1; #if defined DOSISH_DRIVE_LETTER || defined DOSISH_UNC if (name != root) { /* has slashes */ } #ifdef DOSISH_DRIVE_LETTER else if (*p == ':') { p++; f = 0; } #endif /* DOSISH_DRIVE_LETTER */ #ifdef DOSISH_UNC else { p = "/"; } #endif /* DOSISH_UNC */ #endif /* defined DOSISH_DRIVE_LETTER || defined DOSISH_UNC */ } else { p = strrdirsep(name, end, mb_enc, enc); if (!p) { p = name; } else { while (isdirsep(*p)) { p++; /* skip last / */ } } #if USE_NTFS n = ntfs_tail(p, end, mb_enc, enc) - p; #else n = chompdirsep(p, end, mb_enc, enc) - p; #endif for (q = p; q - p < n && *q == '.'; q++); for (e = 0; q - p < n; Inc(q, end, mb_enc, enc)) { if (*q == '.') e = q; } if (e) { f = e - p; } else { f = n; } } if (baselen) { *baselen = f; } if (alllen) { *alllen = n; } return p; } const char * ruby_enc_find_basename(const char *name, rb_len_t *baselen, rb_len_t *alllen, rb_encoding *enc) { return enc_find_basename(name, baselen, alllen, enc_mbclen_needed(enc), enc); } /* * call-seq: * File.basename(path, suffix = '') -> string * * Returns a new string containing all or part of the last component of the given +path+. * Components are delimited by the value of constant File::SEPARATOR * and, if non-+nil+, the value of constant File::ALT_SEPARATOR. * * When +suffix+ is the empty string '', * returns all of the last entry: * * File.basename('foo/bar/baz/bat.txt') # => "bat.txt" * File.basename('foo/bar/baz') # => "baz" * * File::SEPARATOR # => "/" * File.basename('foo/bar.txt////') # => "bar.txt" * File::ALT_SEPARATOR # => "\\" # On Windows. * File.basename('foo/bar.txt//\\\\//') # => "bar.txt" * * When +suffix+ is '.*', * the last {filename extension}[https://en.wikipedia.org/wiki/Filename_extension], * if any, is removed: * * File.basename('foo/bar.txt', '.*') # => "bar" * File.basename('foo/bar.txt.old', '.*') # => "bar.txt" * File.basename('foo/bar', '.*') # => "bar" * * When +suffix+ is any string other than '' or '.*', * the matching trailing substring, if any, is removed: * * File.basename('foo/bar.txt', '.txt') # => "bar" * File.basename('foo/bar.txt', 'txt') # => "bar." * File.basename('foo/bar.txt', '*') # => "bar.txt" * File.basename('foo/bar.txt', '.') # => "bar.txt" * */ static VALUE rb_file_s_basename(int argc, VALUE *argv, VALUE _) { VALUE fname, fext = Qnil; const char *name, *p, *fp = 0; rb_len_t f = 0, n; rb_encoding *enc; argc = rb_check_arity(argc, 1, 2); fname = argv[0]; CheckPath(fname, name); if (argc == 2) { fext = argv[1]; fp = StringValueCStr(fext); check_path_encoding(fext); } if (NIL_P(fext) || !(enc = rb_enc_compatible(fname, fext))) { enc = rb_str_enc_get(fname); } n = RSTRING_LEN(fname); if (n <= 0 || !*name) { return rb_enc_str_new(0, 0, enc); } bool mb_enc = enc_mbclen_needed(enc); p = enc_find_basename(name, &f, &n, mb_enc, enc); if (n >= 0) { if (!fp) { f = n; } else { if (!(f = rmext(p, f, n, fp, RSTRING_LEN(fext), enc))) { f = n; } RB_GC_GUARD(fext); } if (f == RSTRING_LEN(fname)) { return rb_str_new_shared(fname); } } return rb_enc_str_new(p, f, enc); } static VALUE rb_file_dirname_n(VALUE fname, int n); /* * call-seq: * File.dirname(path, count = 1) -> string * * Returns a string path containing all but the last +count+ components * of the given +path+: * * File.dirname('/usr/lib/linux') # => "/usr/lib" * File.dirname('/usr') # => "/" * File.dirname('/') # => "/" * File.dirname('lib/') # => "." * File.dirname('nosuch') # => "." * File.dirname('/usr/lib/linux', 2) # => "/usr" * File.dirname('/usr/lib/linux', 20) # => "/" * File.dirname('/usr/lib/linux', 0) # => "/usr/lib/linux" * * Components are delimited by File::SEPARATOR and, if non-+nil+, File::ALT_SEPARATOR. * */ static VALUE rb_file_s_dirname(int argc, VALUE *argv, VALUE klass) { int n = 1; if ((argc = rb_check_arity(argc, 1, 2)) > 1) { n = NUM2INT(argv[1]); } return rb_file_dirname_n(argv[0], n); } VALUE rb_file_dirname(VALUE fname) { return rb_file_dirname_n(fname, 1); } static VALUE rb_file_dirname_n(VALUE fname, int n) { const char *name, *root, *p, *end; VALUE dirname; if (n < 0) rb_raise(rb_eArgError, "negative level: %d", n); CheckPath(fname, name); end = name + RSTRING_LEN(fname); bool mb_enc = !rb_str_enc_fastpath(fname); rb_encoding *enc = rb_str_enc_get(fname); root = skiproot(name, end); #ifdef DOSISH_UNC if (root > name + 1 && isdirsep(*name)) root = skipprefix(name = root - 2, end, mb_enc, enc); #else if (root > name + 1) name = root - 1; #endif if (n > (end - root + 1) / 2) { p = root; } else { p = end; while (n) { if (!(p = strrdirsep(root, p, mb_enc, enc))) { p = root; break; } n--; } } if (p == name) { return rb_enc_str_new(".", 1, enc); } #ifdef DOSISH_DRIVE_LETTER if (name + 3 < end && has_drive_letter(name) && isdirsep(*(name + 2))) { const char *top = skiproot(name + 2, end); dirname = rb_enc_str_new(name, 3, enc); rb_str_cat(dirname, top, p - top); } else #endif dirname = rb_enc_str_new(name, p - name, enc); #ifdef DOSISH_DRIVE_LETTER if (root == name + 2 && p == root && name[1] == ':') rb_str_cat(dirname, ".", 1); #endif return dirname; } static inline const char * enc_find_extname(const char *name, rb_len_t *len, bool mb_enc, rb_encoding *enc) { const char *p, *e, *end = name + (len ? *len : (rb_len_t)strlen(name)); p = strrdirsep(name, end, mb_enc, enc); /* get the last path component */ if (!p) p = name; else do name = ++p; while (isdirsep(*p)); e = 0; while (*p && *p == '.') p++; while (*p) { if (*p == '.' || istrailinggarbage(*p)) { #if USE_NTFS const char *last = p++, *dot = last; while (istrailinggarbage(*p)) { if (*p == '.') dot = p; p++; } if (!*p || isADS(*p)) { p = last; break; } if (*last == '.' || dot > last) e = dot; continue; #else e = p; /* get the last dot of the last component */ #endif /* USE_NTFS */ } #if USE_NTFS else if (isADS(*p)) { break; } #endif else if (isdirsep(*p)) break; Inc(p, end, mb_enc, enc); } if (len) { /* no dot, or the only dot is first or end? */ if (!e || e == name) *len = 0; else if (e+1 == p) *len = 1; else *len = p - e; } return e; } /* * accept a String, and return the pointer of the extension. * if len is passed, set the length of extension to it. * returned pointer is in ``name'' or NULL. * returns *len * no dot NULL 0 * dotfile top 0 * end with dot dot 1 * .ext dot len of .ext * .ext:stream dot len of .ext without :stream (NTFS only) * */ const char * ruby_enc_find_extname(const char *name, rb_len_t *len, rb_encoding *enc) { return enc_find_extname(name, len, enc_mbclen_needed(enc), enc); } /* * :markup: markdown * * call-seq: * File.extname(path) -> extension * * Returns the filename extension -- * usually the portion of the string `path` * beginning from the last period: * * ```ruby * File.extname('t.rb') # => ".rb" * File.extname('foo.bar.t.rb') # => ".rb" * File.extname('foo/bar/t.rb') # => ".rb" * File.extname('nosuch.txt') # => ".txt" # Path need not exist. * ``` * * Returns the entire string when there is no period: * * ```ruby * Pathname('foo').extname # => "" * ``` * * Returns an empty string when the only period is the first character: * * ```ruby * File.extname('.irbrc') # => "" * ``` * * Returns an empty string or `'.'` when `path` ends with a period: * * ``` * File.extname('foo.') # => "" # On Windows. * File.extname('foo.') # => "." # Elsewhere. * File.extname('foo....') # => "" # On Windows. * File.extname('foo....') # => "." # Elsewhere. * ``` * */ static VALUE rb_file_s_extname(VALUE klass, VALUE fname) { const char *name; CheckPath(fname, name); rb_len_t len = RSTRING_LEN(fname); if (len < 1) { return rb_enc_str_new(0, 0, rb_str_enc_get(fname)); } bool mb_enc = !rb_str_enc_fastpath(fname); rb_encoding *enc = rb_str_enc_get(fname); const char *ext = enc_find_extname(name, &len, mb_enc, enc); return rb_enc_str_new(ext, len, enc); } /* * :markup: markdown * * call-seq: * File.path(path) -> string * * Returns a string representation of the given `path`: * * ```ruby * File.path(File::NULL) # => "/dev/null" * File.path('/tmp') # => "/tmp" * File.path('../ruby') # => "../ruby" * File.path($stdin) # => "" * File.path('nosuch') # => "nosuch" * ``` * */ static VALUE rb_file_s_path(VALUE klass, VALUE fname) { return rb_get_path(fname); } /* * :markup: markdown * * call-seq: * File.split(string) -> array_of_strings * * Returns a 2-element array of strings containing the ::dirname and ::basename * of the the given `string`: * * ```ruby * File.split('doc/maintainers.md') # => ["doc", "maintainers.md"] * File.split('doc/') # => [".", "doc"] * File.split('README.md') # => [".", "README.md"] * File.split('/tmp/nosuch') # => ["/tmp", "nosuch"] * File.split('@@##$$/%%^^&&') # => ["@@#\#$$", "%%^^&&"] * ``` * */ static VALUE rb_file_s_split(VALUE klass, VALUE path) { FilePathStringValue(path); /* get rid of converting twice */ return rb_assoc_new(rb_file_dirname(path), rb_file_s_basename(1,&path,Qundef)); } static VALUE rb_file_join_ary(VALUE ary); static VALUE file_inspect_join(VALUE ary, VALUE arg, int recur) { if (recur || ary == arg) rb_raise(rb_eArgError, "recursive array"); return rb_file_join_ary(arg); } static VALUE rb_file_join_ary(VALUE ary) { rb_len_t len, i; VALUE result, tmp; const char *name, *tail; int checked = TRUE; rb_encoding *enc; if (RARRAY_LEN(ary) == 0) return rb_str_new(0, 0); len = 1; for (i=0; i 0 && isdirsep(RSTRING_PTR(tmp)[0])) { rb_str_set_len(result, tail - name); } else if (tail == name + len) { rb_str_cat(result, "/", 1); } } enc = fs_enc_check(result, tmp); rb_str_buf_append(result, tmp); rb_enc_associate(result, enc); } RBASIC_SET_CLASS_RAW(result, rb_cString); return result; } static inline VALUE rb_file_join_fastpath(rb_len_t argc, VALUE *args) { rb_len_t size = argc; rb_len_t i; for (i = 0; i < argc; i++) { VALUE tmp = args[i]; if (RB_LIKELY(RB_TYPE_P(tmp, T_STRING) && rb_str_enc_fastpath(tmp))) { size += RSTRING_LEN(tmp); } else { return 0; } } VALUE result = rb_str_buf_new(size); int encidx = ENCODING_GET_INLINED(args[0]); ENCODING_SET_INLINED(result, encidx); rb_str_buf_append(result, args[0]); const char *name = RSTRING_PTR(result); for (i = 1; i < argc; i++) { VALUE tmp = args[i]; rb_len_t len = RSTRING_LEN(result); const char *tmp_s; rb_len_t tmp_len; RSTRING_GETMEM(tmp, tmp_s, tmp_len); if (tmp_len > 0 && isdirsep(tmp_s[0])) { // right side has a leading separator, remove left side separators. rb_len_t chomp = len; while (chomp > 0 && isdirsep(name[chomp - 1])) { --chomp; } rb_str_set_len(result, chomp); } else if (len < 1 || !isdirsep(name[len - 1])) { // neither side have a separator, append one; rb_str_cat(result, "/", 1); } if (RB_UNLIKELY(ENCODING_GET_INLINED(tmp) != encidx)) { rb_encoding *new_enc = fs_enc_check(result, tmp); rb_enc_associate(result, new_enc); encidx = rb_enc_to_index(new_enc); } rb_str_buf_cat(result, tmp_s, tmp_len); } rb_str_null_check(result); return result; } static inline VALUE rb_file_join(rb_len_t argc, VALUE *args) { if (RB_UNLIKELY(argc == 0)) { return rb_str_new(0, 0); } VALUE result = rb_file_join_fastpath(argc, args); if (RB_LIKELY(result)) { return result; } return rb_file_join_ary(rb_ary_new_from_values(argc, args)); } /* * call-seq: * File.join(*components) -> string * * Returns a new string formed by joining the given string +components+ * with character '/': * * File.join # => "" * File.join('foo') # => "foo" * File.join(*%w[bar baz bat]) # => "bar/baz/bat" * */ static VALUE rb_file_s_join(int argc, VALUE *argv, VALUE klass) { return rb_file_join(argc, argv); } #if defined(HAVE_TRUNCATE) struct truncate_arg { const char *path; rb_off_t pos; }; static void * nogvl_truncate(void *ptr) { struct truncate_arg *ta = ptr; return (void *)(VALUE)truncate(ta->path, ta->pos); } /* * :markup: markdown * * call-seq: * File.truncate(filepath, size) -> 0 * * Adjusts the size of file `filepath` to the given `size`: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, '0123456789') * File.read(filepath) # => "0123456789" * File.truncate(filepath, 5) * File.read(filepath) # => "01234" * ``` * * Pads with null characters if necessary: * * ```ruby * File.truncate(filepath, 10) * File.read(filepath) # => "01234\u0000\u0000\u0000\u0000\u0000" * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_file_s_truncate(VALUE klass, VALUE path, VALUE len) { struct truncate_arg ta; int r; ta.pos = NUM2OFFT(len); FilePathValue(path); path = rb_str_encode_ospath(path); ta.path = StringValueCStr(path); r = IO_WITHOUT_GVL_INT(nogvl_truncate, &ta); if (r < 0) rb_sys_fail_path(path); return INT2FIX(0); } #else #define rb_file_s_truncate rb_f_notimplement #endif #if defined(HAVE_FTRUNCATE) struct ftruncate_arg { int fd; rb_off_t pos; }; static VALUE nogvl_ftruncate(void *ptr) { struct ftruncate_arg *fa = ptr; return (VALUE)ftruncate(fa->fd, fa->pos); } /* * :markup: markdown * * call-seq: * truncate(size) -> 0 * * Adjusts the size of `self` to the given `size`, * regardless of the current [position](rdoc-ref:IO@Position); * does not adjust the position: * * ```ruby * filepath = '/tmp/t.tmp' * file = File.new(filepath, 'w+') * file.write('0123456789') * file.truncate(5) * file.pos # => 10 * file.rewind * file.read # => "01234" * ``` * * Pads with null characters if necessary: * * ```ruby * file.truncate(10) * file.pos # => 5 * file.rewind * file.read # => "01234\u0000\u0000\u0000\u0000\u0000" * # Clean up. * file.close * File.delete(filepath) * ``` * */ static VALUE rb_file_truncate(VALUE obj, VALUE len) { rb_io_t *fptr; struct ftruncate_arg fa; fa.pos = NUM2OFFT(len); GetOpenFile(obj, fptr); if (!(fptr->mode & FMODE_WRITABLE)) { rb_raise(rb_eIOError, "not opened for writing"); } rb_io_flush_raw(obj, 0); fa.fd = fptr->fd; if ((int)rb_io_blocking_region(fptr, nogvl_ftruncate, &fa) < 0) { rb_sys_fail_path(fptr->pathv); } return INT2FIX(0); } #else #define rb_file_truncate rb_f_notimplement #endif # ifndef LOCK_SH # define LOCK_SH 1 # endif # ifndef LOCK_EX # define LOCK_EX 2 # endif # ifndef LOCK_NB # define LOCK_NB 4 # endif # ifndef LOCK_UN # define LOCK_UN 8 # endif #ifdef __CYGWIN__ #include #endif static VALUE rb_thread_flock(void *data) { #ifdef __CYGWIN__ int old_errno = errno; #endif int *op = data, ret = flock(op[0], op[1]); #ifdef __CYGWIN__ if (GetLastError() == ERROR_NOT_LOCKED) { ret = 0; errno = old_errno; } #endif return (VALUE)ret; } /* :markup: markdown * * call-seq: * flock(locking_constant) -> 0 or false * * Locks or unlocks file `self` according to the given `locking_constant`, * a bitwise OR of the values in the table below. * * Not available on all platforms. * * Returns `false` if `File::LOCK_NB` is specified and the operation would have blocked; * otherwise returns `0`. * * | Constant | Lock | Effect * |-----------------|--------------|-----------------------------------------------------------------------------------------------------------------| * | `File::LOCK_EX` | Exclusive | Only one process may hold an exclusive lock for `self` at a time. | * | `File::LOCK_NB` | Non-blocking | No blocking; may be combined with `File::LOCK_SH` or `File::LOCK_EX` using the bitwise OR operator \|. | * | `File::LOCK_SH` | Shared | Multiple processes may each hold a shared lock for `self` at the same time. | * | `File::LOCK_UN` | Unlock | Remove an existing lock held by this process. | * * Example: * * ```ruby * # Update a counter using an exclusive lock. * # Don't use File::WRONLY because it truncates the file. * File.open('counter', File::RDWR | File::CREAT, 0644) do |f| * f.flock(File::LOCK_EX) * value = f.read.to_i + 1 * f.rewind * f.write("#{value}\n") * f.flush * f.truncate(f.pos) * end * * # Read the counter using a shared lock. * File.open('counter', 'r') do |f| * f.flock(File::LOCK_SH) * f.read * end * ``` * */ static VALUE rb_file_flock(VALUE obj, VALUE operation) { rb_io_t *fptr; int op[2], op1; struct timeval time; op[1] = op1 = NUM2INT(operation); GetOpenFile(obj, fptr); op[0] = fptr->fd; if (fptr->mode & FMODE_WRITABLE) { rb_io_flush_raw(obj, 0); } while ((int)rb_io_blocking_region(fptr, rb_thread_flock, op) < 0) { int e = errno; switch (e) { case EAGAIN: case EACCES: #if defined(EWOULDBLOCK) && EWOULDBLOCK != EAGAIN case EWOULDBLOCK: #endif if (op1 & LOCK_NB) return Qfalse; time.tv_sec = 0; time.tv_usec = 100 * 1000; /* 0.1 sec */ rb_thread_wait_for(time); rb_io_check_closed(fptr); continue; case EINTR: #if defined(ERESTART) case ERESTART: #endif break; default: rb_syserr_fail_path(e, fptr->pathv); } } return INT2FIX(0); } static void test_check(int n, int argc, VALUE *argv) { int i; n+=1; rb_check_arity(argc, n, n); for (i=1; i object * * Performs a test on one or both of the filesystem entities at the given paths * `path0` and `path1`: * * - Each path `path0` or `path1` points to a file, directory, device, pipe, etc. * - Character `char` selects a specific test. * * The tests: * * - Each of these tests operates only on the entity at `path0`, * and returns `true` or `false`; * for a non-existent entity, returns `false` (does not raise exception): * * | Character | Test | * |:------------:|:--------------------------------------------------------------------------| * | 'b' | Whether the entity is a block device. | * | 'c' | Whether the entity is a character device. | * | 'd' | Whether the entity is a directory. | * | 'e' | Whether the entity is an existing entity. | * | 'f' | Whether the entity is an existing regular file. | * | 'g' | Whether the entity's setgid bit is set. | * | 'G' | Whether the entity's group ownership is equal to the caller's. | * | 'k' | Whether the entity's sticky bit is set. | * | 'l' | Whether the entity is a symbolic link. | * | 'o' | Whether the entity is owned by the caller's effective uid. | * | 'O' | Like 'o', but uses the real uid (not the effective uid). | * | 'p' | Whether the entity is a FIFO device (named pipe). | * | 'r' | Whether the entity is readable by the caller's effective uid/gid. | * | 'R' | Like 'r', but uses the real uid/gid (not the effective uid/gid). | * | 'S' | Whether the entity is a socket. | * | 'u' | Whether the entity's setuid bit is set. | * | 'w' | Whether the entity is writable by the caller's effective uid/gid. | * | 'W' | Like 'w', but uses the real uid/gid (not the effective uid/gid). | * | 'x' | Whether the entity is executable by the caller's effective uid/gid. | * | 'X' | Like 'x', but uses the real uid/gid (not the effective uid/git). | * | 'z' | Whether the entity exists and is of length zero. | * * - This test operates only on the entity at `path0`, * and returns an integer size or `nil`: * * | Character | Test | * |:------------:|:---------------------------------------------------------------------------------------------| * | 's' | Returns positive integer size if the entity exists and has non-zero length, `nil` otherwise. | * * - Each of these tests operates only on the entity at `path0`, * and returns a Time object; * raises an exception if the entity does not exist: * * | Character | Test | * |:------------:|:---------------------------------------| * | 'A' | Last access time for the entity. | * | 'C' | Last change time for the entity. | * | 'M' | Last modification time for the entity. | * * - Each of these tests operates on the modification time (`mtime`) * of each of the entities at `path0` and `path1`, * and returns a `true` or `false`; * returns `false` if either entity does not exist: * * | Character | Test | * |:------------:|:----------------------------------------------------------------| * | '<' | Whether the `mtime` at `path0` is less than that at `path1`. | * | '=' | Whether the `mtime` at `path0` is equal to that at `path1`. | * | '>' | Whether the `mtime` at `path0` is greater than that at `path1`. | * * - This test operates on the content of each of the entities at `path0` and `path1`, * and returns a `true` or `false`; * returns `false` if either entity does not exist: * * | Character | Test | * |:------------:|:----------------------------------------------| * | '-' | Whether the entities exist and are identical. | * */ static VALUE rb_f_test(int argc, VALUE *argv, VALUE _) { int cmd; if (argc == 0) rb_check_arity(argc, 2, 3); cmd = NUM2CHR(argv[0]); if (cmd == 0) { goto unknown; } if (strchr("bcdefgGkloOprRsSuwWxXz", cmd)) { CHECK(1); switch (cmd) { case 'b': return rb_file_blockdev_p(0, argv[1]); case 'c': return rb_file_chardev_p(0, argv[1]); case 'd': return rb_file_directory_p(0, argv[1]); case 'e': return rb_file_exist_p(0, argv[1]); case 'f': return rb_file_file_p(0, argv[1]); case 'g': return rb_file_sgid_p(0, argv[1]); case 'G': return rb_file_grpowned_p(0, argv[1]); case 'k': return rb_file_sticky_p(0, argv[1]); case 'l': return rb_file_symlink_p(0, argv[1]); case 'o': return rb_file_owned_p(0, argv[1]); case 'O': return rb_file_rowned_p(0, argv[1]); case 'p': return rb_file_pipe_p(0, argv[1]); case 'r': return rb_file_readable_p(0, argv[1]); case 'R': return rb_file_readable_real_p(0, argv[1]); case 's': return rb_file_size_p(0, argv[1]); case 'S': return rb_file_socket_p(0, argv[1]); case 'u': return rb_file_suid_p(0, argv[1]); case 'w': return rb_file_writable_p(0, argv[1]); case 'W': return rb_file_writable_real_p(0, argv[1]); case 'x': return rb_file_executable_p(0, argv[1]); case 'X': return rb_file_executable_real_p(0, argv[1]); case 'z': return rb_file_zero_p(0, argv[1]); } } if (strchr("MAC", cmd)) { struct stat st; VALUE fname = argv[1]; CHECK(1); if (rb_stat(fname, &st) == -1) { int e = errno; FilePathValue(fname); rb_syserr_fail_path(e, fname); } switch (cmd) { case 'A': return stat_atime(&st); case 'M': return stat_mtime(&st); case 'C': return stat_ctime(&st); } } if (cmd == '-') { CHECK(2); return rb_file_identical_p(0, argv[1], argv[2]); } if (strchr("=<>", cmd)) { struct stat st1, st2; stat_timestamp t1, t2; CHECK(2); if (rb_stat(argv[1], &st1) < 0) return Qfalse; if (rb_stat(argv[2], &st2) < 0) return Qfalse; t1 = stat_mtimespec(&st1); t2 = stat_mtimespec(&st2); switch (cmd) { case '=': if (t1.tv_sec == t2.tv_sec && t1.tv_nsec == t2.tv_nsec) return Qtrue; return Qfalse; case '>': if (t1.tv_sec > t2.tv_sec) return Qtrue; if (t1.tv_sec == t2.tv_sec && t1.tv_nsec > t2.tv_nsec) return Qtrue; return Qfalse; case '<': if (t1.tv_sec < t2.tv_sec) return Qtrue; if (t1.tv_sec == t2.tv_sec && t1.tv_nsec < t2.tv_nsec) return Qtrue; return Qfalse; } } unknown: /* unknown command */ if (ISPRINT(cmd)) { rb_raise(rb_eArgError, "unknown command '%s%c'", cmd == '\'' || cmd == '\\' ? "\\" : "", cmd); } else { rb_raise(rb_eArgError, "unknown command \"\\x%02X\"", cmd); } UNREACHABLE_RETURN(Qundef); } /* * Document-class: File::Stat * * :markup: markdown * * A \File::Stat object contains information about an entry in the filesystem. * * Each of these methods returns a new \File::Stat object. * the first three follow symbolic links; the others don't: * * - File::Stat.new * - File::stat * - IO#stat * - File#lstat * - File::lstat * * ## Snapshot * * A new \File::Stat object takes an immediate "snapshot" of the filesystem entry * at the given 'path'; * the snapshot is never updated, regardless of changes in the entry (even its deletion): * * ```ruby * filepath = '/tmp/t.tmp' * File.stat(filepath) # Raises Errno::ENOENT: No such file or directory. * File.write(filepath, 'foo') * stat = File.stat(filepath) * stat.birthtime # => 2026-10-03 12:19:23.723062465 -0500 * File.delete(filepath) * stat.birthtime # => 2026-10-03 12:19:23.723062465 -0500 * ``` * * ## Filesystem Dependencies * * Methods in a \File::Stat object may return filesystem-dependent values, * and not all values are meaningful on all filesystems; * for example, File::Stat#blocks returns `nil` on a Windows filesystem, * but returns an integer on others. * * See also Kernel#test. */ static VALUE rb_stat_s_alloc(VALUE klass) { VALUE obj; stat_alloc(klass, &obj); return obj; } /* * :markup: markdown * * call-seq: * File::Stat.new(path) -> stat * * Returns a new \File::Stat object containing a [snapshot](rdoc-ref:File::Stat@Snapshot) * of the filesystem entry at the given `path`: * * ```ruby * File::Stat.new('/etc/passwd') * File::Stat.new('/tmp') * File::Stat.new('nosuch') # Raises Errno::ENOENT: No such file or directory. * ``` */ static VALUE rb_stat_init(VALUE obj, VALUE fname) { rb_io_stat_data st; FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (STATX(StringValueCStr(fname), &st, STATX_ALL) == -1) { rb_sys_fail_path(fname); } struct rb_stat *rb_st; TypedData_Get_Struct(obj, struct rb_stat, &stat_data_type, rb_st); rb_st->stat = st; rb_st->initialized = true; return Qnil; } /* :nodoc: */ static VALUE rb_stat_init_copy(VALUE copy, VALUE orig) { if (!OBJ_INIT_COPY(copy, orig)) return copy; struct rb_stat *orig_rb_st; TypedData_Get_Struct(orig, struct rb_stat, &stat_data_type, orig_rb_st); struct rb_stat *copy_rb_st; TypedData_Get_Struct(copy, struct rb_stat, &stat_data_type, copy_rb_st); *copy_rb_st = *orig_rb_st; return copy; } /* * :markup: markdown * * call-seq: * ftype -> string * * Returns the string type of the path in the [snapshot](rdoc-ref:File::Stat@Snapshot) * in `self`, one of: * * - `'file'`. * - `'directory'`. * - `'characterSpecial'`. * - `'blockSpecial'`. * - `'fifo'`. * - `'link'`. * - `'socket'`. * * Examples: * * ```ruby * File.stat('/etc/passwd').ftype # => "file" * File.stat('/etc').ftype # => "directory" * File.stat('/dev/null').ftype # => "characterSpecial" * File.stat('/dev/loop0').ftype # => "blockSpecial" * * File.mkfifo('/tmp/pipe', 0o666) * File.stat('/tmp/pipe').ftype # => "fifo" * * File.symlink('/etc/passwd', '/tmp/link') * File.lstat('/tmp/link').ftype # => "link" * * require 'socket' * UNIXServer.new('/tmp/socket') * File.stat('/tmp/socket').ftype # => "socket" * * File.delete('/tmp/link', '/tmp/pipe', '/tmp/socket') # Clean up. * ``` * * Returns `'unknown'` if the type cannot be determined. */ static VALUE rb_stat_ftype(VALUE obj) { return rb_file_ftype(get_stat(obj)->ST_(mode)); } /* * :markup: markdown * * call-seq: * directory? -> true or false * * Returns whether the entry in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self` * is a directory: * * ```ruby * File.stat('/etc').directory? # => true * File.stat('/etc/passwd').directory? # => false * ``` * */ static VALUE rb_stat_d(VALUE obj) { if (S_ISDIR(get_stat(obj)->ST_(mode))) return Qtrue; return Qfalse; } /* * :markup: markdown * * call-seq: * pipe? -> true or false * * Returns whether the entry at the path in `self` is a pipe: * * ```ruby * pipepath = '/tmp/pipe' * File.mkfifo(pipepath) # Make pipe. * stat = File.stat(pipepath) # Take snapshot. * stat.pipe? # => true # In snapshot. * File.delete(pipepath) # Clean up. * stat.pipe? # => true # Snapshot not updated. * File.stat('/etc').pipe? # => false * File.stat('/etc/passwd').pipe? # => false * ``` * */ static VALUE rb_stat_p(VALUE obj) { #ifdef S_IFIFO if (S_ISFIFO(get_stat(obj)->ST_(mode))) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * symlink? -> true or false * * Returns whether the entry in `self` (see [Snapshot](rdoc-ref:File::Stat@Snapshot)) * is a [symbolic link](rdoc-ref:file/symbolic_links.md): * * ```ruby * filepath = '/etc/passwd' * linkpath = '/tmp/foo' * File.symlink(filepath, linkpath) * File.stat(filepath).symlink? # => false * File.lstat(filepath).symlink? # => false * stat = File.stat(linkpath) # Snapshot with stat follows link. * stat.symlink? # => false * lstat = File.lstat(linkpath) # Snapshot with lstat does not follow link. * lstat.symlink? # => true * File.delete(linkpath) # Clean up. * # Snapshots are unchanged, even when link deleted. * stat.symlink? # => false * lstat.symlink? # => true * ``` * */ static VALUE rb_stat_l(VALUE obj) { #ifdef S_ISLNK if (S_ISLNK(get_stat(obj)->ST_(mode))) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * socket? -> true or false * * Returns whether entry in the [snapshot](rdoc-ref:File::Stat@Snapshot) * in `self` is a socket: * * ```ruby * require 'socket' * socket_path = '/tmp/socket' * server = UNIXServer.new(socket_path) * stat = File.stat(socket_path) # Take snapshot. * stat.socket? # => true * server.close # Clean up. * File.delete(socket_path) # Clean up. * stat.socket? # => true # Snapshot not updated. * File.stat('/tmp').socket? # => false # Not a socket. * ``` * */ static VALUE rb_stat_S(VALUE obj) { #ifdef S_ISSOCK if (S_ISSOCK(get_stat(obj)->ST_(mode))) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * blockdev? -> true or false * * Returns whether the entry in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self` * is a block device (i.e., a direct-access device): * * ```ruby * File.stat('/dev/nvme0n1').blockdev? # => true * File.stat('/dev/loop0').blockdev? # => true * File.stat('/dev/tty').blockdev? # => false * File.stat('/dev/null').blockdev? # => false * ``` * * The returned value is filesystem-dependent; returns `false` on Windows or MacOS. * */ static VALUE rb_stat_b(VALUE obj) { #ifdef S_ISBLK if (S_ISBLK(get_stat(obj)->ST_(mode))) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * chardev? -> true or false * * Returns whether the entry in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self` * is a character device (i.e., a sequential-access device): * * ```ruby * File.stat('/dev/tty').chardev? # => true * File.stat('/dev/null').chardev? # => true * File.stat('/dev/nvme0n1').chardev? # => false * File.stat('/dev/loop0').chardev? # => false * ``` * * The returned value is filesystem-dependent; on Windows, always `false`. */ static VALUE rb_stat_c(VALUE obj) { if (S_ISCHR(get_stat(obj)->ST_(mode))) return Qtrue; return Qfalse; } /* * :markup: markdown * * call-seq: * owned? -> true or false * * Returns whether the owner in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self` * is the owner of the current process: * * ```ruby * dirpath = '/tmp/dir' * Dir.mkdir(dirpath) * filepath = File.join(dirpath, 't.tmp') # => "/tmp/dir/t.tmp" * File.write(filepath, 'foo') * dirstat = File.stat(dirpath) # Snapshot of directory. * filestat = File.stat(filepath) # Snapshot of file. * dirstat.owned? # => true * filestat.owned? # => true * FileUtils.rm_rf(dirpath) # Clean up. * dirstat.owned? # => true # Snapshot not updated. * filestat.owned? # => true # Snapshot not updated. * ``` * */ static VALUE rb_stat_owned(VALUE obj) { if (get_stat(obj)->ST_(uid) == geteuid()) return Qtrue; return Qfalse; } static VALUE rb_stat_rowned(VALUE obj) { if (get_stat(obj)->ST_(uid) == getuid()) return Qtrue; return Qfalse; } /* * :markup: markdown * * call-seq: * grpowned?(path) -> true or false * * Returns `false` on Windows. * * On other systems, returns whether the effective group id of the calling process * is the owner of the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self`: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.stat(filepath).grpowned? # => true * File.stat('/etc').grpowned? # => false * File.stat('/etc/passwd').grpowned? # => false * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_stat_grpowned(VALUE obj) { #ifndef _WIN32 if (rb_group_member(get_stat(obj)->ST_(gid))) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * readable? -> true or false * * Returns whether the entry represented by `self` * exists and is readable by the owner and group of the current process; * see [Permissions](rdoc-ref:file/filesystem_modes.md@Permissions): * * ```ruby * path = '/tmp/secret.txt' * File.write(path, 'foo') * File.stat(path).readable? # => true * File.chmod(0o000, path) * File.stat(path).readable? # => false * File.delete(path) # Clean up. * ``` * */ static VALUE rb_stat_r(VALUE obj) { rb_io_stat_data *st = get_stat(obj); #ifdef USE_GETEUID if (geteuid() == 0) return Qtrue; #endif #ifdef S_IRUSR if (rb_stat_owned(obj)) return RBOOL(st->ST_(mode) & S_IRUSR); #endif #ifdef S_IRGRP if (rb_stat_grpowned(obj)) return RBOOL(st->ST_(mode) & S_IRGRP); #endif #ifdef S_IROTH if (!(st->ST_(mode) & S_IROTH)) return Qfalse; #endif return Qtrue; } /* * :markup: markdown * * call-seq: * stat.readable_real? -> true or false * * Like #readable?, but checks against the real owner and group ids * instead of the effective ids. */ static VALUE rb_stat_R(VALUE obj) { rb_io_stat_data *st = get_stat(obj); #ifdef USE_GETEUID if (getuid() == 0) return Qtrue; #endif #ifdef S_IRUSR if (rb_stat_rowned(obj)) return RBOOL(st->ST_(mode) & S_IRUSR); #endif #ifdef S_IRGRP if (rb_group_member(get_stat(obj)->ST_(gid))) return RBOOL(st->ST_(mode) & S_IRGRP); #endif #ifdef S_IROTH if (!(st->ST_(mode) & S_IROTH)) return Qfalse; #endif return Qtrue; } /* * :markup: markdown * * call-seq: * world_readable? -> integer or nil * * Returns the integer [permissions](rdoc-ref:file/filesystem_modes.md@Permissions) * for the entry in the [snapshot](rdoc-ref:File::Stat@Snapshot) in `self` * if those permissions allow reading by others; * otherwise, returns `nil`: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') # Create file. * File.chmod(0o000, filepath) # Make file unreadable. * stat0 = File.stat(filepath) # Take snapshot. * stat0.world_readable? # => nil # Snapshot shows not world-readable. * File.chmod(0o644, filepath) # Make file world-readable. * stat0.world_readable? # => nil # Snapshot not updated. * stat1 = File.stat(filepath) # Take new snapshot. * stat1.world_readable?.to_s(8) # => "644" # Snapshot shows world-readable. * File.delete(filepath) # Clean up. * stat1.world_readable?.to_s(8) # => "644" # Snapshot not updated. * ``` */ static VALUE rb_stat_wr(VALUE obj) { #ifdef S_IROTH rb_io_stat_data *st = get_stat(obj); if ((st->ST_(mode) & (S_IROTH)) == S_IROTH) { return UINT2NUM(st->ST_(mode) & (S_IRUGO|S_IWUGO|S_IXUGO)); } #endif return Qnil; } /* * :markup: markdown * call-seq: * writable? -> true or false * * Returns whether the entry at the path in `self` exists and is writable * by the effective owner and group in the current process: * * ```ruby * filepath = '/tmp/secret.txt' * File.write(filepath, 'foo') * File.stat(filepath).writable? # => true # Writable. * File.chmod(0o000, filepath) # Make non-writable. * File.stat(filepath).writable? # => false # Not writable. * File.delete(filepath) # Clean up. * File.stat('/etc').writable? # => false # Directory. * ``` * * Note that filesystem security features may cause this method to return `true` * even when the file is not writable by the effective owner and group. */ static VALUE rb_stat_w(VALUE obj) { rb_io_stat_data *st = get_stat(obj); #ifdef USE_GETEUID if (geteuid() == 0) return Qtrue; #endif #ifdef S_IWUSR if (rb_stat_owned(obj)) return RBOOL(st->ST_(mode) & S_IWUSR); #endif #ifdef S_IWGRP if (rb_stat_grpowned(obj)) return RBOOL(st->ST_(mode) & S_IWGRP); #endif #ifdef S_IWOTH if (!(st->ST_(mode) & S_IWOTH)) return Qfalse; #endif return Qtrue; } /* * :markup: markdown * * call-seq: * writable_real? -> true or false * * Like File::Stat.writable?, but checks against the real owner and group * instead of the effective owner and group. * * Note that filesystem security features may cause this method to return `true` * even when the entry in `self` is not writable by the real owner and group. */ static VALUE rb_stat_W(VALUE obj) { rb_io_stat_data *st = get_stat(obj); #ifdef USE_GETEUID if (getuid() == 0) return Qtrue; #endif #ifdef S_IWUSR if (rb_stat_rowned(obj)) return RBOOL(st->ST_(mode) & S_IWUSR); #endif #ifdef S_IWGRP if (rb_group_member(get_stat(obj)->ST_(gid))) return RBOOL(st->ST_(mode) & S_IWGRP); #endif #ifdef S_IWOTH if (!(st->ST_(mode) & S_IWOTH)) return Qfalse; #endif return Qtrue; } /* * :markup: markdown * call-seq: * world_writable? -> integer or nil * * If the entry in `self` exists and is writable by others, * returns the integer [permissions](rdoc-ref:file/filesystem_modes.md@Permissions) * for the entry; * otherwise, returns `nil`: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.stat(filepath).world_writable? # => nil # Not world-writable. * File.chmod(0o777, filepath) # Make world-writable. * File.stat(filepath).world_writable?.to_s(8) # => "777" # World-writable. * File.delete(filepath) # Clean up. * File.stat('/tmp').world_writable?.to_s(8) # => "777" # Directory. * ``` * */ static VALUE rb_stat_ww(VALUE obj) { #ifdef S_IWOTH rb_io_stat_data *st = get_stat(obj); if ((st->ST_(mode) & (S_IWOTH)) == S_IWOTH) { return UINT2NUM(st->ST_(mode) & (S_IRUGO|S_IWUGO|S_IXUGO)); } #endif return Qnil; } /* * :markup: markdown * * call-seq: * executable? -> true or false * * Returns whether the filesystem entry represented by `self` * is [executable](rdoc-ref:file/filesystem_modes.md@Executable+Files) * by the effective owner/group of the current process: * * ```ruby * File.stat('/bin/ruby').executable? # => true * File.stat('/etc').executable? # => true * File.stat('/etc/passwd').executable? # => false * ``` * * Raises Errno::ENOENT if the entry does not exist. * * Note that some filesystem settings may cause this method to return `true` * even though the entry is not executable by the effective owner/group. */ static VALUE rb_stat_x(VALUE obj) { rb_io_stat_data *st = get_stat(obj); #ifdef USE_GETEUID if (geteuid() == 0) { return RBOOL(st->ST_(mode) & S_IXUGO); } #endif #ifdef S_IXUSR if (rb_stat_owned(obj)) return RBOOL(st->ST_(mode) & S_IXUSR); #endif #ifdef S_IXGRP if (rb_stat_grpowned(obj)) return RBOOL(st->ST_(mode) & S_IXGRP); #endif #ifdef S_IXOTH if (!(st->ST_(mode) & S_IXOTH)) return Qfalse; #endif return Qtrue; } /* * :markup: markdown * call-seq: * executable_real? -> true or false * * Like Pathname#executable?, but checks against the real owner/group * instead of the effective owner/group. */ static VALUE rb_stat_X(VALUE obj) { rb_io_stat_data *st = get_stat(obj); #ifdef USE_GETEUID if (getuid() == 0) { return RBOOL(st->ST_(mode) & S_IXUGO); } #endif #ifdef S_IXUSR if (rb_stat_rowned(obj)) return RBOOL(st->ST_(mode) & S_IXUSR); #endif #ifdef S_IXGRP if (rb_group_member(get_stat(obj)->ST_(gid))) return RBOOL(st->ST_(mode) & S_IXGRP); #endif #ifdef S_IXOTH if (!(st->ST_(mode) & S_IXOTH)) return Qfalse; #endif return Qtrue; } /* * :markup: markdown * * call-seq: * file? -> true or false * * Returns whether `self` represents a filesystem entry that exists and is a regular file; * see File::Stat.ftype: * * ```ruby * File.stat('/etc/passwd').file? # => true * File.stat('/etc').file? # => false * ``` * */ static VALUE rb_stat_f(VALUE obj) { if (S_ISREG(get_stat(obj)->ST_(mode))) return Qtrue; return Qfalse; } /* * :markup: markdown * * call-seq: * zero? -> true or false * * Returns whether the entry at the path in `self` has size zero. * * The entry may be a file: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.stat(filepath).zero? # => false * File.truncate(filepath, 0) * File.stat(filepath).zero? # => true * File.delete(filepath) # Clean up. * ``` * * The entry may be a directory: * * ```ruby * dirpath = '/tmp/foo' * Dir.mkdir(dirpath) * stat = File.stat(dirpath) * # Size is filesystem-dependent; may or may not be zero. * stat.size # => 4096 * stat.zero? # => false * filepath = File.join(dirpath, 't.tmp') # => "/tmp/foo/t.tmp" * File.write(filepath, 'foo') * stat = File.stat(dirpath) * stat.size # => 4096 * stat.zero? # => false * FileUtils.rm_rf(dirpath) # Clean up. * ``` * */ static VALUE rb_stat_z(VALUE obj) { if (get_stat(obj)->ST_(size) == 0) return Qtrue; return Qfalse; } /* * :markup: markdown * * call-seq: * size? -> integer or nil * * Returns the size in bytes of the entry in `self` * if the entry exists and has non-zero size, `nil` otherwise: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * File.size(filepath) # => 3 * stat = File.stat(filepath) # Take snapshot. * stat.size? # => 3 # Non-zero size. * File.write(filepath, '') * File.size(filepath) # => 0 * stat.size? # => 3 # Snapshot unchanged. * stat = File.stat(filepath) # Take new snapshot. * stat.size? # => nil # Zero size * File.delete(filepath) # Clean up. * ``` * */ static VALUE rb_stat_s(VALUE obj) { rb_off_t size = get_stat(obj)->ST_(size); if (size == 0) return Qnil; return OFFT2NUM(size); } /* * :markup: markdown * * call-seq: * setuid? -> true or false * * Returns whether the setuid bit is set * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits) * for the entry represented in `self`: * * ```ruby * path = '/tmp/t.tmp' * File.write(path, 'foo') * stat = File.stat(path) # Take snapshot; bit not set. * stat.setuid? # => false * stat.mode.to_s(8) # => "100664" * File.chmod(0o4644, path) # Set the bit; snapshot not updated. * stat.setuid? # => false * stat.mode.to_s(8) # => "100664" * stat = File.stat(path) # Fresh snapshot. * stat.setuid? # => true * stat.mode.to_s(8) # => "104644" * File.delete(path) # Clean up. * ``` * * On Windows, the bit is never set; the method always returns `false`. */ static VALUE rb_stat_suid(VALUE obj) { #ifdef S_ISUID if (get_stat(obj)->ST_(mode) & S_ISUID) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * * call-seq: * setgid? -> true or false * * Returns whether the setgid bit is set * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits) * for the entry represented in `self`: * * ```ruby * path = '/tmp/t.tmp' * File.write(path, 'foo') * stat = File.stat(path) # Take a snapshot. * stat.setgid? # => false * stat.mode.to_s(8) # => "100664" * File.chmod(0o2644, path) # Set the bit; stat snapshot unchanged. * stat.setgid? # => false * stat.mode.to_s(8) # => "100664" * stat = File.stat(path) # Fresh stat; snapshot changed. * stat.setgid? # => true * stat.mode.to_s(8) # => "102644" * File.delete(path) # Clean up. * ``` * * On Windows, the bit is never set; the method always returns `false`. */ static VALUE rb_stat_sgid(VALUE obj) { #ifdef S_ISGID if (get_stat(obj)->ST_(mode) & S_ISGID) return Qtrue; #endif return Qfalse; } /* * :markup: markdown * call-seq: * sticky? -> true or false * * Returns whether the sticky bit is set * in the [special bits](rdoc-ref:file/filesystem_modes.md@Special+Bits) * for `self`: * * ```ruby * filepath = '/tmp/t.tmp' * File.write(filepath, 'foo') * stat = File.stat(filepath) * stat.sticky? # => false * stat.mode.to_s(8) # => "100664" * File.chmod(01644, filepath) # => 1 # Stat unchanged. * stat.sticky? # => false * stat.mode.to_s(8) # => "100664" * stat = File.stat(filepath) # Fresh stat. * stat.sticky? # => true * stat.mode.to_s(8) # => "101644" * File.delete(filepath) # Clean up. * ``` * * Returns `false` on Windows. */ static VALUE rb_stat_sticky(VALUE obj) { #ifdef S_ISVTX if (get_stat(obj)->ST_(mode) & S_ISVTX) return Qtrue; #endif return Qfalse; } #if !defined HAVE_MKFIFO && defined HAVE_MKNOD && defined S_IFIFO #define mkfifo(path, mode) mknod(path, (mode)&~S_IFMT|S_IFIFO, 0) #define HAVE_MKFIFO #endif #ifdef HAVE_MKFIFO struct mkfifo_arg { const char *path; mode_t mode; }; static void * nogvl_mkfifo(void *ptr) { struct mkfifo_arg *ma = ptr; return (void *)(VALUE)mkfifo(ma->path, ma->mode); } /* * :markup: markdown * * call-seq: * File.mkfifo(path, mode = 0666) -> 0 * * Creates a FIFO special file at the given `path`, * with the permissions given by `mode`; * see [Filesystem Modes](rdoc-ref:file/filesystem_modes.md): * * ```ruby * path = '/tmp/pipe' * File.mkfifo(path) * File.pipe?(path) # => true * File.ftype(path) # => "fifo" * File.unlink(path) * ``` * * Not implemented on Windows. */ static VALUE rb_file_s_mkfifo(int argc, VALUE *argv, VALUE _) { VALUE path; struct mkfifo_arg ma; ma.mode = 0666; rb_check_arity(argc, 1, 2); if (argc > 1) { ma.mode = NUM2MODET(argv[1]); } path = argv[0]; FilePathValue(path); path = rb_str_encode_ospath(path); ma.path = RSTRING_PTR(path); if (IO_WITHOUT_GVL(nogvl_mkfifo, &ma)) { rb_sys_fail_path(path); } return INT2FIX(0); } #else #define rb_file_s_mkfifo rb_f_notimplement #endif static VALUE rb_mFConst; void rb_file_const(const char *name, VALUE value) { rb_define_const(rb_mFConst, name, value); } int rb_is_absolute_path(const char *path) { #ifdef DOSISH_DRIVE_LETTER if (has_drive_letter(path) && isdirsep(path[2])) return 1; #endif #ifdef DOSISH_UNC if (isdirsep(path[0]) && isdirsep(path[1])) return 1; #endif #ifndef DOSISH if (path[0] == '/') return 1; #endif return 0; } int ruby_is_fd_loadable(int fd) { #ifdef _WIN32 return 1; #else struct stat st; if (fstat(fd, &st) < 0) return 0; if (S_ISREG(st.st_mode)) return 1; if (S_ISFIFO(st.st_mode) || S_ISCHR(st.st_mode)) return -1; if (S_ISDIR(st.st_mode)) errno = EISDIR; else errno = ENXIO; return 0; #endif } #ifndef _WIN32 int rb_file_load_ok(const char *path) { int ret = 1; /* open(2) may block if path is FIFO and it's empty. Let's use O_NONBLOCK. FIXME: Why O_NDELAY is checked? */ int mode = (O_RDONLY | #if defined O_NONBLOCK O_NONBLOCK | #elif defined O_NDELAY O_NDELAY | #endif 0); int fd = rb_cloexec_open(path, mode, 0); if (fd < 0) { if (!rb_gc_for_fd(errno)) return 0; fd = rb_cloexec_open(path, mode, 0); if (fd < 0) return 0; } rb_update_max_fd(fd); ret = ruby_is_fd_loadable(fd); (void)close(fd); return ret; } #endif static int is_explicit_relative(const char *path) { if (*path++ != '.') return 0; if (*path == '.') path++; return isdirsep(*path); } static VALUE copy_path_class(VALUE path, VALUE orig) { int encidx = rb_enc_get_index(orig); if (encidx == ENCINDEX_ASCII_8BIT || encidx == ENCINDEX_US_ASCII) encidx = rb_filesystem_encindex(); rb_enc_associate_index(path, encidx); str_shrink(path); RBASIC_SET_CLASS(path, rb_obj_class(orig)); OBJ_FREEZE(path); return path; } static bool nav_component_p(const char *s, const char *send) { if ((send - s) >= 2 && s[0] == '.') { return s[1] == '.' || isdirsep(s[1]); } return false; } static bool fname_need_expansion_p(VALUE fname) { const char *s = RSTRING_PTR(fname); const rb_len_t len = RSTRING_LEN(fname); const char *send = s + len; if (nav_component_p(s, send)) { return true; } rb_encoding *enc = rb_str_enc_get(fname); bool mbenc = enc_mbclen_needed(enc); s = enc_path_next(s, send, mbenc, enc); while (s < send) { if (nav_component_p(s, send)) { return true; } s++; s = enc_path_next(s, send, mbenc, enc); } return false; } static bool expand_feature(VALUE fname, VALUE dname, VALUE buffer, bool need_expansion) { rb_len_t dname_len = RSTRING_LEN(dname); const char *dname_ptr = RSTRING_PTR(dname); RUBY_ASSERT(dname_len > 0); if (need_expansion || dname_ptr[0] == '~') { rb_file_expand_path_internal(fname, dname, 0, 0, buffer); } else { rb_str_set_len(buffer, 0); rb_str_append(buffer, dname); if (!isdirsep(dname_ptr[dname_len - 1])) { rb_str_cat(buffer, "/", 1); } rb_str_append(buffer, fname); } return true; } int rb_find_file_ext(VALUE *filep, const char *const *ext) { const char *f = StringValueCStr(*filep); VALUE fname = *filep; rb_len_t i, j, fnlen; int expanded = 0; if (!ext[0]) return 0; if (f[0] == '~') { fname = file_expand_path_1(fname, DLEXT_MAXLEN); f = RSTRING_PTR(fname); *filep = fname; expanded = 1; } if (expanded || rb_is_absolute_path(f) || is_explicit_relative(f)) { if (!expanded) fname = file_expand_path_1(fname, DLEXT_MAXLEN); fnlen = RSTRING_LEN(fname); for (i=0; ext[i]; i++) { rb_str_cat2(fname, ext[i]); if (rb_file_load_ok(RSTRING_PTR(fname))) { *filep = copy_path_class(fname, *filep); return (int)(i+1); } rb_str_set_len(fname, fnlen); } return 0; } rb_len_t expanded_load_path_maxlen; VALUE load_path = rb_get_expanded_load_path(&expanded_load_path_maxlen); if (!load_path) return 0; fname = rb_str_dup(*filep); RBASIC_CLEAR_CLASS(fname); fnlen = RSTRING_LEN(fname); bool need_expansion = fname_need_expansion_p(fname); VALUE tmp = rb_str_tmp_new(expanded_load_path_maxlen + fnlen + 2); rb_enc_associate_index(tmp, rb_usascii_encindex()); for (j=0; ext[j]; j++) { rb_str_cat2(fname, ext[j]); for (i = 0; i < RARRAY_LEN(load_path); i++) { VALUE dname = rb_get_path(RARRAY_AREF(load_path, i)); if (!RSTRING_LEN(dname)) continue; expand_feature(fname, dname, tmp, need_expansion); if (rb_file_load_ok(RSTRING_PTR(tmp))) { *filep = copy_path_class(tmp, *filep); return (int)(j+1); } } rb_str_set_len(fname, fnlen); } rb_str_resize(tmp, 0); RB_GC_GUARD(load_path); RB_GC_GUARD(tmp); return 0; } VALUE rb_find_file(VALUE path) { const char *f = StringValueCStr(path); int expanded = 0; if (f[0] == '~') { path = copy_path_class(file_expand_path_1(path, 0), path); f = RSTRING_PTR(path); expanded = 1; } if (expanded || rb_is_absolute_path(f) || is_explicit_relative(f)) { if (!rb_file_load_ok(f)) return 0; if (!expanded) path = copy_path_class(file_expand_path_1(path, 0), path); return path; } rb_len_t expanded_load_path_maxlen; VALUE load_path = rb_get_expanded_load_path(&expanded_load_path_maxlen); if (load_path) { bool need_expansion = fname_need_expansion_p(path); VALUE tmp = rb_str_tmp_new(expanded_load_path_maxlen + RSTRING_LEN(path) + 2); rb_enc_associate_index(tmp, rb_usascii_encindex()); for (rb_len_t i = 0; i < RARRAY_LEN(load_path); i++) { VALUE dname = rb_get_path(RARRAY_AREF(load_path, i)); if (!RSTRING_LEN(dname)) continue; expand_feature(path, dname, tmp, need_expansion); if (rb_file_load_ok(RSTRING_PTR(tmp))) { return copy_path_class(tmp, path); } } rb_str_resize(tmp, 0); } RB_GC_GUARD(load_path); return Qfalse; /* no path, no load */ } #define define_filetest_function(name, func, argc) do { \ rb_define_module_function(rb_mFileTest, name, func, argc); \ rb_define_singleton_method(rb_cFile, name, func, argc); \ } while(false) const char ruby_null_device[] = #if defined DOSISH "NUL" #else "/dev/null" #endif ; /* * A \File object is a representation of a file in the underlying platform. * * Class \File extends module FileTest, supporting such singleton methods * as File.exist?. * * == About the Examples * * Many examples here use these variables: * * :include: doc/examples/files.rdoc * * == Access Modes * * Methods File.new and File.open each create a \File object for a given file path. * * === \String Access Modes * * Methods File.new and File.open each may take string argument +mode+, which: * * - Begins with a 1- or 2-character * {read/write mode}[rdoc-ref:File@ReadWrite+Mode]. * - May also contain a 1-character {data mode}[rdoc-ref:File@Data+Mode]. * - May also contain a 1-character * {file-create mode}[rdoc-ref:File@File-Create+Mode]. * * ==== Read/Write Mode * * The read/write +mode+ determines: * * - Whether the file is to be initially truncated. * * - Whether reading is allowed, and if so: * * - The initial read position in the file. * - Where in the file reading can occur. * * - Whether writing is allowed, and if so: * * - The initial write position in the file. * - Where in the file writing can occur. * * These tables summarize: * * Read/Write Modes for Existing File * * |------|-----------|----------|----------|----------|-----------| * | R/W | Initial | | Initial | | Initial | * | Mode | Truncate? | Read | Read Pos | Write | Write Pos | * |------|-----------|----------|----------|----------|-----------| * | 'r' | No | Anywhere | 0 | Error | - | * | 'w' | Yes | Error | - | Anywhere | 0 | * | 'a' | No | Error | - | End only | End | * | 'r+' | No | Anywhere | 0 | Anywhere | 0 | * | 'w+' | Yes | Anywhere | 0 | Anywhere | 0 | * | 'a+' | No | Anywhere | End | End only | End | * |------|-----------|----------|----------|----------|-----------| * * Read/Write Modes for \File To Be Created * * |------|----------|----------|----------|-----------| * | R/W | | Initial | | Initial | * | Mode | Read | Read Pos | Write | Write Pos | * |------|----------|----------|----------|-----------| * | 'w' | Error | - | Anywhere | 0 | * | 'a' | Error | - | End only | 0 | * | 'w+' | Anywhere | 0 | Anywhere | 0 | * | 'a+' | Anywhere | 0 | End only | End | * |------|----------|----------|----------|-----------| * * Note that modes 'r' and 'r+' are not allowed * for a non-existent file (exception raised). * * In the tables: * * - +Anywhere+ means that methods IO#rewind, IO#pos=, and IO#seek * may be used to change the file's position, * so that allowed reading or writing may occur anywhere in the file. * - End only means that writing can occur only at end-of-file, * and that methods IO#rewind, IO#pos=, and IO#seek do not affect writing. * - +Error+ means that an exception is raised if disallowed reading or writing * is attempted. * * ===== Read/Write Modes for Existing \File * * - 'r': * * - \File is not initially truncated: * * f = File.new('t.txt') # => # * f.size == 0 # => false * * - File's initial read position is 0: * * f.pos # => 0 * * - \File may be read anywhere; see IO#rewind, IO#pos=, IO#seek: * * f.readline # => "First line\n" * f.readline # => "Second line\n" * * f.rewind * f.readline # => "First line\n" * * f.pos = 1 * f.readline # => "irst line\n" * * f.seek(1, :CUR) * f.readline # => "econd line\n" * * - Writing is not allowed: * * f.write('foo') # Raises IOError. * * - 'w': * * - \File is initially truncated: * * path = 't.tmp' * File.write(path, text) * f = File.new(path, 'w') * f.size == 0 # => true * * - File's initial write position is 0: * * f.pos # => 0 * * - \File may be written anywhere (even past end-of-file); * see IO#rewind, IO#pos=, IO#seek: * * f.write('foo') * f.flush * File.read(path) # => "foo" * f.pos # => 3 * * f.write('bar') * f.flush * File.read(path) # => "foobar" * f.pos # => 6 * * f.rewind * f.write('baz') * f.flush * File.read(path) # => "bazbar" * f.pos # => 3 * * f.pos = 3 * f.write('foo') * f.flush * File.read(path) # => "bazfoo" * f.pos # => 6 * * f.seek(-3, :END) * f.write('bam') * f.flush * File.read(path) # => "bazbam" * f.pos # => 6 * * f.pos = 8 * f.write('bah') # Zero padding as needed. * f.flush * File.read(path) # => "bazbam\u0000\u0000bah" * f.pos # => 11 * * - Reading is not allowed: * * f.read # Raises IOError. * * - 'a': * * - \File is not initially truncated: * * path = 't.tmp' * File.write(path, 'foo') * f = File.new(path, 'a') * f.size == 0 # => false * * - File's initial position is 0 (but is ignored): * * f.pos # => 0 * * - \File may be written only at end-of-file; * IO#rewind, IO#pos=, IO#seek do not affect writing: * * f.write('bar') * f.flush * File.read(path) # => "foobar" * f.write('baz') * f.flush * File.read(path) # => "foobarbaz" * * f.rewind * f.write('bat') * f.flush * File.read(path) # => "foobarbazbat" * * - Reading is not allowed: * * f.read # Raises IOError. * * - 'r+': * * - \File is not initially truncated: * * path = 't.tmp' * File.write(path, text) * f = File.new(path, 'r+') * f.size == 0 # => false * * - File's initial read position is 0: * * f.pos # => 0 * * - \File may be read or written anywhere (even past end-of-file); * see IO#rewind, IO#pos=, IO#seek: * * f.readline # => "First line\n" * f.readline # => "Second line\n" * * f.rewind * f.readline # => "First line\n" * * f.pos = 1 * f.readline # => "irst line\n" * * f.seek(1, :CUR) * f.readline # => "econd line\n" * * f.rewind * f.write('WWW') * f.flush * File.read(path) * # => "WWWst line\nSecond line\nFourth line\nFifth line\n" * * f.pos = 10 * f.write('XXX') * f.flush * File.read(path) * # => "WWWst lineXXXecond line\nFourth line\nFifth line\n" * * f.seek(-6, :END) * # => 0 * f.write('YYY') * # => 3 * f.flush * # => # * File.read(path) * # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n" * * f.seek(2, :END) * f.write('ZZZ') # Zero padding as needed. * f.flush * File.read(path) * # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ" * * * - 'a+': * * - \File is not initially truncated: * * path = 't.tmp' * File.write(path, 'foo') * f = File.new(path, 'a+') * f.size == 0 # => false * * - File's initial read position is 0: * * f.pos # => 0 * * - \File may be written only at end-of-file; * IO#rewind, IO#pos=, IO#seek do not affect writing: * * f.write('bar') * f.flush * File.read(path) # => "foobar" * f.write('baz') * f.flush * File.read(path) # => "foobarbaz" * * f.rewind * f.write('bat') * f.flush * File.read(path) # => "foobarbazbat" * * - \File may be read anywhere; see IO#rewind, IO#pos=, IO#seek: * * f.rewind * f.read # => "foobarbazbat" * * f.pos = 3 * f.read # => "barbazbat" * * f.seek(-3, :END) * f.read # => "bat" * * ===== Read/Write Modes for \File To Be Created * * Note that modes 'r' and 'r+' are not allowed * for a non-existent file (exception raised). * * - 'w': * * - File's initial write position is 0: * * path = 't.tmp' * FileUtils.rm_f(path) * f = File.new(path, 'w') * f.pos # => 0 * * - \File may be written anywhere (even past end-of-file); * see IO#rewind, IO#pos=, IO#seek: * * f.write('foo') * f.flush * File.read(path) # => "foo" * f.pos # => 3 * * f.write('bar') * f.flush * File.read(path) # => "foobar" * f.pos # => 6 * * f.rewind * f.write('baz') * f.flush * File.read(path) # => "bazbar" * f.pos # => 3 * * f.pos = 3 * f.write('foo') * f.flush * File.read(path) # => "bazfoo" * f.pos # => 6 * * f.seek(-3, :END) * f.write('bam') * f.flush * File.read(path) # => "bazbam" * f.pos # => 6 * * f.pos = 8 * f.write('bah') # Zero padding as needed. * f.flush * File.read(path) # => "bazbam\u0000\u0000bah" * f.pos # => 11 * * - Reading is not allowed: * * f.read # Raises IOError. * * - 'a': * * - File's initial write position is 0: * * path = 't.tmp' * FileUtils.rm_f(path) * f = File.new(path, 'a') * f.pos # => 0 * * - Writing occurs only at end-of-file: * * f.write('foo') * f.pos # => 3 * f.write('bar') * f.pos # => 6 * f.flush * File.read(path) # => "foobar" * * f.rewind * f.write('baz') * f.flush * File.read(path) # => "foobarbaz" * * - Reading is not allowed: * * f.read # Raises IOError. * * - 'w+': * * - File's initial position is 0: * * path = 't.tmp' * FileUtils.rm_f(path) * f = File.new(path, 'w+') * f.pos # => 0 * * - \File may be written anywhere (even past end-of-file); * see IO#rewind, IO#pos=, IO#seek: * * f.write('foo') * f.flush * File.read(path) # => "foo" * f.pos # => 3 * * f.write('bar') * f.flush * File.read(path) # => "foobar" * f.pos # => 6 * * f.rewind * f.write('baz') * f.flush * File.read(path) # => "bazbar" * f.pos # => 3 * * f.pos = 3 * f.write('foo') * f.flush * File.read(path) # => "bazfoo" * f.pos # => 6 * * f.seek(-3, :END) * f.write('bam') * f.flush * File.read(path) # => "bazbam" * f.pos # => 6 * * f.pos = 8 * f.write('bah') # Zero padding as needed. * f.flush * File.read(path) # => "bazbam\u0000\u0000bah" * f.pos # => 11 * * - \File may be read anywhere (even past end-of-file); * see IO#rewind, IO#pos=, IO#seek: * * f.rewind * # => 0 * f.read * # => "bazbam\u0000\u0000bah" * * f.pos = 3 * # => 3 * f.read * # => "bam\u0000\u0000bah" * * f.seek(-3, :END) * # => 0 * f.read * # => "bah" * * - 'a+': * * - File's initial write position is 0: * * path = 't.tmp' * FileUtils.rm_f(path) * f = File.new(path, 'a+') * f.pos # => 0 * * - Writing occurs only at end-of-file: * * f.write('foo') * f.pos # => 3 * f.write('bar') * f.pos # => 6 * f.flush * File.read(path) # => "foobar" * * f.rewind * f.write('baz') * f.flush * File.read(path) # => "foobarbaz" * * - \File may be read anywhere (even past end-of-file); * see IO#rewind, IO#pos=, IO#seek: * * f.rewind * f.read # => "foobarbaz" * * f.pos = 3 * f.read # => "barbaz" * * f.seek(-3, :END) * f.read # => "baz" * * f.pos = 800 * f.read # => "" * * ==== \Data Mode * * To specify whether data is to be treated as text or as binary data, * either of the following may be suffixed to any of the string read/write modes * above: * * - 't': Text data; sets the default external encoding * to Encoding::UTF_8; * on Windows, enables conversion between EOL and CRLF * and enables interpreting 0x1A as an end-of-file marker. * - 'b': Binary data; sets the default external encoding * to Encoding::ASCII_8BIT; * on Windows, suppresses conversion between EOL and CRLF * and disables interpreting 0x1A as an end-of-file marker. * * If neither is given, the stream defaults to text data. * * Examples: * * File.new('t.txt', 'rt') * File.new('t.dat', 'rb') * * When the data mode is specified, the read/write mode may not be omitted, * and the data mode must precede the file-create mode, if given: * * File.new('t.dat', 'b') # Raises an exception. * File.new('t.dat', 'rxb') # Raises an exception. * * ==== \File-Create Mode * * The following may be suffixed to any writable string mode above: * * - 'x': Creates the file if it does not exist; * raises an exception if the file exists. * * Example: * * File.new('t.tmp', 'wx') * * When the file-create mode is specified, the read/write mode may not be omitted, * and the file-create mode must follow the data mode: * * File.new('t.dat', 'x') # Raises an exception. * File.new('t.dat', 'rxb') # Raises an exception. * * === \Integer Access Modes * * When mode is an integer it must be one or more of the following constants, * which may be combined by the bitwise OR operator |: * * - +File::RDONLY+: Open for reading only. * - +File::WRONLY+: Open for writing only. * - +File::RDWR+: Open for reading and writing. * - +File::APPEND+: Open for appending only. * * Examples: * * File.new('t.txt', File::RDONLY) * File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL) * * Note: Method IO#set_encoding does not allow the mode to be specified as an integer. * * === File-Create Mode Specified as an \Integer * * These constants may also be ORed into the integer mode: * * - +File::CREAT+: Create file if it does not exist. * - +File::EXCL+: Raise an exception if +File::CREAT+ is given and the file exists. * * === \Data Mode Specified as an \Integer * * \Data mode cannot be specified as an integer. * When the stream access mode is given as an integer, * the data mode is always text, never binary. * * Note that although there is a constant +File::BINARY+, * setting its value in an integer stream mode has no effect; * this is because, as documented in File::Constants, * the +File::BINARY+ value disables line code conversion, * but does not change the external encoding. * * === Encodings * * Any of the string modes above may specify encodings - * either external encoding only or both external and internal encodings - * by appending one or both encoding names, separated by colons: * * f = File.new('t.dat', 'rb') * f.external_encoding # => # * f.internal_encoding # => nil * f = File.new('t.dat', 'rb:UTF-16') * f.external_encoding # => # * f.internal_encoding # => nil * f = File.new('t.dat', 'rb:UTF-16:UTF-16') * f.external_encoding # => # * f.internal_encoding # => # * f.close * * The numerous encoding names are available in array Encoding.name_list: * * Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"] * * When the external encoding is set, strings read are tagged by that encoding * when reading, and strings written are converted to that encoding when * writing. * * When both external and internal encodings are set, * strings read are converted from external to internal encoding, * and strings written are converted from internal to external encoding. * For further details about transcoding input and output, * see {Encodings}[rdoc-ref:encodings.rdoc@Encodings]. * * If the external encoding is 'BOM|UTF-8', 'BOM|UTF-16LE' * or 'BOM|UTF16-BE', * Ruby checks for a Unicode BOM in the input document * to help determine the encoding. * For UTF-16 encodings the file open mode must be binary. * If the BOM is found, * it is stripped and the external encoding from the BOM is used. * * Note that the BOM-style encoding option is case insensitive, * so 'bom|utf-8' is also valid. * * == \File Permissions * * A \File object has _permissions_, an octal integer representing * the permissions of an actual file in the underlying platform. * * Note that file permissions are quite different from the _mode_ * of a file stream (\File object). * * In a \File object, the permissions are available thus, * where method +mode+, despite its name, returns permissions: * * f = File.new('t.txt') * f.lstat.mode.to_s(8) # => "100644" * * On a Unix-based operating system, * the three low-order octal digits represent the permissions * for owner (6), group (4), and world (4). * The triplet of bits in each octal digit represent, respectively, * read, write, and execute permissions. * * Permissions 0644 thus represent read-write access for owner * and read-only access for group and world. * See man pages {open(2)}[https://www.unix.com/man-page/bsd/2/open] * and {chmod(2)}[https://www.unix.com/man-page/bsd/2/chmod]. * * For a directory, the meaning of the execute bit changes: * when set, the directory can be searched. * * Higher-order bits in permissions may indicate the type of file * (plain, directory, pipe, socket, etc.) and various other special features. * * On non-Posix operating systems, permissions may include only read-only or * read-write, in which case, the remaining permission will resemble typical * values. On Windows, for instance, the default permissions are +0644+; The * only change that can be made is to make the file read-only, which is * reported as +0444+. * * For a method that actually creates a file in the underlying platform * (as opposed to merely creating a \File object), * permissions may be specified: * * File.new('t.tmp', File::CREAT, 0644) * File.new('t.tmp', File::CREAT, 0444) * * Permissions may also be changed: * * f = File.new('t.tmp', File::CREAT, 0444) * f.chmod(0644) * f.chmod(0444) * * == \File \Constants * * Various constants for use in \File and IO methods * may be found in module File::Constants; * an array of their names is returned by File::Constants.constants. * * == What's Here * * First, what's elsewhere. Class \File: * * - Inherits from {class IO}[rdoc-ref:IO@Whats+Here], * in particular, methods for creating, reading, and writing files * - Includes module FileTest, * which provides dozens of additional methods. * * Here, class \File provides methods that are useful for: * * - {Creating}[rdoc-ref:File@Creating] * - {Querying}[rdoc-ref:File@Querying] * - {Settings}[rdoc-ref:File@Settings] * - {Other}[rdoc-ref:File@Other] * * === Creating * * - ::new: Opens the file at the given path; returns the file. * - ::open: Same as ::new, but when given a block will yield the file to the block, * and close the file upon exiting the block. * - ::link: Creates a new name for an existing file using a hard link. * - ::mkfifo: Returns the FIFO file created at the given path. * - ::symlink: Creates a symbolic link for the given file path. * * === Querying * * _Paths_ * * - ::absolute_path: Returns the absolute file path for the given path. * - ::absolute_path?: Returns whether the given path is the absolute file path. * - ::basename: Returns the last component of the given file path. * - ::dirname: Returns all but the last component of the given file path. * - ::expand_path: Returns the absolute file path for the given path, * expanding ~ for a home directory. * - ::extname: Returns the file extension for the given file path. * - ::fnmatch? (aliased as ::fnmatch): Returns whether the given file path * matches the given pattern. * - ::join: Joins path components into a single path string. * - ::path: Returns the string representation of the given path. * - ::readlink: Returns the path to the file at the given symbolic link. * - ::realdirpath: Returns the real path for the given file path, * where the last component need not exist. * - ::realpath: Returns the real path for the given file path, * where all components must exist. * - ::split: Returns an array of two strings: the directory name and basename * of the file at the given path. * - #path (aliased as #to_path): Returns the string representation of the given path. * * _Times_ * * - ::atime: Returns a Time for the most recent access to the given file. * - ::birthtime: Returns a Time for the creation of the given file. * - ::ctime: Returns a Time for the metadata change of the given file. * - ::mtime: Returns a Time for the most recent data modification to * the content of the given file. * - #atime: Returns a Time for the most recent access to +self+. * - #birthtime: Returns a Time the creation for +self+. * - #ctime: Returns a Time for the metadata change of +self+. * - #mtime: Returns a Time for the most recent data modification * to the content of +self+. * * _Types_ * * - ::blockdev?: Returns whether the file at the given path is a block device. * - ::chardev?: Returns whether the file at the given path is a character device. * - ::directory?: Returns whether the file at the given path is a directory. * - ::executable?: Returns whether the file at the given path is executable * by the effective user and group of the current process. * - ::executable_real?: Returns whether the file at the given path is executable * by the real user and group of the current process. * - ::exist?: Returns whether the file at the given path exists. * - ::file?: Returns whether the file at the given path is a regular file. * - ::ftype: Returns a string giving the type of the file at the given path. * - ::grpowned?: Returns whether the effective group of the current process * owns the file at the given path. * - ::identical?: Returns whether the files at two given paths are identical. * - ::lstat: Returns the File::Stat object for the last symbolic link * in the given path. * - ::owned?: Returns whether the effective user of the current process * owns the file at the given path. * - ::pipe?: Returns whether the file at the given path is a pipe. * - ::readable?: Returns whether the file at the given path is readable * by the effective user and group of the current process. * - ::readable_real?: Returns whether the file at the given path is readable * by the real user and group of the current process. * - ::setgid?: Returns whether the setgid bit is set for the file at the given path. * - ::setuid?: Returns whether the setuid bit is set for the file at the given path. * - ::socket?: Returns whether the file at the given path is a socket. * - ::stat: Returns the File::Stat object for the file at the given path. * - ::sticky?: Returns whether the file at the given path has its sticky bit set. * - ::symlink?: Returns whether the file at the given path is a symbolic link. * - ::umask: Returns the umask value for the current process. * - ::world_readable?: Returns whether the file at the given path is readable * by others. * - ::world_writable?: Returns whether the file at the given path is writable * by others. * - ::writable?: Returns whether the file at the given path is writable * by the effective user and group of the current process. * - ::writable_real?: Returns whether the file at the given path is writable * by the real user and group of the current process. * - #lstat: Returns the File::Stat object for the last symbolic link * in the path for +self+. * * _Contents_ * * - ::empty? (aliased as ::zero?): Returns whether the file at the given path * exists and is empty. * - ::size: Returns the size (bytes) of the file at the given path. * - ::size?: Returns +nil+ if there is no file at the given path, * or if that file is empty; otherwise returns the file size (bytes). * - #size: Returns the size (bytes) of +self+. * * === Settings * * - ::chmod: Changes permissions of the file at the given path. * - ::chown: Change ownership of the file at the given path. * - ::lchmod: Changes permissions of the last symbolic link in the given path. * - ::lchown: Change ownership of the last symbolic in the given path. * - ::lutime: For each given file path, sets the access time and modification time * of the last symbolic link in the path. * - ::rename: Moves the file at one given path to another given path. * - ::utime: Sets the access time and modification time of each file * at the given paths. * - #flock: Locks or unlocks +self+. * * === Other * * - ::truncate: Truncates the file at the given file path to the given size. * - ::unlink (aliased as ::delete): Deletes the file for each given file path. * - #truncate: Truncates +self+ to the given size. * */ void Init_File(void) { #if defined(__APPLE__) && defined(HAVE_WORKING_FORK) rb_CFString_class_initialize_before_fork(); #endif VALUE separator; rb_mFileTest = rb_define_module("FileTest"); rb_cFile = rb_define_class("File", rb_cIO); define_filetest_function("directory?", rb_file_directory_p, 1); define_filetest_function("exist?", rb_file_exist_p, 1); define_filetest_function("readable?", rb_file_readable_p, 1); define_filetest_function("readable_real?", rb_file_readable_real_p, 1); define_filetest_function("world_readable?", rb_file_world_readable_p, 1); define_filetest_function("writable?", rb_file_writable_p, 1); define_filetest_function("writable_real?", rb_file_writable_real_p, 1); define_filetest_function("world_writable?", rb_file_world_writable_p, 1); define_filetest_function("executable?", rb_file_executable_p, 1); define_filetest_function("executable_real?", rb_file_executable_real_p, 1); define_filetest_function("file?", rb_file_file_p, 1); define_filetest_function("zero?", rb_file_zero_p, 1); define_filetest_function("empty?", rb_file_zero_p, 1); define_filetest_function("size?", rb_file_size_p, 1); define_filetest_function("size", rb_file_s_size, 1); define_filetest_function("owned?", rb_file_owned_p, 1); define_filetest_function("grpowned?", rb_file_grpowned_p, 1); define_filetest_function("pipe?", rb_file_pipe_p, 1); define_filetest_function("symlink?", rb_file_symlink_p, 1); define_filetest_function("socket?", rb_file_socket_p, 1); define_filetest_function("blockdev?", rb_file_blockdev_p, 1); define_filetest_function("chardev?", rb_file_chardev_p, 1); define_filetest_function("setuid?", rb_file_suid_p, 1); define_filetest_function("setgid?", rb_file_sgid_p, 1); define_filetest_function("sticky?", rb_file_sticky_p, 1); define_filetest_function("identical?", rb_file_identical_p, 2); rb_define_singleton_method(rb_cFile, "stat", rb_file_s_stat, 1); rb_define_singleton_method(rb_cFile, "lstat", rb_file_s_lstat, 1); rb_define_singleton_method(rb_cFile, "ftype", rb_file_s_ftype, 1); rb_define_singleton_method(rb_cFile, "atime", rb_file_s_atime, 1); rb_define_singleton_method(rb_cFile, "mtime", rb_file_s_mtime, 1); rb_define_singleton_method(rb_cFile, "ctime", rb_file_s_ctime, 1); rb_define_singleton_method(rb_cFile, "birthtime", rb_file_s_birthtime, 1); rb_define_singleton_method(rb_cFile, "utime", rb_file_s_utime, -1); rb_define_singleton_method(rb_cFile, "chmod", rb_file_s_chmod, -1); rb_define_singleton_method(rb_cFile, "chown", rb_file_s_chown, -1); rb_define_singleton_method(rb_cFile, "lchmod", rb_file_s_lchmod, -1); rb_define_singleton_method(rb_cFile, "lchown", rb_file_s_lchown, -1); rb_define_singleton_method(rb_cFile, "lutime", rb_file_s_lutime, -1); rb_define_singleton_method(rb_cFile, "link", rb_file_s_link, 2); rb_define_singleton_method(rb_cFile, "symlink", rb_file_s_symlink, 2); rb_define_singleton_method(rb_cFile, "readlink", rb_file_s_readlink, 1); rb_define_singleton_method(rb_cFile, "unlink", rb_file_s_unlink, -1); rb_define_singleton_method(rb_cFile, "delete", rb_file_s_unlink, -1); rb_define_singleton_method(rb_cFile, "rename", rb_file_s_rename, 2); rb_define_singleton_method(rb_cFile, "umask", rb_file_s_umask, -1); rb_define_singleton_method(rb_cFile, "truncate", rb_file_s_truncate, 2); rb_define_singleton_method(rb_cFile, "mkfifo", rb_file_s_mkfifo, -1); rb_define_singleton_method(rb_cFile, "expand_path", s_expand_path, -1); rb_define_singleton_method(rb_cFile, "absolute_path", s_absolute_path, -1); rb_define_singleton_method(rb_cFile, "absolute_path?", s_absolute_path_p, 1); rb_define_singleton_method(rb_cFile, "realpath", rb_file_s_realpath, -1); rb_define_singleton_method(rb_cFile, "realdirpath", rb_file_s_realdirpath, -1); rb_define_singleton_method(rb_cFile, "basename", rb_file_s_basename, -1); rb_define_singleton_method(rb_cFile, "dirname", rb_file_s_dirname, -1); rb_define_singleton_method(rb_cFile, "extname", rb_file_s_extname, 1); rb_define_singleton_method(rb_cFile, "path", rb_file_s_path, 1); separator = rb_fstring_lit("/"); /* separates directory parts in path */ rb_define_const(rb_cFile, "Separator", separator); /* separates directory parts in path */ rb_define_const(rb_cFile, "SEPARATOR", separator); rb_define_singleton_method(rb_cFile, "split", rb_file_s_split, 1); rb_define_singleton_method(rb_cFile, "join", rb_file_s_join, -1); #ifdef DOSISH /* platform specific alternative separator */ rb_define_const(rb_cFile, "ALT_SEPARATOR", rb_obj_freeze(rb_usascii_str_new2(file_alt_separator))); #else rb_define_const(rb_cFile, "ALT_SEPARATOR", Qnil); #endif /* path list separator */ rb_define_const(rb_cFile, "PATH_SEPARATOR", rb_fstring_cstr(PATH_SEP)); rb_define_method(rb_cIO, "stat", rb_io_stat, 0); /* this is IO's method */ rb_define_method(rb_cFile, "lstat", rb_file_lstat, 0); rb_define_method(rb_cFile, "atime", rb_file_atime, 0); rb_define_method(rb_cFile, "mtime", rb_file_mtime, 0); rb_define_method(rb_cFile, "ctime", rb_file_ctime, 0); rb_define_method(rb_cFile, "birthtime", rb_file_birthtime, 0); rb_define_method(rb_cFile, "size", file_size, 0); rb_define_method(rb_cFile, "chmod", rb_file_chmod, 1); rb_define_method(rb_cFile, "chown", rb_file_chown, 2); rb_define_method(rb_cFile, "truncate", rb_file_truncate, 1); rb_define_method(rb_cFile, "flock", rb_file_flock, 1); /* * Document-module: File::Constants * * Module +File::Constants+ defines file-related constants. * * There are two families of constants here: * * - Those having to do with {file access}[rdoc-ref:File::Constants@File+Access]. * - Those having to do with {filename globbing}[rdoc-ref:File::Constants@Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29]. * * \File constants defined for the local process may be retrieved * with method File::Constants.constants: * * File::Constants.constants.take(5) * # => [:RDONLY, :WRONLY, :RDWR, :APPEND, :CREAT] * * == \File Access * * \File-access constants may be used with optional argument +mode+ in calls * to the following methods: * * - File.new. * - File.open. * - IO.for_fd. * - IO.new. * - IO.open. * - IO.popen. * - IO.reopen. * - IO.sysopen. * - StringIO.new. * - StringIO.open. * - StringIO#reopen. * * === Read/Write Access * * Read-write access for a stream * may be specified by a file-access constant. * * The constant may be specified as part of a bitwise OR of other such constants. * * Any combination of the constants in this section may be specified. * * ==== File::RDONLY * * Flag File::RDONLY specifies the stream should be opened for reading only: * * filepath = '/tmp/t.tmp' * f = File.new(filepath, File::RDONLY) * f.write('Foo') # Raises IOError (not opened for writing). * * ==== File::WRONLY * * Flag File::WRONLY specifies that the stream should be opened for writing only: * * f = File.new(filepath, File::WRONLY) * f.read # Raises IOError (not opened for reading). * * ==== File::RDWR * * Flag File::RDWR specifies that the stream should be opened * for both reading and writing: * * f = File.new(filepath, File::RDWR) * f.write('Foo') # => 3 * f.rewind # => 0 * f.read # => "Foo" * * === \File Positioning * * ==== File::APPEND * * Flag File::APPEND specifies that the stream should be opened * in append mode. * * Before each write operation, the position is set to end-of-stream. * The modification of the position and the following write operation * are performed as a single atomic step. * * ==== File::TRUNC * * Flag File::TRUNC specifies that the stream should be truncated * at its beginning. * If the file exists and is successfully opened for writing, * it is to be truncated to position zero; * its ctime and mtime are updated. * * There is no effect on a FIFO special file or a terminal device. * The effect on other file types is implementation-defined. * The result of using File::TRUNC with File::RDONLY is undefined. * * === Creating and Preserving * * ==== File::CREAT * * Flag File::CREAT specifies that the stream should be created * if it does not already exist. * * If the file exists: * * - Raise an exception if File::EXCL is also specified. * - Otherwise, do nothing. * * If the file does not exist, then it is created. * Upon successful completion, the atime, ctime, and mtime of the file are updated, * and the ctime and mtime of the parent directory are updated. * * ==== File::EXCL * * Flag File::EXCL specifies that the stream should not already exist; * If flags File::CREAT and File::EXCL are both specified * and the stream already exists, an exception is raised. * * The check for the existence and creation of the file is performed as an * atomic operation. * * If both File::EXCL and File::CREAT are specified and the path names a symbolic link, * an exception is raised regardless of the contents of the symbolic link. * * If File::EXCL is specified and File::CREAT is not specified, * the result is undefined. * * === POSIX \File \Constants * * Some file-access constants are defined only on POSIX-compliant systems; * those are: * * - File::SYNC. * - File::DSYNC. * - File::RSYNC. * - File::DIRECT. * - File::NOATIME. * - File::NOCTTY. * - File::NOFOLLOW. * - File::TMPFILE. * * ==== File::SYNC, File::RSYNC, and File::DSYNC * * Flag File::SYNC, File::RSYNC, or File::DSYNC * specifies synchronization of I/O operations with the underlying file system. * * These flags are valid only for POSIX-compliant systems. * * - File::SYNC specifies that all write operations (both data and metadata) * are immediately to be flushed to the underlying storage device. * This means that the data is written to the storage device, * and the file's metadata (e.g., file size, timestamps, permissions) * are also synchronized. * This guarantees that data is safely stored on the storage medium * before returning control to the calling program. * This flag can have a significant impact on performance * since it requires synchronous writes, which can be slower * compared to asynchronous writes. * * - File::RSYNC specifies that any read operations on the file will not return * until all outstanding write operations * (those that have been issued but not completed) are also synchronized. * This is useful when you want to read the most up-to-date data, * which may still be in the process of being written. * * - File::DSYNC specifies that all _data_ write operations * are immediately to be flushed to the underlying storage device; * this differs from File::SYNC, which requires that _metadata_ * also be synchronized. * * Note that the behavior of these flags may vary slightly * depending on the operating system and filesystem being used. * Additionally, using these flags can have an impact on performance * due to the synchronous nature of the I/O operations, * so they should be used judiciously, * especially in performance-critical applications. * * ==== File::NOCTTY * * Flag File::NOCTTY specifies that if the stream is a terminal device, * that device does not become the controlling terminal for the process. * * Defined only for POSIX-compliant systems. * * ==== File::DIRECT * * Flag File::DIRECT requests that cache effects of the I/O to and from the stream * be minimized. * * Defined only for POSIX-compliant systems. * * ==== File::NOATIME * * Flag File::NOATIME specifies that act of opening the stream * should not modify its access time (atime). * * Defined only for POSIX-compliant systems. * * ==== File::NOFOLLOW * * Flag File::NOFOLLOW specifies that if path is a symbolic link, * it should not be followed. * * Defined only for POSIX-compliant systems. * * ==== File::TMPFILE * * Flag File::TMPFILE specifies that the opened stream * should be a new temporary file. * * Defined only for POSIX-compliant systems. * * === Other File-Access \Constants * * ==== File::NONBLOCK * * When possible, the file is opened in nonblocking mode. * Neither the open operation nor any subsequent I/O operations on * the file will cause the calling process to wait. * * ==== File::BINARY * * Flag File::BINARY specifies that the stream is to be accessed in binary mode. * * ==== File::SHARE_DELETE * * Flag File::SHARE_DELETE enables other processes to open the stream * with delete access. * * Windows only. * * If the stream is opened for (local) delete access without File::SHARE_DELETE, * and another process attempts to open it with delete access, * the attempt fails and the stream is not opened for that process. * * == Locking * * Four file constants relate to stream locking; * see File#flock: * * ==== File::LOCK_EX * * Flag File::LOCK_EX specifies an exclusive lock; * only one process a a time may lock the stream. * * ==== File::LOCK_NB * * Flag File::LOCK_NB specifies non-blocking locking for the stream; * may be combined with File::LOCK_EX or File::LOCK_SH. * * ==== File::LOCK_SH * * Flag File::LOCK_SH specifies that multiple processes may lock * the stream at the same time. * * ==== File::LOCK_UN * * Flag File::LOCK_UN specifies that the stream is not to be locked. * * == Filename Globbing \Constants (File::FNM_*) * * Filename-globbing constants may be used with optional argument +flags+ * in calls to the following methods: * * - Dir.glob. * - File.fnmatch. * - Pathname#fnmatch. * - Pathname.glob. * - Pathname#glob. * * The constants are: * * ==== File::FNM_CASEFOLD * * Flag File::FNM_CASEFOLD makes patterns case insensitive * for File.fnmatch (but not Dir.glob). * * ==== File::FNM_DOTMATCH * * Flag File::FNM_DOTMATCH makes the '*' pattern * match a filename starting with '.'. * * ==== File::FNM_EXTGLOB * * Flag File::FNM_EXTGLOB enables pattern '{a,b}', * which matches pattern '_a_' and pattern '_b_'; * behaves like * a {regexp union}[rdoc-ref:Regexp.union] * (e.g., '(?:a|b)'): * * pattern = '{LEGAL,BSDL}' * Dir.glob(pattern) # => ["LEGAL", "BSDL"] * Pathname.glob(pattern) # => [#, #] * pathname.glob(pattern) # => [#, #] * * ==== File::FNM_NOESCAPE * * Flag File::FNM_NOESCAPE disables '\' escaping. * * ==== File::FNM_PATHNAME * * Flag File::FNM_PATHNAME specifies that patterns '*' and '?' * do not match the directory separator * (the value of constant File::SEPARATOR). * * ==== File::FNM_SHORTNAME * * Flag File::FNM_SHORTNAME allows patterns to match short names if they exist. * * Windows only. * * ==== File::FNM_SYSCASE * * Flag File::FNM_SYSCASE specifies that case sensitivity * is the same as in the underlying operating system; * effective for File.fnmatch, but not Dir.glob. * * == Other \Constants * * ==== File::NULL * * Flag File::NULL contains the string value of the null device: * * - On a Unix-like OS, '/dev/null'. * - On Windows, 'NUL'. * */ rb_mFConst = rb_define_module_under(rb_cFile, "Constants"); rb_include_module(rb_cIO, rb_mFConst); /* {File::RDONLY}[rdoc-ref:File::Constants@File-3A-3ARDONLY] */ rb_define_const(rb_mFConst, "RDONLY", INT2FIX(O_RDONLY)); /* {File::WRONLY}[rdoc-ref:File::Constants@File-3A-3AWRONLY] */ rb_define_const(rb_mFConst, "WRONLY", INT2FIX(O_WRONLY)); /* {File::RDWR}[rdoc-ref:File::Constants@File-3A-3ARDWR] */ rb_define_const(rb_mFConst, "RDWR", INT2FIX(O_RDWR)); /* {File::APPEND}[rdoc-ref:File::Constants@File-3A-3AAPPEND] */ rb_define_const(rb_mFConst, "APPEND", INT2FIX(O_APPEND)); /* {File::CREAT}[rdoc-ref:File::Constants@File-3A-3ACREAT] */ rb_define_const(rb_mFConst, "CREAT", INT2FIX(O_CREAT)); /* {File::EXCL}[rdoc-ref:File::Constants@File-3A-3AEXCL] */ rb_define_const(rb_mFConst, "EXCL", INT2FIX(O_EXCL)); #if defined(O_NDELAY) || defined(O_NONBLOCK) # ifndef O_NONBLOCK # define O_NONBLOCK O_NDELAY # endif /* {File::NONBLOCK}[rdoc-ref:File::Constants@File-3A-3ANONBLOCK] */ rb_define_const(rb_mFConst, "NONBLOCK", INT2FIX(O_NONBLOCK)); #endif /* {File::TRUNC}[rdoc-ref:File::Constants@File-3A-3ATRUNC] */ rb_define_const(rb_mFConst, "TRUNC", INT2FIX(O_TRUNC)); #ifdef O_NOCTTY /* {File::NOCTTY}[rdoc-ref:File::Constants@File-3A-3ANOCTTY] */ rb_define_const(rb_mFConst, "NOCTTY", INT2FIX(O_NOCTTY)); #endif #ifndef O_BINARY # define O_BINARY 0 #endif /* {File::BINARY}[rdoc-ref:File::Constants@File-3A-3ABINARY] */ rb_define_const(rb_mFConst, "BINARY", INT2FIX(O_BINARY)); #ifndef O_SHARE_DELETE # define O_SHARE_DELETE 0 #endif /* {File::SHARE_DELETE}[rdoc-ref:File::Constants@File-3A-3ASHARE_DELETE] */ rb_define_const(rb_mFConst, "SHARE_DELETE", INT2FIX(O_SHARE_DELETE)); #ifdef O_SYNC /* {File::SYNC}[rdoc-ref:File::Constants@File-3A-3ASYNC-2C+File-3A-3ARSYNC-2C+and+File-3A-3ADSYNC] */ rb_define_const(rb_mFConst, "SYNC", INT2FIX(O_SYNC)); #endif #ifdef O_DSYNC /* {File::DSYNC}[rdoc-ref:File::Constants@File-3A-3ASYNC-2C+File-3A-3ARSYNC-2C+and+File-3A-3ADSYNC] */ rb_define_const(rb_mFConst, "DSYNC", INT2FIX(O_DSYNC)); #endif #ifdef O_RSYNC /* {File::RSYNC}[rdoc-ref:File::Constants@File-3A-3ASYNC-2C+File-3A-3ARSYNC-2C+and+File-3A-3ADSYNC] */ rb_define_const(rb_mFConst, "RSYNC", INT2FIX(O_RSYNC)); #endif #ifdef O_NOFOLLOW /* {File::NOFOLLOW}[rdoc-ref:File::Constants@File-3A-3ANOFOLLOW] */ rb_define_const(rb_mFConst, "NOFOLLOW", INT2FIX(O_NOFOLLOW)); /* FreeBSD, Linux */ #endif #ifdef O_NOATIME /* {File::NOATIME}[rdoc-ref:File::Constants@File-3A-3ANOATIME] */ rb_define_const(rb_mFConst, "NOATIME", INT2FIX(O_NOATIME)); /* Linux */ #endif #ifdef O_DIRECT /* {File::DIRECT}[rdoc-ref:File::Constants@File-3A-3ADIRECT] */ rb_define_const(rb_mFConst, "DIRECT", INT2FIX(O_DIRECT)); #endif #ifdef O_TMPFILE /* {File::TMPFILE}[rdoc-ref:File::Constants@File-3A-3ATMPFILE] */ rb_define_const(rb_mFConst, "TMPFILE", INT2FIX(O_TMPFILE)); #endif /* {File::LOCK_SH}[rdoc-ref:File::Constants@File-3A-3ALOCK_SH] */ rb_define_const(rb_mFConst, "LOCK_SH", INT2FIX(LOCK_SH)); /* {File::LOCK_EX}[rdoc-ref:File::Constants@File-3A-3ALOCK_EX] */ rb_define_const(rb_mFConst, "LOCK_EX", INT2FIX(LOCK_EX)); /* {File::LOCK_UN}[rdoc-ref:File::Constants@File-3A-3ALOCK_UN] */ rb_define_const(rb_mFConst, "LOCK_UN", INT2FIX(LOCK_UN)); /* {File::LOCK_NB}[rdoc-ref:File::Constants@File-3A-3ALOCK_NB] */ rb_define_const(rb_mFConst, "LOCK_NB", INT2FIX(LOCK_NB)); /* {File::NULL}[rdoc-ref:File::Constants@File-3A-3ANULL] */ rb_define_const(rb_mFConst, "NULL", rb_fstring_cstr(ruby_null_device)); rb_define_global_function("test", rb_f_test, -1); rb_cStat = rb_define_class_under(rb_cFile, "Stat", rb_cObject); rb_define_alloc_func(rb_cStat, rb_stat_s_alloc); rb_define_method(rb_cStat, "initialize", rb_stat_init, 1); rb_define_method(rb_cStat, "initialize_copy", rb_stat_init_copy, 1); rb_include_module(rb_cStat, rb_mComparable); rb_define_method(rb_cStat, "<=>", rb_stat_cmp, 1); rb_define_method(rb_cStat, "dev", rb_stat_dev, 0); rb_define_method(rb_cStat, "dev_major", rb_stat_dev_major, 0); rb_define_method(rb_cStat, "dev_minor", rb_stat_dev_minor, 0); rb_define_method(rb_cStat, "ino", rb_stat_ino, 0); rb_define_method(rb_cStat, "mode", rb_stat_mode, 0); rb_define_method(rb_cStat, "nlink", rb_stat_nlink, 0); rb_define_method(rb_cStat, "uid", rb_stat_uid, 0); rb_define_method(rb_cStat, "gid", rb_stat_gid, 0); rb_define_method(rb_cStat, "rdev", rb_stat_rdev, 0); rb_define_method(rb_cStat, "rdev_major", rb_stat_rdev_major, 0); rb_define_method(rb_cStat, "rdev_minor", rb_stat_rdev_minor, 0); rb_define_method(rb_cStat, "size", rb_stat_size, 0); rb_define_method(rb_cStat, "blksize", rb_stat_blksize, 0); rb_define_method(rb_cStat, "blocks", rb_stat_blocks, 0); rb_define_method(rb_cStat, "atime", rb_stat_atime, 0); rb_define_method(rb_cStat, "mtime", rb_stat_mtime, 0); rb_define_method(rb_cStat, "ctime", rb_stat_ctime, 0); rb_define_method(rb_cStat, "birthtime", rb_stat_birthtime, 0); rb_define_method(rb_cStat, "inspect", rb_stat_inspect, 0); rb_define_method(rb_cStat, "ftype", rb_stat_ftype, 0); rb_define_method(rb_cStat, "directory?", rb_stat_d, 0); rb_define_method(rb_cStat, "readable?", rb_stat_r, 0); rb_define_method(rb_cStat, "readable_real?", rb_stat_R, 0); rb_define_method(rb_cStat, "world_readable?", rb_stat_wr, 0); rb_define_method(rb_cStat, "writable?", rb_stat_w, 0); rb_define_method(rb_cStat, "writable_real?", rb_stat_W, 0); rb_define_method(rb_cStat, "world_writable?", rb_stat_ww, 0); rb_define_method(rb_cStat, "executable?", rb_stat_x, 0); rb_define_method(rb_cStat, "executable_real?", rb_stat_X, 0); rb_define_method(rb_cStat, "file?", rb_stat_f, 0); rb_define_method(rb_cStat, "zero?", rb_stat_z, 0); rb_define_method(rb_cStat, "size?", rb_stat_s, 0); rb_define_method(rb_cStat, "owned?", rb_stat_owned, 0); rb_define_method(rb_cStat, "grpowned?", rb_stat_grpowned, 0); rb_define_method(rb_cStat, "pipe?", rb_stat_p, 0); rb_define_method(rb_cStat, "symlink?", rb_stat_l, 0); rb_define_method(rb_cStat, "socket?", rb_stat_S, 0); rb_define_method(rb_cStat, "blockdev?", rb_stat_b, 0); rb_define_method(rb_cStat, "chardev?", rb_stat_c, 0); rb_define_method(rb_cStat, "setuid?", rb_stat_suid, 0); rb_define_method(rb_cStat, "setgid?", rb_stat_sgid, 0); rb_define_method(rb_cStat, "sticky?", rb_stat_sticky, 0); }