Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::Util::Manual(3) User Contributed Perl DocumentationFile::Util::Manual(3)

NAME
       File::Util::Manual - File::Util Reference

VERSION
       version 4.161950

INTRODUCTION
       This manual is is the complete reference	to all available public
       methods for use in File::Util.  It also touches on a few	other topics
       as set forth below.

       For a "nutshell"-type reference full of actual small example code
       snippets, take a	look at	the File::Util::Manual::Examples

       For examples of full Programs using File::Util, take a look at the
       File::Util::Cookbook.

   The layout of the Manual
       Now we'll start out with	some brief notes about what File::Util is (and
       isn't), then we'll talk about the syntax	used in	File::Util.  After
       that we discuss custom error handling and diagnostics in	File::Util.
       Finally,	the rest of this document will cover File::Util's object
       methods,	one by one, with brief usage examples.

   What	File::Util Is
       File::Util is a "Pure Perl" library that	provides you with several
       easy-to-use tools to wrangle files and directories.  It has higher
       order methods (that's fancy talk	for saying that	you can	feed
       subroutine references to	some of	File::Util's object methods and	they
       will be treated like "callbacks").

       File::Util is mainly Object-Oriented Perl, but strives to be gentle and
       accommodating to	those who do not know about or who do not like "OO"
       interfaces.  As such, many of the object	methods	available in
       File::Util can also be imported into your namespace and used like
       regular subroutines to make short work of simple	tasks.

       For more	advanced tasks and features, you will need to use File::Util's
       object-oriented interface.  Don't worry,	it's easy, and there are
       plenty of examples here in the documentation to get you off to a	great
       and productive start.  If you run into trouble, help is available.

       File::Util tries	its best to adhere to these guiding principles:

       Be easy
	   Make	hard things easier and safer to	do while avoiding common
	   mistakes associated with file handling in Perl.  Code using
	   File::Util will automatically be abiding by best practices with
	   regard to Perl IO.

	   File::Util makes the	right decisions	for you	with regard to all the
	   little details involved in the vast majority	of file-related	tasks.
	   File	locking	is automatically performed for you!  File handles are
	   always lexically scoped.  Safe reads	and writes are performed with
	   hard	limits on the amount of	RAM you	are allowed to consume in your
	   process per file read.  (You	can adjust the limits.)

       Be portable
	   We make sure	that File::Util	is going to work on your computer or
	   virtual machine.  If	you run	Windows, Mac, Linux, BSD, some flavor
	   of Unix, etc...  File::Util should work right out of	the box.
	   There are currently no platforms where Perl runs that we do not
	   support.  If	Perl can run on	it, File::Util can run on it.  If you
	   want	unicode	support, however, you need to at least be running Perl
	   5.8 or better.

       Be compatible
	   File::Util has been around for a long time, and so has Perl.	 We'd
	   like	to think that this is because they are good things!  This
	   means there is a lot	of backward-compatibility to account for, even
	   within File::Util itself.

	   In the last several years, there has	never been a release of
	   File::Util that intentionally broke code running a previous
	   version.  We	are unaware of that even happening.  File::Util	is
	   written to support both old and new features, syntaxes, and
	   interfaces with full	backward-compatibility.

       Be helpful
	   If requested, File::Util outputs extremely detailed error messages
	   when	something goes wrong in	a File::Util operation.	 The
	   diagnostic error messages not only provide information about	what
	   went	wrong, but also	hints on how to	fix the	problem.

	   These error messages	can easily be turned on	and off.  See
	   DIAGNOSTICS for the details.

       Be Pure
	   File::Util uses no XS or C underpinnings that require you to	have a
	   compiler or make utility on your system in order to use it.	Simply
	   follow standard installation	procedures (INSTALLATION) and you're
	   done.  No compiling required.

   What	File::Util Is NOT
       File::Util offers significant performance increases over	other modules
       for most	directory-walking and searching, whether doing so in a single
       directory or in many directories	recursively. (See also the
       benchmarking and	profiling scripts included in the performance
       subdirectory as part of this distribution)*

       However File::Util is NOT a single-purpose file-finding/searching
       utility like File::Find::Rule which offers a handful of extra built-in
       search features that File::Util does not	give you out of	the box, such
       as searching for	files by owner/group or	size.  It is possible to
       accomplish the same things by taking advantage of File::Util's
       callbacks if you	want to, but this isn't	the "one thing"	File::Util was
       built to	do.

       *Sometimes it doesn't matter how	fast you can search through a
       directory 1000 times.  Performance alone	isn't the best criteria	for
       choosing	a module.

SYNTAX
       In the past, File::Util relied on an older method invocation syntax
       that was	not robust enough to support the newer features	that have been
       added since version 4.0.	 In addition to	making new features possible,
       the new syntax is more in keeping with what the Perl community has come
       to expect from its favorite modules, like Moose and DBIx::Class.

   OLD Syntax Example
	  # this legacy	syntax looks clunky and	kind of	smells like shell script
	  $f->list_dir(	'/some/dir', '--recurse', '--as-ref', '--pattern=[^\d]'	);

   NEW Syntax Example (Does Much More)
	  # This syntax	is much	more robust, and supports new features
	  $f->list_dir(
	     '/some/dir' => {
		files_match    => { or	=> [ qr/bender$/, qr/^flexo/   ] },
		parent_matches => { and	=> [ qr/^Planet/, qr/Express$/ ] },
		callback       => \&deliver_interstellar_shipment,
		files_only     => 1,
		recurse	       => 1,
		as_ref	       => 1,
	     }
	  )

       If you already have code	that uses the old syntax, DON'T	WORRY -- it's
       still fully supported behind the	scenes.	 However, for new code that
       takes advantage of new features like higher order functions
       (callbacks), or advanced	matching for directory listings, you'll	need
       to use the syntax as set	forth in this document.	 The old syntax	isn't
       covered here, because you shouldn't use it anymore.

       An Explanation Of The "Options Hashref"

       As shown	in the code example above, the new syntax uses hash references
       to specify options for calls to File::Util methods.  This documentation
       refers to these as the "options hashref".  The code examples below
       illustrates what	they are and how they are used.	 Advanced Perl
       programmers will	recognize these	right away.

       NOTE: "hashref" is short	for "hash reference".  Hash references use
       curly brackets and look like this:

	  my $hashref =	{ name => 'Larry', language => 'Perl', pet => 'Velociraptor' };

       File::Util uses these hash references as	argument modifiers that	allow
       you to enable or	disable	certain	features or behaviors, so you get the
       output you want,	like this:

	  my $result = $ftl->some_method_call( arg1, arg2, { options hashref } );
							   # ^^^^^^^^^^^^^^^ #

       A couple	of real	examples would look like this:

	  $ftl->write_file( '/some/file.txt', 'Hello World!', {	mode =>	'append' } );
							      #	^^^^^^^^^^^^^^^^ #

	  $ftl->list_dir( '/home/dangerian' => { recurse => 1, files_only => 1 } );
					       # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #

ERROR HANDLING
   Feature Summary
       Managing	potential errors is a big part of Perl IO.  File::Util gives
       you several options.  In	fact, every single call	to a File::Util	method
       which accepts an	"options hashref" can also include an error handling
       directive.  File::Util has some pre-defined error handling behaviors
       that you	can choose from, or you	can supply your	own error handler
       routine.	 This is accomplished via the "onfail" option.

       As an added convenience,	when you use this option with the File::Util
       constructor method, it sets the default error handling policy for all
       failures; in other words, you can set up	one error handler for
       everything and never have to worry about	it after that.

	  # Set	every error to cause a warning instead of dying	by default
	  my $ftl = File::Util->new( { onfail => 'warn'	} );

	  $ftl->write_file( 'C:\\' => 'woof!' ); # now this call will warn and not die

   Details
       The predefined "onfail" behaviors and their syntaxes are	covered	below.

       keyword:	"die"
	   This	is what	File::Util already does: it calls "CORE::die()"	with
	   an error message when it encounters a fatal error, and your program
	   terminates.

	   Example:

	      my $ftl =	File::Util->new( ... { onfail => 'die' } );

       keyword:	"zero"
	   When	you use	the predefined "zero" behavior as the "onfail"
	   handler, File::Util will return a zero value	(the integer 0)	if it
	   encounters a	fatal error, instead of	dying.	File::Util won't warn
	   about the error or abort execution.	You will just get a zero back
	   instead of what you would have gotten otherwise, and	execution will
	   continue as if no error happened.

	   Example:

	      my $content = File::Util->load_file( ... { onfail	=> 'zero' } );

       keyword:	"undefined"
	   When	you use	the predefined "undefined" behavior as the "onfail"
	   handler, if File::Util runs into a fatal error it will return
	   "undef".  Execution will not	be aborted, and	no warnings will be
	   issued.  A value of undef will just get sent	back to	the caller
	   instead of what you would have gotten otherwise.  Execution will
	   then	continue on as if no error happened.

	   Note: This option usually makes more	practical sense	than "onfail
	   => 'zero'"

	   Example:

	      my $handle = File::Util->open_handle( ...	{ onfail => 'undefined'	} );

       keyword:	"warn"
	   When	you use	the predefined "warn" behavior as the "onfail"
	   handler, File::Util will return "undef"  if it encounters a fatal
	   error, instead of dying.  Then File::Util will emit a warning with
	   details about the error, but	will not abort execution.  You will
	   just	get a warning message sent to STDERR and "undef" gets sent
	   back	to the caller instead of what you would	have gotten otherwise.
	   Other than the warning, execution will continue as if no error ever
	   happened.

	   Example:

	      my $write_ok = File::Util->write_file( ... { onfail => 'warn' } );

       keyword:	"message"
	   When	you use	the predefined "message" behavior as the "onfail"
	   handler, if File::Util runs into a fatal error it will return an
	   error message in the	form of	a string containing details about the
	   problem.  Execution will not	be aborted, and	no warnings will be
	   issued.  You	will just get an error message sent back to the	caller
	   instead of what you would have gotten otherwise.  Execution will
	   then	continue on as if no error happened.

	   Example:

	      my @files	= File::Util->list_dir(	... { onfail =>	'message' } );

       "subroutine reference"
	   If you supply a code	reference to the "onfail" option in a
	   File::Util method call, it will execute that	code if	it encounters
	   a fatal error.  You must supply a true code reference, as shown in
	   the examples	below, either to a named or anonymous subroutine.

	   The subroutine you specify will receive two arguments as its	input
	   in "@_".  The first will be the text	of the error message, and the
	   second will be a stack trace	in text	format.	 You can send them to
	   a logger, to	your sysadmin in an email alert, or whatever you
	   like-- because it is	*your* error handler.

	   WARNING!  If	you do not call	"die" or "exit"	at the end of your
	   error handler, File::Util will NOT exit, but	continue to execute.
	   When	you opt	to use this feature, you are fully responsible for
	   your	process' error handling	and post-error execution.

	   Examples using the constructor:

	      #	step 1)	define your custom error handler
	      sub politician_error_handler {

		 my ( $err, $stack ) = @_;

		 # do stuff like ...

		 $logger->debug( $stack	);

		 die 'We neither confirm nor deny that an IO error has happened.';
	      }

	      #	step 2)	apply your error handler
	      my $ftl =	File::Util->new( { onfail => \&politician_error_handler	} );

		 -OR-

	      #	Define and apply your error handler in one step:

	      my $ftl =	File::Util->new(
		 {
		    onfail => sub {
		       my ( $err, $stack ) = @_;

		       # do stuff ...
		    }
		 }
	      );

	   Examples in individual method calls:

	      $ftl->write_file(	'greedo' => 'try bargain' => { onfail => \&shoot_first } );

	      my $file_handle =	$ftl->open_handle(
		 '/this/might/not/work'	=> {
		    onfail => sub {
		       warn "Couldn't open first choice, trying	a backup plan...";
		       return $ftl->open_handle( '/this/one/should/work' );
		    }
		 }
	      );

DIAGNOSTICS
       When things go wrong, sometimes it's nice to get	as much	information as
       possible	about the error.  In "File::Util", you incur no	performance
       penalties by enabling more verbose error	messages.  In fact, you're
       encouraged to do	so.

       You can globally	enable diagnostic messages (for	every "File::Util"
       object you create), or on a per-object basis, or	even on	a per-call
       basis when you just want	to diagnose a problem with a single method
       invocation.  Here's how:

       Enable Diagnostics Globally
		  use File::Util qw( :diag );

       Enable Diagnostics Per-Object
		  my $ftl = File::Util->new( diag => 1 );

       Enable Diagnostics Temporarily
		  $ftl->diagnostic( 1 ); # turn	diagnostic mode	on

		  # ...	do some	troubleshooting	...

		  $ftl->diagnostic( 0 ); # turn	diagnostic mode	off

       Enable Diagnostics per-call
		  $ftl->load_file( 'abc.txt' =>	{ diag => 1 } );

METHODS
       Note: In	the past, some of the methods listed would state that they
       were autoloaded methods.	 This mechanism	has been changed in favor of
       more modern practices, in step with the evolution of computing over the
       last decade since File::Util was	first released.

       Methods listed in alphabetical order.

   "atomize_path"
       Syntax: "atomize_path( [/file/path or file_name]	)"
	   This	method is used internally by File::Util	to handle absolute
	   filenames on	different platforms in a portable manner, but it can
	   be a	useful tool for	you as well.

	   This	method takes a single string as	its argument.  The string is
	   expected to be a fully-qualified (absolute) or relative path	to a
	   file	or directory.  It carefully splits the string into three
	   parts: The root of the path,	the rest of the	path, and the final
	   file/directory named	in the string.

	   Depending on	the input, the root and/or path	may be empty strings.
	   The following table can serve as a guide in what to expect from
	   "atomize_path()"

	      +-------------------------+----------+--------------------+----------------+
	      |	 INPUT			|   ROOT   |   PATH-COMPONENT	|   FILE/DIR	 |
	      +-------------------------+----------+--------------------+----------------+
	      |	 C:\foo\bar\baz.txt	|   C:\	   |   foo\bar		|   baz.txt	 |
	      |	 /foo/bar/baz.txt	|   /	   |   foo/bar		|   baz.txt	 |
	      |	 ./a/b/c/d/e/f/g.txt	|	   |   ./a/b/c/d/e/f	|   g.txt	 |
	      |	 :a:b:c:d:e:f:g.txt	|   :	   |   a:b:c:d:e:f	|   g.txt	 |
	      |	 ../wibble/wombat.ini	|	   |   ../wibble	|   wombat.ini	 |
	      |	 ..\woot\noot.doc	|	   |   ..\woot		|   noot.doc	 |
	      |	 ../../zoot.conf	|	   |   ../..		|   zoot.conf	 |
	      |	 /root			|   /	   |			|   root	 |
	      |	 /etc/sudoers		|   /	   |   etc		|   sudoers	 |
	      |	 /			|   /	   |			|		 |
	      |	 D:\			|   D:\	   |			|		 |
	      |	 D:\autorun.inf		|   D:\	   |			|   autorun.inf	 |
	      +-------------------------+----------+--------------------+----------------+

   "bitmask"
       Syntax: "bitmask( [file name] )"
	   Gets	the bitmask of the named file, provided	the file exists. If
	   the file exists and is accessible, the bitmask of the named file is
	   returned in four digit octal	notation e.g.- 0644.  Otherwise,
	   returns "undef" if the file does not	exist or could not be
	   accessed.

   "can_flock"
       Syntax: "can_flock"
	   Returns 1 if	the current system claims to support "flock()" and if
	   the Perl process can	successfully call it.  (see "flock" in
	   perlfunc.)  Unless both of these conditions are true, a zero	value
	   (0) is returned.  This is a constant	method.	 It accepts no
	   arguments and will always return the	same value for the system on
	   which it is executed.

	   Note: Perl tries to support or emulate flock	whenever it can	via
	   available system calls, namely "flock"; "lockf"; or with "fcntl".

   "created"
       Syntax: "created( [file name] )"
	   Returns the time of creation	for the	named file in non-leap seconds
	   since whatever your system considers	to be the epoch.  Suitable for
	   feeding to Perl's built-in functions	"gmtime" and "localtime".
	   (see	"time" in perlfunc.)

   "diagnostic"
       Syntax: "diagnostic( [true / false value] )"
	   When	called without any arguments, this method returns a true or
	   false value to reflect the current setting for the use of
	   diagnostic (verbose)	error messages when a File::Util object
	   encounters errors.

	   When	called with a true or false value as its single	argument, this
	   tells the File::Util	object whether or not it should	enable
	   diagnostic error messages in	the event of a failure.	 A true	value
	   indicates that the File::Util object	will enable diagnostic mode,
	   and a false value indicates that it will not.  The default setting
	   for "diagnostic()" is 0 (NOT	enabled.)

	   see also DIAGNOSTICS

   "default_path"
       Syntax: "default_path( [string, string] )"
	   The second string argument is optional.

	   Works just like "strict_path", except that instead of returning
	   "undef" when	the argument passed in doesn't look like a path, it
	   will	return a default string	instead.  The default string returned
	   will	either be the built-in default path, or	the string you specify
	   as a	second argument	to this	method.

	   The default string returned by this method is '.' . SL (see SL)

	   This	means that on windows, the built-in default would be ".\"
	   whereas on a	POSIX-compliant	system (Linux, UNIX, Mac, etc) you
	   would get "./"

	   see also strict_path)

   "ebcdic"
       Syntax: "ebcdic"
	   Returns 1 if	the machine on which the code is running uses EBCDIC,
	   or returns 0	if not.	 (see perlebcdic.)  This is a constant method.
	   It accepts no arguments and will always return the same value for
	   the system on which it is executed.

   "escape_filename"
       Syntax: "escape_filename( [string], [escape char] )"
	   Returns it's	argument in an escaped form that is suitable for use
	   as a	filename.  Illegal characters (i.e.- any type of newline
	   character, tab, vtab, and the following "/ |	* " ? <	: > \"), are
	   replaced with [escape char] or "_" if no [escape char] is
	   specified.  Returns an empty	string if no arguments are provided.

   "existent"
       Syntax: "existent( [file	name] )"
	   Returns 1 if	the named file (or directory) exists.  Otherwise a
	   value of undef is returned.

	   This	works the same as Perl's built-in "-e" file test operator,
	   (see	"-X" in	perlfunc), it's	just easier for	some people to
	   remember.

   "file_type"
       Syntax: "file_type( [file name] )"
	   Returns a list of keywords corresponding to each of Perl's built in
	   file	tests (those specific to file types) for which the named file
	   returns true.  (see "-X" in perlfunc.)

	   The keywords	and their definitions appear below; the	order of
	   keywords returned is	the same as the	order in which the are listed
	   here:

	   "PLAIN	      File is a	plain file."
	   "TEXT	      File is a	text file."
	   "BINARY	      File is a	binary file."
	   "DIRECTORY	      File is a	directory."
	   "SYMLINK	      File is a	symbolic link."
	   "PIPE	      File is a	named pipe (FIFO)."
	   "SOCKET	      File is a	socket."
	   "BLOCK	      File is a	block special file."
	   "CHARACTER	      File is a	character special file."

   "flock_rules"
       Syntax: "flock_rules( [keyword list] )"
	   Sets	I/O race condition policy, or tells File::Util how it should
	   handle race conditions created when a file can't be locked because
	   it is already locked	somewhere else (usually	by another process).

	   An empty call to this method	returns	a list of keywords
	   representing	the rules that are currently in	effect for the object.

	   Otherwise, a	call should include a list containing your chosen
	   directive keywords in order of precedence.  The rules will be
	   applied in cascading	order when a File::Util	object attempts	to
	   lock	a file,	so if the actions specified by the first rule don't
	   result in success, the second rule is applied, and so on.

	   This	setting	can be dynamically changed at any point	in your	code
	   by calling this method as desired.

	   The default behavior	of File::Util is to try	and obtain an
	   exclusive lock on all file opens (if	supported by your operating
	   system).  If	a lock cannot be obtained, File::Util will throw an
	   exception and exit.

	   If you want to change that behavior,	this method is the way to do
	   it.	One common situation is	for someone to want their code to
	   first try for a lock, and failing that, to wait until one can be
	   obtained.  If that's	what you want, see the examples	after the
	   keywords list below.

	   Recognized keywords:

	   "NOBLOCKEX"
	       tries to	get an exclusive lock on the file without blocking
	       (waiting)

	   "NOBLOCKSH"
	       tries to	get a shared lock on the file without blocking

	   "BLOCKEX"
	       waits to	get an exclusive lock

	   "BLOCKSH"
	       waits to	get a shared lock

	   "FAIL"
	       dies with stack trace

	   "WARN"
	       warn()s about the error and returns undef

	   "IGNORE"
	       ignores the failure to get an exclusive lock

	   "UNDEF"
	       returns undef

	   "ZERO"
	       returns 0

	   Examples:

	   ex- "flock_rules( qw( NOBLOCKEX FAIL	) );"
	       This is the default policy.  When in effect, the	File::Util
	       object will first attempt to get	a non-blocking exclusive lock
	       on the file.  If	that attempt fails the File::Util object will
	       call die() with an error.

	   ex- "flock_rules( qw( NOBLOCKEX BLOCKEX FAIL	) );"
	       The File::Util object will first	attempt	to get a non-blocking
	       exclusive lock on the file.  If that attempt fails it falls
	       back to the second policy rule "BLOCKEX"	and tries again	to get
	       an exclusive lock on the	file, but this time by blocking
	       (waiting	for its	turn).	If that	second attempt fails, the
	       File::Util object will fail with	an error.

	   ex- "flock_rules( qw( BLOCKEX IGNORE	) );"
	       The File::Util object will first	attempt	to get a file non-
	       blocking	lock on	the file.  If that attempt fails it will
	       ignore the error, and go	on to open the file anyway and no
	       failures	or warnings will occur.

   "is_bin"
       Syntax: "is_bin(	[file name] )"
	   Returns 1 if	the named file (or directory) exists.  Otherwise a
	   value of undef is returned, indicating that the named file either
	   does	not exist or is	of another file	type.

	   This	works the same as Perl's built-in "-B" file test operator,
	   (see	"-X" in	perlfunc), it's	just easier for	some people to
	   remember.

   "is_readable"
       Syntax: "is_readable( [file name] )"
	   Returns 1 if	the named file (or directory) is readable by your
	   program according to	the applied permissions	of the file system on
	   which the file resides.  Otherwise a	value of undef is returned.

	   This	works the same as Perl's built-in "-r" file test operator,
	   (see	"-X" in	perlfunc), it's	just easier for	some people to
	   remember.

   "is_writable"
       Syntax: "is_writable( [file name] )"
	   Returns 1 if	the named file (or directory) is writable by your
	   program according to	the applied permissions	of the file system on
	   which the file resides.  Otherwise a	value of undef is returned.

	   This	works the same as Perl's built-in "-w" file test operator,
	   (see	"-X" in	perlfunc), it's	just easier for	some people to
	   remember.

   "last_access"
       Syntax: "last_access( [file name] )"
	   Returns the last accessed time for the named	file in	non-leap
	   seconds since whatever your system considers	to be the epoch.
	   Suitable for	feeding	to Perl's built-in functions "gmtime" and
	   "localtime".	 (see "time" in	perlfunc.)

   "last_changed"
       Syntax: "last_changed( [file name] )"
	   Returns the inode change time for the named file in non-leap
	   seconds since whatever your system considers	to be the epoch.
	   Suitable for	feeding	to Perl's built-in functions "gmtime" and
	   "localtime".	 (see "time" in	perlfunc.)

   "last_modified"
       Syntax: "last_modified( [file name] )"
	   Returns the last modified time for the named	file in	non-leap
	   seconds since whatever your system considers	to be the epoch.
	   Suitable for	feeding	to Perl's built-in functions "gmtime" and
	   "localtime".	 (see "time" in	perlfunc.)

   "line_count"
       Syntax: "line_count( [file name]	)"
	   Returns the number of lines in the named file.  Fails with an error
	   if the named	file does not exist.

   "list_dir"
       Syntax: "list_dir( [directory name] => {	option => value, ... } )"
	   Returns all file names in the specified directory, sorted in
	   alphabetical	order.	Fails with an error if no such directory is
	   found, or if	the directory is inaccessible.

	   Note	that this is one of File::Util's most robust methods, and can
	   be very useful.  It can be used as a	higher order function
	   (accepting callback subrefs), and can be used for advanced pattern
	   matching against files.  It can also	return a hierarchical data
	   structure of	the file tree you ask it to walk.

	   See the File::Util::Manual::Examples	for several useful ways	to use
	   "list_dir()".

	   Syntax example to recursively return	a list of subdirectories in
	   directory "dir_name":

	      my @dirs = $f->list_dir( 'dir_name' => { dirs_only => 1, recurse => 1 } );

	   Options accepted by "list_dir()"
	       "callback => subroutine reference"
		   "list_dir()"	can accept references to subroutines of	your
		   own.	 If you	pass it	a code reference using this option,
		   File::Util will execute your	code every time	list_dir()
		   enters a directory.	This is	particularly useful when
		   combined with the "recurse" option which is explained
		   below.

		   When	you create a callback function,	the File::Util will
		   pass	it four	arguments in this order: The name of the
		   current directory, a	reference to a list of subdirectories
		   in the current directory, a reference to a list of files in
		   the current directory, and the depth	(positive integer)
		   relative to the directory you provided as your first
		   argument to "list_dir()".  This means if you	pass in	a path
		   such	as "/var/tmp", that "/var/tmp" is at a depth of	0,
		   "/var/tmp/foo" is 1 deep, and so on down through the
		   "/var/tmp" directory.

		   Remember that the code in your callback gets	executed in
		   real	time, as list_dir() is walking the directory tree.
		   Consider this example:

		      #	Define a subroutine to print the byte size and depth of	all files in a
		      #	directory, designed to be used as a callback function to list_dir()

		      sub filesize {
			 my ( $selfdir,	$subdirs, $files, $depth ) = @_;

			 print "$_ | " . ( -s $_ ) . " | $depth	levels deep\n" for @$files;
		      }

		      #	Now list directory recursively,	invoking the callback on every recursion

		      $f->list_dir( './droids' => { recurse => 1, callback => \&filesize } );

		      #	Output would look something like
		      #
		      #	  ./droids/by-owner/luke/R2.spec | 1024	| 3 deep
		      #	  ./droids/by-owner/luke/C2P0.spec | 2048 | 3 deep
		      #	  ./droids/by-boss/dooku/Grievous.spec | 4096 |	3 deep
		      #	  ./droids/by-series/imperial/sentries/R5.spec | 1024 |	4 deep
		      #
		      #	Depth breakdown
		      #
		      #	   level 0 => ./droids/
		      #	   level 1 => ./droids/by-owner/
		      #	   level 1 => ./droids/by-boss/
		      #	   level 1 => ./droids/by-series/
		      #	   level 2 => ./droids/by-owner/luke/
		      #	   level 2 => ./droids/by-boss/dooku/
		      #	   level 2 => ./droids/by-series/imperial/
		      #	   level 3 => ./droids/by-series/imperial/sentries/

		   Another way to use callbacks	is in combination with
		   closures, to	"close around" a variable or variables defined
		   in the same scope as	the callback.  A demonstration of this
		   technique is	shown below:

		      {
			 my $size_total;
			 my $dir = 'C:\Users\superman\projects\scripts_and_binaries';

			 # how many total bytes	are in all of the executable files in $dir

			 $f->list_dir(
			    $dir => {
			       callback	=> sub {
				  my ( $selfdir, $subdirs, $files, $depth ) = @_;

				  $size_total += -s $_ for grep	{ -B $_	} @$files;
			       }
			    }
			 );

			 print "There's	$size_total bytes of binary files in my	projects dir.";
		      }

	       "d_callback => subroutine reference"
		   A "d_callback" is just like a "callback", except it is only
		   executed on directories encountered in the file tree, not
		   files, and its input	is slightly different.	@_ is
		   comprised of	(in order) the name of the current directory,
		   a reference to a list of all	subdirectories in that
		   directory, and the depth (positive integer) relative	to the
		   top level directory in the path you provided	as your	first
		   argument to "list_dir".

	       "f_callback => subroutine reference"
		   Similarly an	"f_callback" is	just like a "callback",	except
		   it is only concerned	with files encountered in the file
		   tree, not directories.  It's	input is also slightly
		   different.  @_ is comprised of (in order) the name of the
		   current directory, a	reference to a list of all files
		   present in that directory, and the depth (positive integer)
		   relative to the top level directory in the path you
		   provided as your first argument to "list_dir".

	       "dirs_only => boolean"
		   return only directory contents which	are also directories

	       "files_only => boolean"
		   return only directory contents which	are files

	       "max_depth => positive integer"
		   Works just like the "-maxdepth" flag	in the GNU find
		   command.  This option tells "list_dir()" to limit results
		   to directories at no	more than the maximum depth you
		   specify.  This only works in	tandem with the	"recurse"
		   option (or the "recurse_fast" option	which is similar).

		   For compatibility reasons, you can use ""maxdepth"" without
		   the underscore instead, and get the same functionality.

	       "no_fsdots => boolean"
		   do not include "." and ".." in the list of directory
		   contents returned

	       "abort_depth => positive	integer"
		   Override the	global limit on	abort_depth recursions for
		   directory listings, on a per-listing	basis with this
		   option.  Just like the main "abort_depth()" object method,
		   this	option takes a positive	integer.  The default is 1000.
		   Sometimes it	is useful to increase this number by quite a
		   lot when walking directories	with callbacks.

	       "with_paths => boolean"
		   Return results with the preceding file paths	intact,
		   relative to the directory named in the call.

	       "recurse	=> boolean"
		   Recurse into	subdirectories.	 In other words, open up
		   subdirectories and continue to descend into the directory
		   tree	either as far as it goes, or until the "abort_depth"
		   limit is reached. See abort_depth()

	       "recurse_fast =>	boolean"
		   Recurse into	subdirectories,	without	checking for
		   filesystem loops.  This works exactly like the "recurse"
		   option, except it turns off internal	checking for duplicate
		   inodes while	descending through a file tree.

		   You get a performance boost at the sacrifice	of a little
		   "safety checking".

		   The bigger your file	tree, the more performance gains you
		   see.

		   This	option has no effect on	Windows. (see perldoc -f stat)

	       "dirs_as_ref => boolean"
		   When	returning directory listing, include first a reference
		   to the list of subdirectories found,	followed by anything
		   else	returned by the	call.

	       "files_as_ref =>	boolean"
		   When	returning directory listing, include last a reference
		   to the list of files	found, preceded	by a list of
		   subdirectories found	(or preceded by	a list reference to
		   subdirectories found	if "dirs_as_ref" was also used).

	       "as_ref => boolean"
		   Return a pair list references: the first is a reference to
		   any subdirectories found by the call, the second is a
		   reference to	any files found	by the call.

	       "sl_after_dirs => boolean"
		   Append a directory separator	("/, "\", or ":" depending on
		   your	system)	to all directories found by the	call.  Useful
		   in visual displays for quick	differentiation	between
		   subdirectories and files.

	       "ignore_case => boolean"
		   Return items	in a case-insensitive alphabetic sort order,
		   as opposed to the default.

		   **By	default, items returned	by the call to this method are
		   alphabetically sorted in a case-insensitive manner, such
		   that	"Zoo.txt" comes	before "alligator.txt".	 This is also
		   the way files are listed at the system level	on most
		   operating systems.

		   However, if you'd like the directory	contents returned by
		   this	method to be sorted without regard to case, use	this
		   option.  That way, "alligator.txt" will come	before
		   "Zoo.txt".

	       "count_only => boolean"
		   Returns a single value: an integer reflecting the number of
		   items found in the directory	after applying any filter
		   criteria that may also have been specified by other options
		   (i.e.- "dirs_only", "recurse", etc.)

	       "as_tree	=> boolean"
		   Returns a hierarchical data structure (hashref) of the file
		   tree	in the directory you specify as	the first argument to
		   "list_dir()".  Use in combination with other	options	to get
		   the exact results you want in the data structure.

		   *Note: When using this option, the "files_only" and
		   "dirs_only" options are ignored, but	you can	still specify
		   things like a "max_depth" argument, however.	 Note also
		   that	you need to specifically call this with	the "recurse"
		   or "recurse_fast" option or you will	only get a single-
		   level tree structure.

		   One quick example:

		      my $tree = $ftl->list_dir(
			 '/tmp'	=> {
			    as_tree  =>	1,
			    recurse  =>	1,
			 }
		      );

		      #	output would look something like this if you Data::Dumper'd it
		      {
			'/' => {
				 '_DIR_PARENT_'	=> undef,
				 '_DIR_SELF_' => '/',
				 'tmp' => {
					    '_DIR_PARENT_' => '/',
					    '_DIR_SELF_' => '/tmp',
					    'hJMOsoGuEb' => {
							      '_DIR_PARENT_' =>	'/tmp',
							      '_DIR_SELF_' => '/tmp/hJMOsoGuEb',
							      'a.txt' => '/tmp/hJMOsoGuEb/a.txt',
							      'b.log' => '/tmp/hJMOsoGuEb/b.log',
							      'c.ini' => '/tmp/hJMOsoGuEb/c.ini',
							      'd.bat' => '/tmp/hJMOsoGuEb/d.bat',
							      'e.sh' =>	'/tmp/hJMOsoGuEb/e.sh',
							      'f.conf' => '/tmp/hJMOsoGuEb/f.conf',
							      'g.bin' => '/tmp/hJMOsoGuEb/g.bin',
							      'h.rc' =>	'/tmp/hJMOsoGuEb/h.rc',
							    }
					  }
			       }
		      }

		   When	using this option, the hashref you get back will have
		   certain metadata entries at each level of the hierarchy,
		   namely there	will be	two special keys: "_DIR_SELF", and
		   "_DIR_PARENT_".  Their values will be the name of the
		   directory itself, and the name of its parent, respectively.

		   That	metadata can be	extremely helpful when iterating over
		   and parsing the hashref later on, but if you	don't want the
		   metadata, include the "dirmeta" option and set it to	a zero
		   (false) value as shown below:

		      my $tree = $ftl->list_dir(
			 '/some/dir' =>	{
			    as_tree  =>	1,
			    recurse  =>	1,
			    dirmeta  =>	0,
			 }
		      );

		   **Remember: the "as_tree" doesn't recurse into
		   subdirectories unless you tell it to	with "recurse => 1"

	   Filtering and Matching with "list_dir()"
	       "list_dir()" can	use Perl Regular Expressions to	match against
	       and thereby filter the results it returns.  It can match	based
	       on file name, directory name, the path preceding	results, and
	       the parent directory of results.	 The matching arguments	you
	       use must	be real	regular	expression references as shown (i.e.-
	       NOT strings).

	       Regular expressions can be provided as a	single argument	value,
	       or a specifically crafted hashref designating a list of
	       patterns	to match against in either an "or" manner, or an
	       "and"ed cumulative manner.

	       Some short examples of proper syntax will be provided after the
	       list of matching	options	below.

	       **If you	experience a big slowdown in directory listings	while
	       using regular expressions, check	to make	sure your regular
	       expressions are properly	written	and optimized.	In general,
	       directory listings should not be	slow or	resource-intensive.
	       Badly-written regular expressions will result in	considerable
	       slowdowns and bottlenecks in any	application.

	       "files_match => qr/regexp/"
	       OR: "files_match	=> { and/or => [ qr/listref of/, qr/regexps/ ]
	       }"
		   Return only file names matching the regex(es).  Preceding
		   directories are included in the results; for	technical
		   reasons they	are not	excluded (if they were excluded,
		   "list_dir()"	would not be able to "cascade" or recurse into
		   subdirectories in search of matching	files.

		   Use the "files_only"	option in combination with this
		   matching parameter to exclude the preceding directory
		   names.

	       "dirs_match => qr/regexp/"
	       OR: "dirs_match => { and/or => [	qr/listref of/,	qr/regexps/ ]
	       }"
		   Return only files and subdirectory names in directories
		   that	match the regex(es) you	specify.  BE CAREFUL with this
		   one!!  It doesn't "cascade" the way you might expect; for
		   technical reasons, it won't descend into directories	that
		   don't match the regex(es) you provide.  For example,	if you
		   want	to match a directory name that is three	levels deep
		   against a given pattern, but	don't know (or don't care
		   about) the names of the intermediate	directories-- THIS IS
		   NOT THE OPTION YOU ARE LOOKING FOR.	Use the	"path_matches"
		   option instead.

		   *NOTE: Bear in mind that just because you tell "list_dir()"
		   to match each directory against the regex(es) you specify
		   here, that doesn't mean you are telling it to only show
		   directories in its results.	You will get file names	in
		   matching directories	included in the	results	as well,
		   unless you combine this with	the "dirs_only"	option.

	       "path_matches =>	qr/regexp/"
	       OR: "path_matches => { and/or =>	[ qr/listref of/, qr/regexps/
	       ] }"
		   Return only files and subdirectory names with preceding
		   paths that match the	regex(es) you specify.

	       "parent_matches => qr/regexp reference/"
	       OR: "parent_matches => {	and/or => [ qr/listref of/,
	       qr/regexps/ ] }"
		   Return only files and subdirectory names whose parent
		   directory matches the regex(es) you specify.

	   Examples of matching	and filtering results in "listdir()"
	       Single-argument matching	examples

		  my @files = $f->list_dir(
		     '../notes'	=> { files_match => qr/\.txt$/i, files_only => 1 }
		  );

		  my @dirs = $f->list_dir(
		     '/var' => {
			dirs_match => qr/log|spool/i,
			recurse	=> 1,
			dirs_only => 1,
		     }
		  );

		  my @dirs = $f->list_dir(
		     '/home' =>	{
			path_matches =>	qr/Desktop/,
			recurse	=> 1,
			dirs_only => 1,
		     }
		  );

		  my @files = $f->list_dir(
		     '/home/tommy/projects' => {
			parent_matches => qr/^\.git$/,
			recurse	=> 1,
		     }
		  );

	       A multiple-argument matching examples with OR

		  my @files = $f->list_dir(
		     'C:\Users\Billy G'	=> {
			parent_matches => { or => [ qr/Desktop/, qr/Pictures/ ]	}
			recurse	=> 1,
		     }
		  );

		  # ...	same concepts apply to "files_match", "dirs_match",
		  #	and "parent_matches" filtering

	       Multiple-argument matching examples with	AND

		  my @files = $f->list_dir(
		     '/home/leia' => {
			parent_matches => { and	=> [ qr/Anakin/, qr/Amidala/ ] }
			recurse	=> 1,
		     }
		  );

		  my @files = $f->list_dir(
		     '/home/mace' => {
			path_matches =>	{ and => [ qr/^(?!.*dark.side)/i, qr/[Ff]orce/ ] }
			recurse	=> 1,
		     }
		  );

		  # ...	same concepts apply to "files_match" and "dirs_match" filtering

	       **When you specify regexes for more than	one filter type
	       parameter, the patterns are AND'ed together, as you'd expect,
	       and all matching	criteria must be satisfied for a successful
	       overall match.

		  my @files = $f->list_dir(
		     '/var' => {
			dirs_match     => { or => [ qr/^log$/,	 qr/^lib$/    ]	},
			files_match    => { or => [ qr/^syslog/, qr/\.isam$/i ]	},
			parent_matches => qr/[[:alpha:]]+/
			path_matches   => qr/^(?!.*home)/,
			recurse	    => 1,
			files_only  => 1,
		     }

	       Negative	matches	(when you want to NOT match something) - use
	       Perl!

	       As shown	in the File::Util::Manual::Examples, Perl already
	       provides	support	for negated matching in	the form of "zero-
	       width negative assertions".  (See perlre	for details on how
	       they work).  Use	syntax like the	regular	expressions below to
	       match anything that is NOT part of the subpattern.

		  # match all files with names that do NOT contain "apple" (case sensitive)
		  my @no_apples	= $f->list_dir(
		     'Pictures/fruit' => { files_match => qr/^(?!.*apple)/ }
		  );

		  # match all files that that do NOT end in *.mp3 (case	INsensitive)
		  # also, don't	match files that end in	*.wav either
		  my @no_music = $f->list_dir(
		     '/opt/music' => {
			files_match => { and =>	[ qr/^(?!.*mp3$)/i, qr/^(?!.*wav$)/i ]
		     }
		  );

   "load_dir"
       Syntax: "load_dir( [directory name] => {	options	} )"
	   Returns a data structure containing the contents of each file
	   present in the named	directory.

	   The type of data structure returned is determined by	the optional
	   data-type option parameter.	Only one option	at a time may be used
	   for a given call to this method.  Recognized	options	are listed
	   below.

	      my $files_hash_ref = $f->load_dir( $dirname ); # default (hashref)

		 -OR-

	      my $files_list_ref = $f->load_dir( $dirname => { as_listref => 1 } );

		 -OR-

	      my @files	= $f->load_dir(	$dirname => { as_list => 1 } );

	   Options accepted by "load_dir()"
	       "as_hashref => boolean" *(default)
		   Implicit.  If no option is passed in, the default behavior
		   is to return	a reference to an anonymous hash whose keys
		   are the names of each file in the specified directory; the
		   hash	values for contain the contents	of the file
		   represented by its corresponding key.

	       "as_list	=> boolean"
		   Causes the method to	return a list comprised	of the
		   contents loaded from	each file (in case-sensitive order)
		   located in the named	directory.

		   This	is useful in situations	where you don't	care what the
		   filenames were and you just want a list of file contents.

	       "as_listref => boolean"
		   Same	as above, except an array reference to the list	of
		   items is returned rather than the list itself.  This	is
		   more	efficient than the above, particularly when dealing
		   with	large lists.

	       "load_dir()" does not recurse or	accept matching	parameters,
	       etc.  It's an effective tool for	loading	up things like a
	       directory of template files on a	web server, or to store	binary
	       data streams in memory.	Use it however you like.

	       However,	if you do want to load files into a hashref/listref or
	       array while using the advanced features of "list_dir()",	just
	       use list_dir to return the files	and map	the contents into your
	       variable:

		  my $hash_ref = {};

		  %$hash_ref = map { $_	=> $ftl->load_file( $_ ) }
			       $ftl->list_dir( $dir_name => { advanced options... } );

	   Note: This method does not distinguish between plain	files and
	   other file types such as binaries, FIFOs, sockets, etc.

	   Restrictions	imposed	by the current "read limit" (see the
	   read_limit()) entry below will be applied to	the individual files
	   opened by this method as well.  Adjust the read limit as necessary.

	   Example usage:

	      my $templates = $f->load_dir( 'templates/stock-ticker' );

	   The above code creates an anonymous hash reference that is stored
	   in the variable named "$files".  The	keys and values	of the hash
	   referenced by "$files" would	resemble those of the following	code
	   snippet (given that the files in the	named directory	were the files
	   'a.txt', 'b.html', 'c.dat', and 'd.conf')

	      my $files	=
		 {
		    'a.txt'  =>	'the contents of file a.txt',
		    'b.html' =>	'the contents of file b.html',
		    'c.dat'  =>	'the contents of file c.dat',
		    'd.conf' =>	'the contents of file d.conf',
		 };

   "load_file"
       Syntax: "load_file( [file name] => { options } )"
       OR: "load_file( file_handle => [file handle reference] => { options }
       )"
	   If [file name] is passed, returns the contents of [file name] in a
	   string.  If a [file handle reference] is passed instead, the
	   filehandle will be "CORE::read()" and the data obtained by the read
	   will	be returned in a string.

	   If you desire the contents of the file (or file handle data)	in a
	   list	of lines instead of a single string, this can be accomplished
	   through the use of the "as_lines" option (see below).

	   Options accepted by "load_file()"
	       "as_lines => boolean"
		   If this option is enabled then your call to "load_file"
		   will	return a list of strings, each one of which is a line
		   as it was read from the file	[file name].  The lines	are
		   returned in the order they are read,	from the beginning of
		   the file to the end.

		   This	is not the default behavior.  The default behavior is
		   for "load_file" to return a single string containing	the
		   entire contents of the file.

	       "no_lock	=> boolean"
		   By default this method will attempt to get a	lock on	the
		   file	while it is being read,	following whatever rules are
		   in place for	the flock policy established either by default
		   (implicitly)	or changed by you in a call to
		   File::Util::flock_rules() (see the flock_rules()) entry
		   below.

		   This	method will not	try to get a lock on the file if the
		   File::Util object was created with the option "no_lock" or
		   if the method was called with the option "no_lock".

		   This	method will automatically call binmode() on binary
		   files for you.  If you pass in a filehandle instead of a
		   file	name you do not	get this automatic check performed for
		   you.	 In such a case, you'll	have to	call binmode() on the
		   filehandle yourself.	 Once you pass a filehandle to this
		   method it has no way	of telling if the file opened to that
		   filehandle is binary	or not.

	       "binmode	=> [ boolean or	'utf8' ]"
		   Tell	File::Util to read the file in binmode (if set to a
		   true	boolean: 1), or	to read	the file as UTF-8 encoded
		   data, specify a value of "utf8" to this option.  (see
		   "binmode" in	perlfunc).

		   You need Perl 5.8 or	better to use 'utf8' or	your program
		   will	fail with an error message.

		   Example Usage:

		      my $encoded_data = $ftl->load_file( 'encoded.txt'	=> { binmode =>	'utf8' } );

	       "read_limit => positive integer"
		   Override the	global read limit setting for the File::Util
		   object you are working with,	on a one time basis.  By
		   specifying a	this option with a positive integer value
		   (representing the maximum number of bytes to	allow for your
		   "load_file()" call),	you are	telling	"load_file()" to
		   ignore the global/default setting for just that call, and
		   to apply your one-time limit	of [ positive integer ]	bytes
		   on the file while it	is read	into memory.

		   Notes: This method does not distinguish between plain files
		   and other file types	such as	binaries, FIFOs, sockets, etc.

		   Restrictions	imposed	by the current "read limit" (see the
		   read_limit()) entry below will be applied to	the files
		   opened by this method.  Adjust the read limit as necessary
		   either by overriding	(using the 'read_limit'	option above),
		   or by adjusting the global value for	your File::Util	object
		   with	the provided read_limit() object method.

   "make_dir"
       Syntax: "make_dir( [new directory name],	[bitmask] => { options } )"
	   Attempts to create (recursively) a directory	as [new	directory
	   name] with the [bitmask] provided.  The bitmask is an optional
	   argument and	defaults to oct	777, combined with the current user's
	   umask.  If specified, the bitmask must be supplied in the form
	   required by the native perl umask function (as an octal number).
	   see "umask" in perlfunc for more information	about the format of
	   the bitmask argument.

	   As mentioned	above, the recursive creation of directories is
	   transparently handled for you.  This	means that if the name of the
	   directory you pass in contains a parent directory that does not
	   exist, the parent directory(ies) will be created for	you
	   automatically and silently in order to create the final directory
	   in the [new directory name].

	   Simply put, if [new directory] is "/path/to/directory" and the
	   directory "/path/to"	does not exist,	the directory "/path/to" will
	   be created and the "/path/to/directory" directory will be created
	   thereafter.	All directories	created	will be	created	with the
	   [bitmask] you specify, or with the default of oct 777, combined
	   with	the current user's umask.

	   Upon	successful creation of the [new	directory name], the [new
	   directory name] is returned to the caller.

	   Options accepted by "make_dir()"
	       "if_not_exists => boolean"
		   Example:

		      $f->make_dir( '/home/jspice' => oct 755 => { if_not_exists => 1 }	);

		   If this option is enabled then make_dir will	not attempt to
		   create the directory	if it already exists.  Rather it will
		   return the name of the directory as it normally would if
		   the directory did not exist previous	to calling this
		   method.

		   If a	call to	this method is made without the
		   "if_not_exists" option and the directory specified as [new
		   directory name] does	in fact	exist, an error	will result as
		   it is impossible to create a	directory that already exists.

   "abort_depth"
       Syntax: "abort_depth( [positive integer]	)"
	   When	called without any arguments, this method returns an integer
	   reflecting the current number of times the File::Util object	will
	   dive	into the subdirectories	it discovers when recursively listing
	   directory contents from a call to "File::Util::list_dir()".	The
	   default is 1000.  If	the number is exceeded,	the File::Util object
	   will	fail with an error.

	   When	called with an argument, it sets the maximum number of times a
	   File::Util object will recurse into subdirectories before failing
	   with	an error message.

	   This	method can only	be called with a numeric integer value.
	   Passing a bad argument to this method will cause it to fail with an
	   error.

	   (see	also: list_dir)

   "needs_binmode"
       Syntax: "needs_binmode"
	   Returns 1 if	the machine on which the code is running requires that
	   "binmode()" (a built-in function) be	called on open file handles,
	   or returns 0	if not.	 (see "binmode"	in perlfunc.)  This is a
	   constant method.  It	accepts	no arguments and will always return
	   the same value for the system on which it is	executed.

   "new"
       Syntax: "new( { options } )"
	   This	is the File::Util constructor method.  It returns a new
	   File::Util object reference when you	call it.  It recognizes
	   various options that	govern the behavior of the new File::Util
	   object.

	   Parameters accepted by "new()"
	       "use_flock => boolean"
		   Optionally specify this option to the "File::Util::new"
		   method to instruct the new object that it should never
		   attempt to use "flock()" in it's I/O	operations.  The
		   default is to use "flock()" if available on your system.
		   Specify this	option with a true or false value ( 1 or 0 ),
		   true	to use "flock()", false	to not use it.

	       "read_limit => positive integer"
		   Optionally specify this option to the File::Util::new
		   method to instruct the new object that it should never
		   attempt to open and read in a file greater than the number
		   of bytes you	specify.  This argument	can only be a numeric
		   integer value, otherwise it will be silently	ignored.  The
		   default read	limit for File::Util objects is	52428800 bytes
		   (50 megabytes).

	       "abort_depth => positive	integer"
		   Optionally specify this option to the File::Util::new
		   method to instruct the new object to	set the	maximum	number
		   of times it will recurse into subdirectories	while
		   performing directory	listing	operations before failing with
		   an error message.  This argument can	only be	a numeric
		   integer value, otherwise it will be silently	ignored.

		   (see	also: abort_depth())

	       "onfail => designated handler"
		   Set the default policy for how the new File::Util object
		   handles fatal errors.  This option takes any	one of a list
		   of predefined keywords, or a	reference to a named or
		   anonymous error handling subroutine of your own.

		   You can supply an "onfail" handler to nearly	any function
		   in File::Util, but when you do so for the "new()"
		   constructor,	you are	setting	the default.

		   Acceptable values are all covered in	the ERROR HANDLING
		   section (above), along with proper syntax and example
		   usage.

   "onfail"
       Syntax: "onfail(	[keyword or code reference] )"
	   Dynamically set/change the default error handling policy for	an
	   object.

	   This	works exactly the same as it does when you specify an "onfail"
	   handler to the constructor method (see also "new").

	   The syntax and keywords available to	use for	this method are
	   already discussed above in the ERROR	HANDLING section, so refer to
	   that	for in-depth details.

	   Here	are some examples:

	      $ftl->onfail( 'die' );

	      $ftl->onfail( 'zero' );

	      $ftl->onfail( 'undefined'	);

	      $ftl->onfail( 'message' );

	      $ftl->onfail( \&subroutine_reference );

	      $ftl->onfail( sub	{ my ( $error, $stack_trace ) =	@_; ...	} );

   "open_handle"
       Syntax: "open_handle( [file name] => [mode] => {	options	} )"
       OR: "open_handle( file => [file name] =>	mode =>	[mode] => { options }
       )"
	   Attempts to get a lexically scoped open file	handle on [file	name]
	   in [mode] mode.  Returns the	file handle if successful or generates
	   a fatal error with a	diagnostic message if the operation fails.

	   You will need to remember to	call "close()" on the filehandle
	   yourself, at	your own discretion.  Leaving filehandles open is not
	   a good practice, and	is not recommended.  see "close" in perlfunc).

	   Once	you have the file handle you would use it as you would use any
	   file	handle.	 Remember that unless you specifically turn file
	   locking off when the	"File::Util" object is created (see new) or by
	   using the "no_lock" option when calling "open_handle", that file
	   locking is going to automagically be	handled	for you	behind the
	   scenes, so long as your OS supports file locking of any kind	at
	   all.	 Great!	 It's very convenient for you to not have to worry
	   about portability in	taking care of file locking between one
	   application and the next; by	using "File::Util" in all of them, you
	   know	that you're covered.

	   A slight inconvenience for the price	of a larger set	of features
	   (compare write_file to this method) you will	have to	release	the
	   file	lock on	the open handle	yourself.  "File::Util"	can't manage
	   it for you anymore once it turns the	handle over to you.  At	that
	   point, it's all yours.  In order to release the file	lock on	your
	   file	handle,	call unlock_open_handle() on it.  Otherwise the	lock
	   will	remain for the life of your process.  If you don't want	to use
	   the free portable file locking, remember the	"no_lock" option,
	   which will turn off file locking for	your open handle.  Seldom,
	   however, should you ever opt	to not use file	locking	unless you
	   really know what you	are doing.  The	only obvious exception would
	   be if you are working with files on a network-mounted filesystem
	   like	NFS or SMB (CIFS), in which case locking can be	buggy.

	   If the file does not	yet exist it will be created, and it will be
	   created with	a bitmask of [bitmask] if you specify a	file creation
	   bitmask using the 'bitmask' option, otherwise the file will be
	   created with	the default bitmask of oct 777.	 The bitmask is
	   combined with the current user's umask, whether you specify a value
	   or not.  This is a function of Perl,	not File::Util.

	   If specified, the bitmask must be supplied in the form of an	octal
	   number as required by the native perl umask function.  See "umask"
	   in perlfunc for more	information about the format of	the bitmask
	   argument.  If the file [file	name] already exists then the bitmask
	   argument has	no effect and is silently ignored.

	   Any non-existent directories	in the path preceding the actual file
	   name	will be	automatically (and silently - no warnings) created for
	   you and any new directories will be created with a bitmask of
	   [dbitmask], provided	you specify a directory	creation bitmask with
	   the 'dbitmask' option.

	   If specified, the directory creation	bitmask	[dbitmask] must	be
	   supplied in the form	required by the	native perl umask function.

	   If there is an error	while trying to	create any preceding
	   directories,	the failure results in a fatal error with an error.
	   If all directories preceding	the name of the	file already exist,
	   the dbitmask	argument has no	effect and is silently ignored.

       Native Perl open	modes
	   The default behavior	of "open_handle()" is to open file handles
	   using Perl's	native "open()"	(see "open" in perlfunc).  Unless you
	   use the "use_sysopen" option, only then are the following modes
	   valid:

	   "mode => 'read'" (this is the default mode)
	       [file name] is opened in	read-only mode.	 If the	file does not
	       yet exist then a	fatal error will occur.

	   "mode => 'write'"
	       [file name] is created if it does not yet exist.	 If [file
	       name] already exists then its contents are overwritten with the
	       new content provided.

	   "mode => 'append'"
	       [file name] is created if it does not yet exist.	 If [file
	       name] already exists its	contents will be preserved and the new
	       content you provide will	be appended to the end of the file.

       System level open modes ("open a	la C")
	   Optionally you can ask "File::Util" to open your handle using
	   "CORE::sysopen" instead of using the	native Perl "CORE::open()".
	   This	is accomplished	by enabling the	"use_sysopen" option.  Using
	   this	feature	opens up more possibilities as far as the open modes
	   you can choose from,	but also carries with it a few caveats so you
	   have	to be careful, just as you'd have to be	a little more careful
	   when	using "sysopen()" anyway.

	   Specifically	you need to remember that when using this feature you
	   must	NOT mix	different types	of I/O when working with the file
	   handle.  You	can't go opening file handles with "sysopen()" and
	   print to them as you	normally would print to	a file handle.	You
	   have	to use "syswrite()" instead.  The same applies here.  If you
	   get a "sysopen()"'d filehandle from "open_handle()" it is
	   imperative that you use "syswrite()"	on it.	You'll also need to
	   use "sysseek()" and other type of "sys"* commands on	the filehandle
	   instead of their native Perl	equivalents.

	   (see	"sysopen" in perlfunc, "syswrite" in perlfunc, "sysseek" in
	   perlfunc, "sysread" in perlfunc)

	   That	said, here are the different modes you can choose from to get
	   a file handle when using the	"use_sysopen" option.  Remember	that
	   these won't work unless you use that	option,	and will generate an
	   error if you	try using them without it.  The	standard 'read',
	   'write', and	'append' modes are already available to	you by
	   default.  These are the extended modes:

	   "mode => 'rwcreate'"
	       [file name] is opened in	read-write mode, and will be created
	       for you if it does not already exist.

	   "mode => 'rwupdate'"
	       [file name] is opened for you in	read-write mode, but must
	       already exist.  If it does not exist, a fatal error will
	       result.

	   "mode => 'rwclobber'"
	       [file name] is opened for you in	read-write mode.  If the file
	       already exists it's contents will be "clobbered"	or wiped out.
	       The file	will then be empty and you will	be working with	the
	       then-truncated file.  This can not be undone.  Once you call
	       "open_handle()" using this option, your file WILL be wiped out.
	       If the file does	not exist yet, it will be created for you.

	   "mode => 'rwappend'"
	       [file name] will	be opened for you in read-write	mode ready for
	       appending.  The file's contents will not	be wiped out; they
	       will be preserved and you will be working in append fashion.
	       If the file does	not exist, it will be created for you.

	   Remember to use "sysread()" and not plain "read()" when reading
	   those "sysopen()"'d filehandles!

       Options accepted	by "open_handle()"
	   "binmode => [ boolean or 'utf8' ]"
	       Tell File::Util to open the file	in binmode (if set to a	true
	       boolean:	1), or to open the file	with UTF-8 encoding, specify a
	       value of	"utf8" to this option.	(see "binmode" in perlfunc).

	       You need	Perl 5.8 or better to use "utf8" or your program will
	       fail with an error message.

	       Example Usage:

		  $ftl->open_handle( 'encoded.txt' => {	binmode	=> 'utf8' } );

	   "no_lock => boolean"
	       By default this method will attempt to get a lock on the	file
	       while it	is being read, following whatever rules	are in place
	       for the flock policy established	either by default (implicitly)
	       or changed by you in a call to File::Util::flock_rules()	(see
	       flock_rules()).

	       This method will	not try	to get a lock on the file if the
	       File::Util object was created with the option "no_lock" or if
	       this method is called with the option "no_lock".

	   "use_sysopen	=> boolean"
	       Instead of opening the file using Perl's	native "open()"
	       command,	"File::Util" will open the file	with the "sysopen()"
	       command.	 You will have to remember that	your filehandle	is a
	       "sysopen()"'d one, and that you will not	be able	to use native
	       Perl I/O	functions on it.  You will have	to use the "sys"*
	       equivalents.  See perlopentut for a more	in-depth explanation
	       of why you can't	mix native Perl	I/O with system	I/O.

   "read_limit"
       Syntax: "read_limit( [positive integer] )"
	   By default, the largest size	file that File::Util will read into
	   memory and return via the load_file is 52428800 bytes (50
	   megabytes).

	   This	value can be modified by calling this method with an integer
	   value reflecting the	new limit you want to impose, in bytes.	 For
	   example, if you want	to set the limit to 10 megabytes, call the
	   method with an argument of 10485760.

	   If this method is called without an argument, the read limit
	   currently in	force for the File::Util object	will be	returned.

   "return_path"
       Syntax: "return_path( [string] )"
	   Takes the file path from the	file name provided and returns it such
	   that	"/who/you/callin/scruffy.txt" is returned as
	   "/who/you/callin".

	   This	method is optimized for	speed and returns anything that	could
	   possibly be a file path, even if that means the path	is actually
	   "foo.bar" if	you passed it such an argument.	 Technically, you
	   could indeed	have a directory named "blaster.txt", so this method
	   doesn't distinguish between strings that look like file names and
	   ones	that don't.

	   If you want one that	does, you need to use "strict_path()" instead.
	   (see	strict_path)

   "size"
       Syntax: "size( [file name] )"
	   Returns the file size of [file name]	in bytes.  Returns 0 if	the
	   file	is empty. Returns "undef" if the file does not exist.

   "split_path"
       Syntax: "split_path( [string] )"
	   Takes a path/filename, fully-qualified or relative (it doesn't
	   matter), and	it returns a list comprising the root of the path (if
	   any), each directory	in the path, and the final part	of the path
	   (be it a file, a directory, or otherwise)

	   This	method doesn't divine or detect	any information	about the
	   path, it simply manipulates the string value.  It doesn't map it to
	   any real filesystem object.	It doesn't matter whether or not the
	   file/path named in the input	string exists or not.

   "strict_path"
       Syntax: "strict_path( [string] )"
	   Works just like "return_path()" except that it is more strict in
	   what	it returns.  If	you pass it a string that does not "look" like
	   a path (a string with no directory separators or that is not	"." or
	   ".."), then this method will	return "undef".

	   If you'd like to get	a default path string returned instead of
	   "undef", then you want to use the "default_path()" method instead.

	   (see	also return_path and default_path)

   "strip_path"
       Syntax: "strip_path( [string] )"
	   Strips the file path	from the file name provided and	returns	the
	   file	name only.

	   Given "/kessel/run/12/parsecs", it returns "parsecs"

	   Given "C:\you\scoundrel", it	returns	"scoundrel"

   "touch"
       Syntax: "touch( [file name] )"
	   Behaves like	the *nix "touch" command; Updates the access and
	   modification	times of the specified file to the current time.  If
	   the file does not exist, "File::Util" tries to create it empty.
	   This	method will fail with a	fatal error if system permissions deny
	   alterations to or creation of the file.

	   Returns 1 if	successful.  If	unsuccessful, fails with an error.

   "trunc"
       Syntax: "trunc( [file name] )"
	   Truncates [file name] (i.e.-	wipes out, or "clobbers" the contents
	   of the specified file.)  Returns 1 if successful.  If unsuccessful,
	   fails with a	descriptive error message about	what went wrong.

   "unlock_open_handle"
       Syntax: "unlock_open_handle([file handle])"
	   Release the flock on	a file handle you opened with open_handle.

	   Returns true	on success, false on failure.  Will not	raise a	fatal
	   error if the	unlock operation fails.	 You can capture the return
	   value from your call	to this	method and "die()" if you so desire.
	   Failure is not ever very likely, or "File::Util" wouldn't have been
	   able	to get a portable lock on the file in the first	place.

	   If "File::Util" wasn't able to ever lock the	file due to
	   limitations of your operating system, a call	to this	method will
	   return a true value.

	   If file locking has been disabled on	the file handle	via the
	   "no_lock" option at the time	open_handle was	called,	or if file
	   locking was disabled	using the use_flock method, or if file locking
	   was disabled	on the entire "File::Util" object at the time of its
	   creation (see new()), calling this method will have no effect and a
	   true	value will be returned.

   "use_flock"
       Syntax: "use_flock( [true / false value]	)"
	   When	called without any arguments, this method returns a true or
	   false value to reflect the current use of "flock()" within the
	   File::Util object.

	   When	called with a true or false value as its single	argument, this
	   method will tell the	File::Util object whether or not it should
	   attempt to use "flock()" in its I/O operations.  A true value
	   indicates that the File::Util object	will use "flock()" if
	   available, a	false value indicates that it will not.	 The default
	   is to use "flock()" when available on your system.

	   DON'T USE FLOCK ON NETWORK FILESYSTEMS
	       If you are working with files on	an NFS mount, or a Windows
	       file share, it is quite likely that using flock will be buggy
	       and cause unexpected failures in	your program.  You should not
	       use flock in such situations.

	   A WORD OF CAUTION FOR SOLARIS USERS
	       File locking has	known issues on	SOLARIS.  Solaris claims to
	       offer a native "flock()"	implementation,	but after obtaining a
	       lock on a file, Solaris will very often just silently refuse to
	       unlock it again until your process has completely exited.  This
	       is not an issue with File::Util or even with Perl itself.
	       Other programming languages encounter the same problems;	it is
	       a system-level issue.  So please	be aware of this if you	are a
	       Solaris user and	want to	use file locking on your OS.

	       You may have to explicitly disable file locking completely.

   "write_file"
       Syntax: "write_file( [file name]	=> [string] => { other_options } )"
       OR: "write_file(	{ file => [file	name], content => [string], mode =>
       [mode], other_options } )"
	   Syntax Examples:

	      #	get some content (a string returned from a function call, perhaps)
	      my $answer = ask_commissioner( 'Can he be	trusted?' );

	      $ftl->write_file(	'Harvey_Dent.txt' => $answer );

		 -OR-

	      #	get some binary	content, maybe a picture...
	      my $binary_data =	get_mugshot( alias => 'twoface'	);

	      $ftl->write_file(	'suspect.png' => $binary_data => { binmode => 1	} );

		 -OR-

	      #	write a	file with UTF-8	encoding (unicode character support)
	      $ftl->write_file(	'encoded.txt' => $encoded_data => { binmode => 'utf8' }	);

		 -OR-

	      $ftl->write_file(
		 {
		    file    => '/gotham/city/ballots/Bruce_Wayne.txt',
		    content => 'Vote for Harvey!',
		    bitmask => oct 600,	# <- secret ballot file	permissions
		 }
	      );

	   Attempts to write [string] to [file name] in	mode [mode].  If the
	   file	does not yet exist it will be created, and it will be created
	   with	a bitmask of [bitmask] if you specify a	file creation bitmask
	   using the 'bitmask' option, otherwise the file will be created with
	   the default bitmask of oct 777.  The	bitmask	is combined with the
	   current user's umask, whether you specify a value or	not.  This is
	   a function of Perl, not File::Util.

	   [string] should be a	string or a scalar variable containing a
	   string.  The	string can be any type of data,	such as	a binary
	   stream, or ascii text with line breaks, etc.	 Be sure to enable the
	   "binmode => 1" option for binary streams, and be sure to specify a
	   value of "binmode =>	'utf8'"	for UTF-8 encoded data.

	   NOTE: that you will need Perl version 5.8 or	better to use the
	   'utf8' feature, or your program will	fail with an error.

	   If specified, the bitmask must be supplied in the form of an	octal
	   number, as required by the native perl umask	function.  see "umask"
	   in perlfunc for more	information about the format of	the bitmask
	   argument.  If the file [file	name] already exists then the bitmask
	   argument has	no effect and is silently ignored.

	   Returns 1 if	successful or fails with an error if not successful.

	   Any non-existent directories	in the path preceding the actual file
	   name	will be	automatically (and silently - no warnings) created for
	   you and new directories will	be created with	a bitmask of
	   [dbitmask], provided	you specify a directory	creation bitmask with
	   the 'dbitmask' option.

	   If specified, the directory creation	bitmask	[dbitmask] must	be
	   supplied in the form	required by the	native perl umask function.

	   If there is a problem while trying to create	any preceding
	   directories,	the failure results in a fatal error.  If all
	   directories preceding the name of the file already exist, the
	   dbitmask argument has no effect and is silently ignored.

	   "mode => 'write'" (this is the default mode)
	       [file name] is created if it does not yet exist.	 If [file
	       name] already exists then its contents are overwritten with the
	       new content provided.

	   "mode => 'append'"
	       [file name] is created if it does not yet exist.	 If [file
	       name] already exists its	contents will be preserved and the new
	       content you provide will	be appended to the end of the file.

	   Options accepted by "write_file()"
	       "binmode	=> [ boolean or	'utf8' ]"
		   Tell	File::Util to write the	file in	binmode	(if set	to a
		   true	boolean: 1), or	to write the file with UTF-8 encoding,
		   specify a value of "utf8" to	this option.  (see "binmode"
		   in perlfunc).

		   You need Perl 5.8 or	better to use "utf8" or	your program
		   will	fail with an error message.

		   Example Usage:

		      $ftl->write_file(	'encoded.txt' => $encoded_data => { binmode => 'utf8' }	);

	       "empty_writes_OK	=> boolean"
		   Allows you to call this method without providing a content
		   argument (it	lets you create	an empty file without warning
		   you or failing.  Be advised that if you enable this option,
		   it will have	the same effect	as truncating a	file that
		   already has content in it (i.e.- it will "clobber" non-
		   empty files)

	       "no_lock	=> boolean"
		   By default this method will attempt to get a	lock on	the
		   file	while it is being read,	following whatever rules are
		   in place for	the flock policy established either by default
		   (implicitly)	or changed by you in a call to
		   File::Util::flock_rules() (see flock_rules()).

		   This	method will not	try to get a lock on the file if the
		   File::Util object was created with the option "no_lock" or
		   if this method is called with the option "no_lock" enabled.

   "valid_filename"
       Syntax: "valid_filename(	[string] )"
	   For the given string, returns 1 if the string is a legal file name
	   for the system on which the program is running, or returns undef if
	   it is not.  This method does	not test for the validity of file
	   paths!  It tests for	the validity of	file names only.  (It is used
	   internally to check beforehand if a file name is usable when
	   creating new	files, but is also a public method available for
	   external use.)

CONSTANTS
   "NL"
       Syntax: "NL"
	   Short for "New Line".  Returns the correct new line character (or
	   character sequence) for the system on which your program runs.

   "SL"
       Syntax: "SL"
	   Short for "Slash". Returns the correct directory path separator for
	   the system on which your program runs.

   "OS"
       Syntax: "OS"
	   Returns the File::Util keyword for the operating system FAMILY it
	   detected.  The keyword for the detected operating system will be
	   one of the following, derived from the contents of $^O, or if $^O
	   can not be found, from the contents of $Config::Config{osname} (see
	   native Config library), or if that doesn't contain a	recognizable
	   value, finally falls	back to	"UNIX".

	   Generally speaking, Linux operating systems are going to be
	   detected as "UNIX".	This isn't a bug.  The OS FAMILY to which it
	   belongs uses	"UNIX" style filesystem	conventions and	line endings,
	   which are the relevant things to file handling operations.

	   UNIX
	       Specifics: OS name =~ /^(?:darwin|bsdos)/i

	   CYGWIN
	       Specifics: OS name =~ /^cygwin/i

	   WINDOWS
	       Specifics: OS name =~ /^MSWin/i

	   VMS Specifics: OS name =~ /^vms/i

	   DOS Specifics: OS name =~ /^dos/i

	   MACINTOSH
	       Specifics: OS name =~ /^MacOS/i

	   EPOC
	       Specifics: OS name =~ /^epoc/i

	   OS2 Specifics: OS name =~ /^os2/i

AUTHORS
       Tommy Butler <http://www.atrixnet.com/contact>

COPYRIGHT
       Copyright(C) 2001-2013, Tommy Butler.  All rights reserved.

LICENSE
       This library is free software, you may redistribute it and/or modify it
       under the same terms as Perl itself. For	more details, see the full
       text of the LICENSE file	that is	included in this distribution.

LIMITATION OF WARRANTY
       This software is	distributed in the hope	that it	will be	useful,	but
       without any warranty; without even the implied warranty of
       merchantability or fitness for a	particular purpose.

SEE ALSO
       File::Util::Cookbook, File::Util::Manual::Examples, File::Util

perl v5.32.1			  2016-07-13		 File::Util::Manual(3)

NAME | VERSION | INTRODUCTION | SYNTAX | ERROR HANDLING | DIAGNOSTICS | METHODS | CONSTANTS | AUTHORS | COPYRIGHT | LICENSE | LIMITATION OF WARRANTY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::Util::Manual&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help