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

FreeBSD Manual Pages


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

       File::Util - Easy, versatile, portable file handling

       version 4.161950

       File::Util provides a comprehensive toolbox of utilities	to automate
       all kinds of common tasks on files and directories.  Its	purpose	is to
       do so in	the most portable manner possible so that users	of this	module
       won't have to worry about whether their programs	will work on other
       operating systems and/or	architectures.	It works on Linux, Windows,
       Mac, BSD, Unix and others.

       File::Util is written purely in Perl, and requires no compiler or make
       utility on your system in order to install and run it.  It loads	a
       minimal amount of code when used, only pulling in support for lesser-
       used methods on demand.	It has no dependencies other than what comes
       installed with Perl itself.

       File::Util also aims to be as backward compatible as possible, running
       without problems	on Perl	installations as old as	5.006.	You are
       encouraged to run File::Util on Perl version 5.8	and above.

       After browsing this document, please have a look	at the other
       documentation.  (See DOCUMENTATION section below.)

	  # use	File::Util in your program
	  use File::Util;

	  # create a new File::Util object
	  my $f	= File::Util->new();

	  # read file into a variable
	  my $content =	$f->load_file( 'some_file.txt' );

	  # write content to a file
	  $f->write_file( 'some_other_file.txt'	=> 'Hello world!' );

	  # get	the contents of	a directory, 3 levels deep
	  my @songs = $f->list_dir( '~/Music' => { recurse => 1, max_depth => 3	} );

       You can do much more with File::Util than the examples above.  For an
       explanation of all the features available to you, take a	look at	these
       other reference materials:

	   The File::Util::Manual::Examples document has a long	list of	small,
	   reusable code snippets and techniques to use	in your	own programs.
	   This	is the "cheat sheet", and is a great place to get started
	   quickly.  Almost everything you need	is here.

       Complete	API Reference
	   The File::Util::Manual is the complete reference document
	   explaining every available feature and object method.  Use this to
	   look	up the full information	on any given feature when the examples
	   aren't enough.

	   The File::Util::Cookbook contains examples of complete, working
	   programs that use File::Util	to easily accomplish tasks which
	   require file	handling.

   Getting Started
	  # use	File::Util in your program
	  use File::Util;

	  # can optionally enable File::Util's diagnostic error messages:
	  # (see File::Util::Manual section regarding diagnostics)
	  use File::Util qw( :diag );

	  # create a new File::Util object
	  my $f	= File::Util->new();

	  # can enable diagnostics for individual objects:
	  $f = File::Util->new(	diag =>	1 );

   File	Operations
	  # load file content into a scalar variable as	raw text
	  my $content =	$f->load_file( 'somefile.txt' );

	  # read a binary file the same	way
	  my $binary_content = $f->load_file( 'barking-cat.mp4'	);

	  # write a raw	text file
	  $f->write_file( 'somefile.txt' => $content );

	  # ...and write a binary file,	using some other options as well
	     'llama.jpg' => $picture_data => { binmode => 1, bitmask =>	oct 644	}

	  # ...or write	a file with UTF-8 encoding (unicode support)
	  $f->write_file( 'encoded.txt'	=> qq(\x{c0}) => { binmode => 'utf8' } );

	  # load a file	into an	array, line by line
	  my @lines = $f->load_file( 'file.txt'	=> { as_lines => 1 } );

	  # see	if you have permission to write	to a file, then	append to it
	  if ( $f->is_writable(	'captains.log' ) ) {

	     my	$fh = $f->open_handle( 'captains.log' => 'append' );

	     print $fh "Captain's log, stardate	41153.7.  Our destination is...";

	     close $fh or die $!;
	  else { # ...or warn the crew

	     warn "Trouble on the bridge, the Captain can't access his log!";

	  # get	the number of lines in a file
	  my $log_line_count = $f->line_count( '/var/log/messages' );

   File	Handles
	  # get	an open	file handle for	reading
	  my $fh = $f->open_handle( 'Ian likes cats.txt' => 'read' );

	  while	( my $line = <$fh> ) { # read the file,	line by	line
	     # ... do stuff

	  # get	an open	file handle for	writing	the same way
	  $fh =	$f->open_handle( 'John prefers dachshunds.txt' => 'write' );

	  # You	add the	option to turn on UTF-8	strict encoding	for your reads/writes
	  $fh =	$f->open_handle(
	     'John prefers dachshunds.txt' => 'write' => { binmode => 'utf8' }

	  print	$fh "Bob is happy! \N{U+263A}";	# << unicode smiley face!

	  # you	can use	sysopen	to get low-level with your file	handles	if needed
	  $fh =	$f->open_handle(
	     'alderaan.txt' => 'rwclobber' => {	use_sysopen => 1 }

	  syswrite $fh,	"that's	no moon";

	  # ...You can use any of these	syswrite modes with open_handle():
	  # read, write, append, rwcreate, rwclobber, rwappend,	rwupdate, and trunc

       PLEASE NOTE that	as of Perl 5.23, it is deprecated to mix system	IO
       (sysopen/syswrite/sysread/sysseek) with utf8 binmode (see perldoc
       perlport).  As such, File::Util will no longer allow you	to do this
       after version 4.132140.	Please see notes on UTF-8 and encoding further

	     'somefile.txt' => 'write' => { use_sysopen	=> 1, binmode => 'utf8'	}

	  # get	a listing of files, recursively, skipping directories
	  my @files = $f->list_dir( '/var/tmp' => { files_only => 1, recurse =>	1 } );

	  # get	a listing of text files, recursively
	  my @textfiles	= $f->list_dir(
	     '/var/tmp'	=> {
		files_match => qr/\.txt$/,
		files_only  => 1,
		recurse	    => 1,

	  # walk a directory, using an anonymous function or function ref as a callback
	  $f->list_dir(	'/home/larry' => {
	     recurse  => 1,
	     callback => sub {
		my ( $selfdir, $subdirs, $files	) = @_;
		# do stuff ...
	  } );

	  # get	an entire directory tree as a hierarchal datastructure reference
	  my $tree = $f->list_dir( '/my/podcasts' => { as_tree => 1 } );

   Getting Information About Files
	  print	'My file has a bitmask of ' . $f->bitmask( 'my.file' );

	  print	'My file is a '	. join(', ', $f->file_type( 'my.file' )) . " file.";

	  warn 'This file is binary!' if $f->is_bin( 'my.file' );

	  print	'My file was last modified on '	.
	     scalar localtime $f->last_modified( 'my.file' );

   Getting Information About Your System's IO Capabilities
	  # Does your running Perl support unicode?
	  print	'I support unicode' if $f->can_utf8;

	  # Can	your system use	file locking?
	  print	'I can use flock' if $f->can_flock;

	  # The	correct	directory separator for	your system
	  print	'The correct directory separator for this system is ' .	$f->SL;

	  # Does your platform require binmode for all IO?
	  print	'I always need binmode'	if $f->needs_binmode;

	  # Is your system an EBCDIC platform?	(see perldoc perlebcdic)
	  print	'This is an EBCDIC platform, so	be careful!' if	$f->EBCDIC;

       ...See the File::Util::Manual for more details and features like
       advanced	pattern	matching in directories, callbacks, directory walking,
       user-definable error handlers, and more.

   File	Encoding and UTF-8
       If you want to read/write in UTF-8, you can do that:

	  $ftl->load_file( 'file.txt' => $content => { binmode => 'utf8' } );

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

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

	  # ...and so on

       Only use	"binmode => 'utf8'" for	text.

       Encoding	and IO layers (sometimes called	disciplines) can become
       complex.	 It's not something you	usually	need to	worry about unless you
       wish to really fine tune	File::Util's behavior beyond what are very
       suitable, portable defaults, or accomplish very specific	tasks like
       encoding	conversions.

       You're free to specify any binmode you like, or allow File::Util	to use
       the system's default IO layering.  It will automatically	use the	":raw"
       pseudo layer when reading files that are	binary,	unless specifically
       told to use something different.

       You can control things as shown in the examples below:

	  $ftl->load_file( 'file.txt' => $content => { binmode => SPEC } );

	  $ftl->write_file( 'file.txt' => $content => {	binmode	=> SPEC	} );

	  $ftl->open_handle( 'file.txt'	=> 'read' => { binmode => SPEC } );

       ...where	"SPEC" is one or more of any supported IO layers on your
       system.	Examples might include:

       o   ':raw'

       o   ':unix'

       o   ':crlf'

       o   ':stdio'

       o   ':encoding(ENCODING)' with ENCODING's like iso-8859-1, shiftjis,

       o   ...and much more

       You can learn about the IO layers available to you and what they	do in
       the PerlIO perldoc.  Available options have increased over the years,
       and are likely subject to continued evolution.  Consult the PerlIO and
       Encode documentation as your authoritative source of info on what
       layers to use.

       File::Util consists of a	set of smaller modules,	but only loads the
       ones it needs when it needs them.  It offers a comparatively fast load-
       up time,	so using File::Util doesn't bloat your code's resource

       Additionally, File::Util	has been optimized to run fast.	 In many
       scenarios it does more and still	out-performs other popular IO modules.
       Benchmarking tools are included as part of the File::Util installation

       (See the	benchmarking and profiling scripts that	are included as	part
       of this distribution.)

       File::Util exposes the following	public methods.

       Each of which are covered in the	File::Util::Manual, which has more
       room for	the detailed explanation that is provided there.

       This is just an itemized	table of contents for HTML POD readers.	 For
       those viewing this document in a	text terminal, open perldoc to the

       atomize_path	    (see atomize_path)
       bitmask		    (see bitmask)
       can_flock	    (see can_flock)
       can_utf8		    (see can_utf8)
       created		    (see created)
       default_path	    (see default_path)
       diagnostic	    (see diagnostic)
       ebcdic		    (see ebcdic)
       escape_filename	    (see escape_filename)
       existent		    (see existent)
       file_type	    (see file_type)
       flock_rules	    (see flock_rules)
       is_bin		    (see is_bin)
       is_readable	    (see is_readable)
       is_writable	    (see is_writable)
       last_access	    (see last_access)
       last_changed	    (see last_changed)
       last_modified	    (see last_modified)
       line_count	    (see line_count)
       list_dir		    (see list_dir)
       load_dir		    (see load_dir)
       load_file	    (see load_file)
       make_dir		    (see make_dir)
       abort_depth	    (see abort_depth)
       needs_binmode	    (see needs_binmode)
       new		    (see new)
       onfail		    (see onfail)
       open_handle	    (see open_handle)
       read_limit	    (see read_limit)
       return_path	    (see return_path)
       size		    (see size)
       split_path	    (see split_path)
       strict_path	    (see strict_path)
       strip_path	    (see strip_path)
       touch		    (see touch)
       trunc		    (see trunc)
       unlock_open_handle   (see unlock_open_handle)
       use_flock	    (see use_flock)
       valid_filename	    (see valid_filename)
       write_file	    (see write_file)

       Exports nothing by default.  File::Util fully respects your namespace.
       You can,	however, ask it	for certain things (below).

       The following symbols comprise @File::Util::EXPORT_OK, and as such are
       available for import to your namespace only upon	request.  They can be
       used either as object methods or	like regular subroutines in your

	  -  atomize_path      -  can_flock	    -  can_utf8
	  -  created	       -  default_path	    -  diagnostic
	  -  ebcdic	       -  escape_filename   -  existent
	  -  file_type	       -  is_bin	    -  is_readable
	  -  is_writable       -  last_access	    -  last_changed
	  -  last_modified     -  needs_binmode	    -  strict_path
	  -  return_path       -  size		    -  split_path
	  -  strip_path	       -  valid_filename    -  NL and S	L

       To get any of these functions/symbols into your namespace without
       having to use them as object methods, use this kind of syntax:

	  use File::Util qw( strip_path	return_path existent size );

	  my $file  = $ARGV[0];
	  my $fname = strip_path( $file	);
	  my $path  = return_path( $file );
	  my $size  = size( $file );

	  print	qq(File	"$fname" exists	in "$path", and	is $size bytes in size)
	     if	existent( $file	);

	  :all (imports	all of @File::Util::EXPORT_OK to your namespace)

	  :diag	(imports nothing to your namespace, it just enables diagnostics)

       You can use these tags alone, or	in combination with other symbols as
       shown above.

       None.  There are	no external prerequisite modules.
	   File::Util only depends on modules that are part of the Core	Perl
	   distribution, and you don't need a compiler on your system to
	   install it.

       File::Util recommends Perl 5.8.1	or better ...
	   You can technically run File::Util on older versions	of Perl	5, but
	   it isn't recommended, especially if you want	unicode	support	and
	   wish	to take	advantage of File::Util's ability to read and write
	   files using UTF-8 encoding.

	   Unicode::UTF8 is also recommended and helps speed things up in
	   several places where	you might choose to use	unicode	as described
	   elsewhere in	the File::Util::Manual.

       To install this module type the following at the	command	prompt:

	  perl Build.PL
	  perl Build
	  perl Build test
	  sudo perl Build install

       On Windows systems, the "sudo" part of the command may be omitted, but
       you will	need to	run the	rest of	the install command with
       Administrative privileges

       Send bug	reports	and patches to the CPAN	Bug Tracker for	File::Util at <>

       If you want to get help,	contact	the authors (links below in AUTHORS

       I fully endorse <> as an	excellent source of
       help with Perl in general.

       The project website for File::Util is at

       The git repository for File::Util is on Github at

       Clone it	at <git://>

       This project was	a private endeavor for too long	so don't hesitate to
       pitch in.

       The following people have contributed to	File::Util in the form of
       feedback, encouragement,	recommendations, testing, or assistance	with
       problems	either on or offline in	one form or another.  Listed in	no
       particular order:

       o   John	Fields <>

       o   BrowserUk <>

       o   Ricardo SIGNES <>

       o   Matt	S Trout	<>

       o   Nicholas Perez <>

       o   David Golden	<>

       Tommy Butler <>

       Others Welcome!

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

       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.

       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.

       This disclaimer applies to every	part of	the File::Util distribution.

       The rest	of the documentation: File::Util::Manual,
       File::Util::Manual::Examples, File::Util::Cookbook

       Other Useful Modules that do similar things: File::Slurp, File::Spec,
       File::Find::Rule, Path::Class, Path::Tiny

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


Want to link to this manual page? Use this URL:

home | help