module FileUtils

Namespace for file utility methods for copying, moving, removing, etc.

What’s Here

First, what’s elsewhere. Module FileUtils:

Here, module FileUtils provides methods that are useful for:

Creating

Deleting

Querying

  • ::pwd, ::getwd: Returns the path to the working directory.

  • ::uptodate?: Returns whether a given entry is newer than given other entries.

Setting

  • ::cd, ::chdir: Sets the working directory.

  • ::chmod: Sets permissions for an entry.

  • ::chmod_R: Sets permissions for an entry and its descendants.

  • ::chown: Sets the owner and group for entries.

  • ::chown_R: Sets the owner and group for entries and their descendants.

  • ::touch: Sets modification and access times for entries, creating if necessary.

Comparing

Copying

Moving

Options

  • ::collect_method: Returns the names of methods that accept a given option.

  • ::commands: Returns the names of methods that accept options.

  • ::have_option?: Returns whether a given method accepts a given option.

  • ::options: Returns all option names.

  • ::options_of: Returns the names of the options for a given method.

Path Arguments

Some methods in FileUtils accept path arguments, which are interpreted as paths to filesystem entries:

  • If the argument is a string, that value is the path.

  • If the argument has method :to_path, it is converted via that method.

  • If the argument has method :to_str, it is converted via that method.

About the Examples

Some examples here involve trees of file entries. For these, we sometimes display trees using the tree command-line utility, which is a recursive directory-listing utility that produces a depth-indented listing of files and directories.

We use a helper method to launch the command and control the format:

def tree(dirpath = '.')
  command = "tree --noreport --charset=ascii #{dirpath}"
  system(command)
end

To illustrate:

tree('src0')
# => src0
#    |-- sub0
#    |   |-- src0.txt
#    |   `-- src1.txt
#    `-- sub1
#        |-- src2.txt
#        `-- src3.txt

Avoiding the TOCTTOU Vulnerability

For certain methods that recursively remove entries, there is a potential vulnerability called the Time-of-check to time-of-use, or TOCTTOU, vulnerability that can exist when:

  • An ancestor directory of the entry at the target path is world writable; such directories include /tmp.

  • The directory tree at the target path includes:

    • A world-writable descendant directory.

    • A symbolic link.

To avoid that vulnerability, you can use this method to remove entries:

Also available are these methods, each of which calls FileUtils.remove_entry_secure:

Finally, this method for moving entries calls FileUtils.remove_entry_secure if the source and destination are on different file systems (which means that the “move” is really a copy and remove):

Method FileUtils.remove_entry_secure removes securely by applying a special pre-process:

  • If the target path points to a directory, this method uses methods File#chown and File#chmod in removing directories.

  • The owner of the target directory should be either the current process or the super user (root).

WARNING: You must ensure that ALL parent directories cannot be moved by other untrusted users. For example, parent directories should not be owned by untrusted users, and should not be world writable except when the sticky bit is set.

For details of this security vulnerability, see Perl cases:

Ruby Core © 1993–2024 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.