NAME

       NetSDS::Util::File - file related utilities

SYNOPSIS

               use NetSDS::Util::File qw(file_read);

               my $passwd = file_read('/etc/passwd');

               file_move('/etc/passwd', '/tmp/find_this');

DESCRIPTION

       "NetSDS::Util::File" module contains some routines for files and directories processing
       tasks like creating, reading, writing, copying and moving files and catalogs.

       This module of cource uses such well known things like File::Spec, File::Path, File::Copy
       and others.

EXPORTED FUNCTIONS

       is_handle($var) - check if argument is a file handle
           Parameters: some variable

           Returns: 1 if it's file handle or undef otherwise

                   if (is_handle($var)) {

                           reset_handle($fh);

                   }

       reset_handle($fh) - reset file handle
           Parameters: file handle

           Returns: nothing

           This function tries to set filehandle to begin of file and set binmode on it.

                   my $fh = file_open('/etc/passwd');
                   ...
                   do something with file
                   ...
                   reset_handle($fh); # We can read it from the beginning

       file_open($file) - open file
           Parameters: file name or file handle

           Returns: file handle

           This function provides unified API for opening files.

                   my $f = file_open('/etc/passwd');

       file_read($file) - read file to scalar
           Parameters: file name or file handle

           Returns: scalar content of file

           This function provides ability to read file content to scalar variable.

                   my $data = file_read('/etc/passwd');

                   print "Passwords file: $data\n";

       file_write($file, $data) - write scalar data to file
           Parameters: file name or open file handle

           Returns: length of written data or undef in case of error

                   my $data = 'This should be file';

                   file_write('/tmp/file.dat', $data);

       file_copy($in_file, $out_file) - copy file
           Parameters: input file name, output file name

           Returns:

           This function copy file to new location.

       file_move($in_file, $out_file) - move file
           Parameters: input file name, output file name

           Returns: 1 or undef

           This function moves old file to new location.

       file_temp($dir) - create temporary file
           Creates new temp file and return its handle

       dir_create($dir) - create directory with parents
           Parameters: directory name

           Returns: directory name or undef

                   # Will create all parent catalogs if necessary

                   dir_create('/var/log/NetSDS/xxx');

       dir_delete($dir) - remove directory recursive
           Parameters: directory name

           Returns: dir name or undef if error

                   print "We need no libs!";

                   dir_delete('/usr/lib');

       dir_read($dir, $ext) - read files list from catalog
           Parameters: directory name, extension of files to read

           Returns: list of files in catalog

                   my @logs = @{ dir_read('/var/log/httpd', 'log') };

                   print "Logs are: " . join (', ', @logs);

       dir_read_recursive($dir, $ext, [$res]) - read all files list recursive
           Parameters: $start catalog, $extension

           Returns: list of files with extension from parameters

                   my $tpls = dir_read_recursive('/etc/NetSDS', 'tmpl');

                   foreach my $tpl (@$tpls) {

                           pritn "Template: $tpl\n";

                   }

       exec_external($prog, [$param1, ... $paramN]) - execute external program
           Parameters: pragram name, arguments list (see perldoc -f system)

           Returns: 1 if ok, undef otherwise

           This function calls system() with given parameters and returns 1 if everything
           happened correctly (program executed and returned correct result).

                   if (exec_external('/bin/rm', '-rf', '/')) {

                           print "Hey! We removed the world!";

                   }

EXAMPLES

       None yet

BUGS

       Unknown yet

SEE ALSO

       IO::Handle, IO::Scalar, IO::File, File::Spec, File::Copy, File::Path, system()

TODO

       1. Implement more detailed error handling

AUTHOR

       Valentyn Solomko <pere@pere.org.ua>

       Michael Bochkaryov <misha@rattler.kiev.ua>