From a7361d3e55c110d274e65e76d2293fa2947f9f7f Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 28 Aug 2026 17:40:04 -0500 Subject: [PATCH] [DOC] Harmonize chmod methods doc --- file.c | 62 +++++++++++++++++++++++++++------------------ pathname_builtin.rb | 43 +++++++++++++++---------------- 2 files changed, 57 insertions(+), 48 deletions(-) diff --git a/file.c b/file.c index 6c46b908440..995111e89d8 100644 --- a/file.c +++ b/file.c @@ -2946,26 +2946,28 @@ chmod_internal(const char *path, void *mode) /* * call-seq: - * File.chmod(mode, *paths) -> integer + * File.chmod(mode, *paths) -> integer * - * Changes the mode (i.e., permissions) of the entries of each the given +paths+; - * see {File Permissions}[rdoc-ref:File@File+Permissions]. - * Returns the count of the given +paths+: + * 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]. * - * filepath = 't.tmp' - * File.write(filepath, 'foo') - * dirpath = 'tempdir' - * Dir.mkdir(dirpath) - * File::Stat.new(filepath).mode.to_s(8) # => "100664" - * File::Stat.new(dirpath).mode.to_s(8) # => "40775" - * File.chmod(0775, filepath, dirpath) # => 2 - * File::Stat.new(filepath).mode.to_s(8) # => "100775" - * File::Stat.new(dirpath).mode.to_s(8) # => "40775" - * File.chmod(0664, filepath, dirpath) # => 2 - * File::Stat.new(filepath).mode.to_s(8) # => "100664" - * File::Stat.new(dirpath).mode.to_s(8) # => "40664" - * File.delete(filepath) - * Dir.rmdir(dirpath) + * These examples use + * a {helper method}[rdoc-ref:file/filesystem_modes.md@Helper+Method], +mode+, + * that displays a mode both in octal digits and in characters: + * + * dirpath = 'doc/foo' + * filepath = File.join(dirpath, 't.tmp') + * Dir.mkdir(dirpath) # Create directory. + * mode(dirpath) # => "040775 drwxrwxr-x" + * File.write(filepath, 'bar') # Create file. + * mode(filepath) # => "100664 -rw-rw-r--" + * File.chmod(0755, filepath) # Change file mode. + * mode(filepath) # => "100755 -rwxr-xr-x" + * File.chmod(0664, dirpath) # Change directory mode. + * mode(dirpath) # => "040664 drw-rw-r--" + * FileUtils.rm_rf(dirpath) # Clean up. * */ @@ -3005,15 +3007,25 @@ rb_fchmod(struct rb_io* io, mode_t mode) /* * call-seq: - * file.chmod(mode_int) -> 0 + * chmod(mode) -> 0 * - * Changes permission bits on file to the bit pattern - * represented by mode_int. Actual effects are platform - * dependent; on Unix systems, see chmod(2) for details. - * Follows symbolic links. Also see File#lchmod. + * 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]. + * + * These examples use + * a {helper method}[rdoc-ref:file/filesystem_modes.md@Helper+Method], +mode+, + * that displays a mode both in octal digits and in characters: + * + * filepath = 'doc/t.tmp' + * File.write(filepath, 'foo') + * file = File.new(filepath) + * mode(filepath) # => "100664 -rw-rw-r--" + * file.chmod(0775) + * mode(filepath) # => "100775 -rwxrwxr-x" + * file.close + * File.delete(filepath) * - * f = File.new("out", "w"); - * f.chmod(0644) #=> 0 */ static VALUE diff --git a/pathname_builtin.rb b/pathname_builtin.rb index 6b8108ce087..e538408ff62 100644 --- a/pathname_builtin.rb +++ b/pathname_builtin.rb @@ -1503,31 +1503,28 @@ class Pathname # * File * # call-seq: # chmod(mode) -> 1 # - # Changes the mode (i.e., permissions) of the entry represented by `self`; - # see {File Permissions}[rdoc-ref:File@File+Permissions]: + # Changes the mode of the entry at the path in `self`; returns `1`. + # See {Filesystem Modes}[rdoc-ref:file/filesystem_modes.md] + # and especially {Setting a Mode}[rdoc-ref:file/filesystem_modes.md@Setting+a+Mode]. + # + # These examples use + # a {helper method}[rdoc-ref:file/filesystem_modes.md@Helper+Method], `mode`, + # that displays a mode both in octal digits and in characters: # # ```ruby - # # Pathname for a (non-existent) directory. - # dir_pn = Pathname('doc/foo') # => # - # # Create the directory and fetch its mode. - # dir_pn.mkdir - # dir_pn.stat.mode.to_s(8) # => "40775" - # # Change the directory mode and fetch the new mode. - # dir_pn.chmod(0777) - # dir_pn.stat.mode.to_s(8) # => "40777" - # - # # Pathname for a (non-existent) file in the directory. - # file_pn = dir_pn.join('t.tmp') # => # - # # Create the file and fetch its mode. - # file_pn.write('foo') - # file_pn.stat.mode.to_s(8) # => "100664" - # # Change the file mode and fetch its new mode. - # file_pn.chmod(0777) - # file_pn.stat.mode.to_s(8) # => "100777" - # - # # Clean up. - # file_pn.delete - # dir_pn.rmdir + # dirpath = 'doc/foo' + # dir_pn = Pathname(dirpath) + # dir_pn.mkdir # Create directory. + # mode(dirpath) # => "040775 drwxrwxr-x" + # filepath = File.join(dirpath, 't.tmp') + # file_pn = Pathname(filepath) + # file_pn.write('bar') # Create file. + # mode(filepath) # => "100664 -rw-rw-r--" + # file_pn.chmod(0755) # Change file mode. + # mode(filepath) # => "100755 -rwxr-xr-x" + # dir_pn.chmod(0644) # Change directory mode. + # mode(dirpath) # => "040644 drw-r--r--" + # dir_pn.rmtree # Clean up. # ``` # def chmod(mode) File.chmod(mode, @path) end