.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NetSDS::Util::File 3pm"
.TH NetSDS::Util::File 3pm "2019-02-22" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
NetSDS::Util::File \- file related utilities
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use NetSDS::Util::File qw(file_read);
\&
\&        my $passwd = file_read(\*(Aq/etc/passwd\*(Aq);
\&
\&        file_move(\*(Aq/etc/passwd\*(Aq, \*(Aq/tmp/find_this\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`NetSDS::Util::File\*(C'\fR module contains some routines for files
and directories processing tasks like creating, reading, writing,
copying and moving files and catalogs.
.PP
This module of cource uses such well known things like File::Spec,
File::Path, File::Copy and others.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.IP "\fBis_handle($var)\fR \- check if argument is a file handle" 4
.IX Item "is_handle($var) - check if argument is a file handle"
Parameters: some variable
.Sp
Returns: 1 if it's file handle or undef otherwise
.Sp
.Vb 1
\&        if (is_handle($var)) {
\&
\&                reset_handle($fh);
\&
\&        }
.Ve
.IP "\fBreset_handle($fh)\fR \- reset file handle" 4
.IX Item "reset_handle($fh) - reset file handle"
Parameters: file handle
.Sp
Returns: nothing
.Sp
This function tries to set filehandle to begin of file and set binmode on it.
.Sp
.Vb 5
\&        my $fh = file_open(\*(Aq/etc/passwd\*(Aq);
\&        ...
\&        do something with file
\&        ...
\&        reset_handle($fh); # We can read it from the beginning
.Ve
.IP "\fBfile_open($file)\fR \- open file" 4
.IX Item "file_open($file) - open file"
Parameters: file name or file handle
.Sp
Returns: file handle
.Sp
This function provides unified \s-1API\s0 for opening files.
.Sp
.Vb 1
\&        my $f = file_open(\*(Aq/etc/passwd\*(Aq);
.Ve
.IP "\fBfile_read($file)\fR \- read file to scalar" 4
.IX Item "file_read($file) - read file to scalar"
Parameters: file name or file handle
.Sp
Returns: scalar content of file
.Sp
This function provides ability to read file content to scalar variable.
.Sp
.Vb 1
\&        my $data = file_read(\*(Aq/etc/passwd\*(Aq);
\&
\&        print "Passwords file: $data\en";
.Ve
.IP "\fBfile_write($file, \f(CB$data\fB)\fR \- write scalar data to file" 4
.IX Item "file_write($file, $data) - write scalar data to file"
Parameters: file name or open file handle
.Sp
Returns: length of written data or undef in case of error
.Sp
.Vb 1
\&        my $data = \*(AqThis should be file\*(Aq;
\&
\&        file_write(\*(Aq/tmp/file.dat\*(Aq, $data);
.Ve
.IP "\fBfile_copy($in_file, \f(CB$out_file\fB)\fR \- copy file" 4
.IX Item "file_copy($in_file, $out_file) - copy file"
Parameters: input file name, output file name
.Sp
Returns:
.Sp
This function copy file to new location.
.IP "\fBfile_move($in_file, \f(CB$out_file\fB)\fR \- move file" 4
.IX Item "file_move($in_file, $out_file) - move file"
Parameters: input file name, output file name
.Sp
Returns: 1 or undef
.Sp
This function moves old file to new location.
.IP "\fBfile_temp($dir)\fR \- create temporary file" 4
.IX Item "file_temp($dir) - create temporary file"
Creates new temp file and return its handle
.IP "\fBdir_create($dir)\fR \- create directory with parents" 4
.IX Item "dir_create($dir) - create directory with parents"
Parameters: directory name
.Sp
Returns: directory name or undef
.Sp
.Vb 1
\&        # Will create all parent catalogs if necessary
\&
\&        dir_create(\*(Aq/var/log/NetSDS/xxx\*(Aq);
.Ve
.IP "\fBdir_delete($dir)\fR \- remove directory recursive" 4
.IX Item "dir_delete($dir) - remove directory recursive"
Parameters: directory name
.Sp
Returns: dir name or undef if error
.Sp
.Vb 1
\&        print "We need no libs!";
\&
\&        dir_delete(\*(Aq/usr/lib\*(Aq);
.Ve
.IP "\fBdir_read($dir, \f(CB$ext\fB)\fR \- read files list from catalog" 4
.IX Item "dir_read($dir, $ext) - read files list from catalog"
Parameters: directory name, extension of files to read
.Sp
Returns: list of files in catalog
.Sp
.Vb 1
\&        my @logs = @{ dir_read(\*(Aq/var/log/httpd\*(Aq, \*(Aqlog\*(Aq) };
\&
\&        print "Logs are: " . join (\*(Aq, \*(Aq, @logs);
.Ve
.IP "\fBdir_read_recursive($dir, \f(CB$ext\fB, [$res])\fR \- read all files list recursive" 4
.IX Item "dir_read_recursive($dir, $ext, [$res]) - read all files list recursive"
Parameters: \f(CW$start\fR catalog, \f(CW$extension\fR
.Sp
Returns: list of files with extension from parameters
.Sp
.Vb 1
\&        my $tpls = dir_read_recursive(\*(Aq/etc/NetSDS\*(Aq, \*(Aqtmpl\*(Aq);
\&
\&        foreach my $tpl (@$tpls) {
\&
\&                pritn "Template: $tpl\en";
\&
\&        }
.Ve
.IP "\fBexec_external($prog, [$param1, ... \f(CB$paramN\fB])\fR \- execute external program" 4
.IX Item "exec_external($prog, [$param1, ... $paramN]) - execute external program"
Parameters: pragram name, arguments list (see perldoc \-f system)
.Sp
Returns: 1 if ok, undef otherwise
.Sp
This function calls \fBsystem()\fR with given parameters and returns 1 if everything
happened correctly (program executed and returned correct result).
.Sp
.Vb 1
\&        if (exec_external(\*(Aq/bin/rm\*(Aq, \*(Aq\-rf\*(Aq, \*(Aq/\*(Aq)) {
\&
\&                print "Hey! We removed the world!";
\&
\&        }
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
None yet
.SH "BUGS"
.IX Header "BUGS"
Unknown yet
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Handle, IO::Scalar, IO::File, File::Spec, File::Copy, File::Path, \fBsystem()\fR
.SH "TODO"
.IX Header "TODO"
1. Implement more detailed error handling
.SH "AUTHOR"
.IX Header "AUTHOR"
Valentyn Solomko <pere@pere.org.ua>
.PP
Michael Bochkaryov <misha@rattler.kiev.ua>