1#@!#!123s

: / proc / self / root / opt / alt / ruby34 / share / ri / system / FileUtils /
Filename : cdesc-FileUtils.ri
back
U:RDoc::NormalModule[iI"FileUtils:ET@0o:RDoc::Markup::Document:@parts[o;;[Lo:RDoc::Markup::Paragraph;[I"KNamespace for file utility methods for copying, moving, removing, etc.;To:RDoc::Markup::BlankLine�S:RDoc::Markup::Heading:
leveli:	textI"What's Here;T@o;	;[I"3First, what’s elsewhere. \Module \FileUtils:;T@o:RDoc::Markup::List:
@type:BULLET:@items[o:RDoc::Markup::ListItem:@label0;[o;	;[I"3Inherits from {class Object}[rdoc-ref:Object].;To;;0;[o;	;[I"-Supplements {class File}[rdoc-ref:File] ;TI"-(but is not included or extended there).;T@o;	;[I"BHere, module \FileUtils provides methods that are useful for:;T@o;;;;[
o;;0;[o;	;[I"-{Creating}[rdoc-ref:FileUtils@Creating].;To;;0;[o;	;[I"-{Deleting}[rdoc-ref:FileUtils@Deleting].;To;;0;[o;	;[I"-{Querying}[rdoc-ref:FileUtils@Querying].;To;;0;[o;	;[I"+{Setting}[rdoc-ref:FileUtils@Setting].;To;;0;[o;	;[I"/{Comparing}[rdoc-ref:FileUtils@Comparing].;To;;0;[o;	;[I"+{Copying}[rdoc-ref:FileUtils@Copying].;To;;0;[o;	;[I"){Moving}[rdoc-ref:FileUtils@Moving].;To;;0;[o;	;[I"+{Options}[rdoc-ref:FileUtils@Options].;T@S;;i;
I"
Creating;T@o;;;;[o;;0;[o;	;[I""::mkdir: Creates directories.;To;;0;[o;	;[I";::mkdir_p, ::makedirs, ::mkpath: Creates directories, ;TI"2also creating ancestor directories as needed.;To;;0;[o;	;[I"'::link_entry: Creates a hard link.;To;;0;[o;	;[I"&::ln, ::link: Creates hard links.;To;;0;[o;	;[I"/::ln_s, ::symlink: Creates symbolic links.;To;;0;[o;	;[I"?::ln_sf: Creates symbolic links, overwriting if necessary.;To;;0;[o;	;[I"8::ln_sr: Creates symbolic links relative to targets;T@S;;i;
I"
Deleting;T@o;;;;[o;;0;[o;	;[I";::remove_dir: Removes a directory and its descendants.;To;;0;[o;	;[I"V::remove_entry: Removes an entry, including its descendants if it is a directory.;To;;0;[o;	;[I"F::remove_entry_secure: Like ::remove_entry, but removes securely.;To;;0;[o;	;[I")::remove_file: Removes a file entry.;To;;0;[o;	;[I"%::rm, ::remove: Removes entries.;To;;0;[o;	;[I"<::rm_f, ::safe_unlink: Like ::rm, but removes forcibly.;To;;0;[o;	;[I"3::rm_r: Removes entries and their descendants.;To;;0;[o;	;[I":::rm_rf, ::rmtree: Like ::rm_r, but removes forcibly.;To;;0;[o;	;[I""::rmdir: Removes directories.;T@S;;i;
I"
Querying;T@o;;;;[o;;0;[o;	;[I"?::pwd, ::getwd: Returns the path to the working directory.;To;;0;[o;	;[I"R::uptodate?: Returns whether a given entry is newer than given other entries.;T@S;;i;
I"Setting;T@o;;;;[o;;0;[o;	;[I"/::cd, ::chdir: Sets the working directory.;To;;0;[o;	;[I",::chmod: Sets permissions for an entry.;To;;0;[o;	;[I"B::chmod_R: Sets permissions for an entry and its descendants.;To;;0;[o;	;[I"3::chown: Sets the owner and group for entries.;To;;0;[o;	;[I"K::chown_R: Sets the owner and group for entries and their descendants.;To;;0;[o;	;[I">::touch: Sets modification and access times for entries, ;TI"creating if necessary.;T@S;;i;
I"Comparing;T@o;;;;[o;;0;[o;	;[I"T::compare_file, ::cmp, ::identical?: Returns whether two entries are identical.;To;;0;[o;	;[I"A::compare_stream: Returns whether two streams are identical.;T@S;;i;
I"Copying;T@o;;;;[o;;0;[o;	;[I"/::copy_entry: Recursively copies an entry.;To;;0;[o;	;[I""::copy_file: Copies an entry.;To;;0;[o;	;[I"$::copy_stream: Copies a stream.;To;;0;[o;	;[I" ::cp, ::copy: Copies files.;To;;0;[o;	;[I"-::cp_lr: Recursively creates hard links.;To;;0;[o;	;[I"H::cp_r: Recursively copies files, retaining mode, owner, and group.;To;;0;[o;	;[I"C::install: Recursively copies files, optionally setting mode, ;TI"owner, and group.;T@S;;i;
I"Moving;T@o;;;;[o;;0;[o;	;[I"!::mv, ::move: Moves entries.;T@S;;i;
I"Options;T@o;;;;[
o;;0;[o;	;[I"O::collect_method: Returns the names of methods that accept a given option.;To;;0;[o;	;[I"B::commands: Returns the names of methods that accept options.;To;;0;[o;	;[I"K::have_option?: Returns whether a given method accepts a given option.;To;;0;[o;	;[I")::options: Returns all option names.;To;;0;[o;	;[I"G::options_of: Returns the names of the options for a given method.;T@S;;i;
I"Path Arguments;T@o;	;[I"9Some methods in \FileUtils accept _path_ arguments, ;TI":which are interpreted as paths to filesystem entries:;T@o;;;;[o;;0;[o;	;[I"9If the argument is a string, that value is the path.;To;;0;[o;	;[I"LIf the argument has method +:to_path+, it is converted via that method.;To;;0;[o;	;[I"KIf the argument has method +:to_str+, it is converted via that method.;T@S;;i;
I"About the Examples;T@o;	;[
I"7Some examples here involve trees of file entries. ;TI"5For these, we sometimes display trees using the ;TI"P{tree command-line utility}[https://en.wikipedia.org/wiki/Tree_(command)], ;TI"Bwhich is a recursive directory-listing utility that produces ;TI"7a depth-indented listing of files and directories.;T@o;	;[I"IWe use a helper method to launch the command and control the format:;T@o:RDoc::Markup::Verbatim;[	I"def tree(dirpath = '.')
;TI">  command = "tree --noreport --charset=ascii #{dirpath}"
;TI"  system(command)
;TI"	end
;T:@format0o;	;[I"To illustrate:;T@o;;[
I"tree('src0')
;TI"# => src0
;TI"#    |-- sub0
;TI"#    |   |-- src0.txt
;TI"#    |   `-- src1.txt
;TI"#    `-- sub1
;TI"#        |-- src2.txt
;TI"#        `-- src3.txt
;T;0S;;i;
I"'Avoiding the TOCTTOU Vulnerability;T@o;	;[	I":For certain methods that recursively remove entries, ;TI"3there is a potential vulnerability called the ;TI"a{Time-of-check to time-of-use}[https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use], ;TI"3or TOCTTOU, vulnerability that can exist when:;T@o;;;;[o;;0;[o;	;[I"NAn ancestor directory of the entry at the target path is world writable; ;TI",such directories include <tt>/tmp</tt>.;To;;0;[o;	;[I"4The directory tree at the target path includes:;T@o;;;;[o;;0;[o;	;[I"+A world-writable descendant directory.;To;;0;[o;	;[I"A symbolic link.;T@o;	;[I"LTo avoid that vulnerability, you can use this method to remove entries:;T@o;;;;[o;;0;[o;	;[I"8FileUtils.remove_entry_secure: removes recursively ;TI".if the target path points to a directory.;T@o;	;[I"'Also available are these methods, ;TI"8each of which calls \FileUtils.remove_entry_secure:;T@o;;;;[o;;0;[o;	;[I"@FileUtils.rm_r with keyword argument <tt>secure: true</tt>.;To;;0;[o;	;[I"AFileUtils.rm_rf with keyword argument <tt>secure: true</tt>.;T@o;	;[I"RFinally, this method for moving entries calls \FileUtils.remove_entry_secure ;TI"Aif the source and destination are on different file systems ;TI"?(which means that the "move" is really a copy and remove):;T@o;;;;[o;;0;[o;	;[I">FileUtils.mv with keyword argument <tt>secure: true</tt>.;T@o;	;[I"=\Method \FileUtils.remove_entry_secure removes securely ;TI"'by applying a special pre-process:;T@o;;;;[o;;0;[o;	;[	I"HIf the target path points to a directory, this method uses methods ;TI"'{File#chown}[rdoc-ref:File#chown] ;TI"+and {File#chmod}[rdoc-ref:File#chmod] ;TI"in removing directories.;To;;0;[o;	;[I"LThe owner of the target directory should be either the current process ;TI"or the super user (root).;T@o;	;[	I"FWARNING: You must ensure that *ALL* parent directories cannot be ;TI"Fmoved by other untrusted users.  For example, parent directories ;TI"Eshould not be owned by untrusted users, and should not be world ;TI"0writable except when the sticky bit is set.;T@o;	;[I"@For details of this security vulnerability, see Perl cases:;T@o;;;;[o;;0;[o;	;[I"S{CVE-2005-0448}[https://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2005-0448].;To;;0;[o;	;[I"S{CVE-2004-0452}[https://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2004-0452].;T:
@fileI"lib/fileutils.rb;T:0@omit_headings_from_table_of_contents_below0o;;[�;I"lib/un.rb;T;0;0;0[�[U:RDoc::Constant[i�I"VERSION;TI"FileUtils::VERSION;T:public0o;;[o;	;[I"The version number.;T;@�;0@�@cRDoc::NormalModule0[�[[I"
class;T[[;[9[I"cd;TI"lib/fileutils.rb;T[I"
chdir;T@�[I"
chmod;T@�[I"chmod_R;T@�[I"
chown;T@�[I"chown_R;T@�[I"cmp;T@�[I"collect_method;T@�[I"
commands;T@�[I"compare_file;T@�[I"compare_stream;T@�[I"	copy;T@�[I"copy_entry;T@�[I"copy_file;T@�[I"copy_stream;T@�[I"cp;T@�[I"
cp_lr;T@�[I"	cp_r;T@�[I"
getwd;T@�[I"have_option?;T@�[I"identical?;T@�[I"install;T@�[I"	link;T@�[I"link_entry;T@�[I"ln;T@�[I"	ln_s;T@�[I"
ln_sf;T@�[I"
ln_sr;T@�[I"
makedirs;T@�[I"
mkdir;T@�[I"mkdir_p;T@�[I"mkpath;T@�[I"	move;T@�[I"mv;T@�[I"options;T@�[I"options_of;T@�[I"pwd;T@�[I"remove;T@�[I"remove_dir;T@�[I"remove_entry;T@�[I"remove_entry_secure;T@�[I"remove_file;T@�[I"rm;T@�[I"	rm_f;T@�[I"	rm_r;T@�[I"
rm_rf;T@�[I"
rmdir;T@�[I"rmtree;T@�[I"safe_unlink;T@�[I"symlink;T@�[I"
touch;T@�[I"uptodate?;T@�[:protected[�[:private[�[I"
instance;T[[;[�[;[�[;[4[@�@�[@�@�[@�@�[@�@�[@�@�[@�@�[@�@�[@@�[@@�[@@�[@@�[@
@�[@@�[@@�[@@�[@@�[@@�[@@�[@@�[@@�[@@�[@ @�[@"@�[@$@�[@&@�[@(@�[@*@�[@,@�[@.@�[@0@�[@2@�[@8@�[@:@�[@<@�[@>@�[@@@�[@B@�[@D@�[@F@�[@H@�[@J@�[@L@�[@N@�[@P@�[@R@�[@T@�[@V@�[[I"StreamUtils_;To;;[�;@�;0@�[U:RDoc::Context::Section[i�0o;;[�;0;0[	@�I")lib/rubygems/ext/ext_conf_builder.rb;TI" lib/rubygems/uninstaller.rb;T@�@�cRDoc::TopLevel