.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "File::Touch 3pm"
.TH File::Touch 3pm "2022-10-13" "perl v5.34.0" "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"
File::Touch \- update file access and modification times, optionally creating files if needed
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use File::Touch 0.12;
\& @file_list = (\*(Aqone.txt\*(Aq,\*(Aq../two.doc\*(Aq);
\& $count = touch(@file_list);
\&
\& use File::Touch;
\& $reference_file = \*(Aq/etc/passwd\*(Aq;
\& $touch_obj = File::Touch\->new(
\&                  reference => $reference_file,
\&                  no_create => 1
\&              );
\& @file_list = (\*(Aqone.txt\*(Aq,\*(Aq../two.doc\*(Aq);
\& $count     = $touch_obj\->touch(@file_list);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides both a functional and \s-1OO\s0 interface
for changing the file access and modification times on files.
It can optionally create the file for you, if it doesn't exist.
.PP
\&\fBNote\fR: you should specify a minimum version of 0.12,
as per the \s-1SYNOPSIS,\s0 as that fixed an issue that affected
systems that have sub-second granularity on those file times.
.PP
Here's a list of arguments that can be used with the
object-oriented contruction:
.IP "atime_only => [0|1]" 4
.IX Item "atime_only => [0|1]"
If nonzero, change only the access time of files. Default is zero.
.IP "mtime_only => [0|1]" 4
.IX Item "mtime_only => [0|1]"
If nonzero, change only the modification time of files. Default is zero.
.IP "no_create => [0|1]" 4
.IX Item "no_create => [0|1]"
If nonzero, do not create new files. Default is zero.
.ie n .IP "reference => $reference_file" 4
.el .IP "reference => \f(CW$reference_file\fR" 4
.IX Item "reference => $reference_file"
If defined, use timestamps from this file instead of current time.
The timestamps are read from the reference file when the object is created,
not when \f(CW\*(C`<\-\*(C'\fRtouch>> is invoked.
Default is undefined.
.ie n .IP "time => $time" 4
.el .IP "time => \f(CW$time\fR" 4
.IX Item "time => $time"
If defined,
then this value will be used for both access time and modification time,
whichever of those are set.
This time is overridden by the \f(CW\*(C`atime\*(C'\fR and \f(CW\*(C`mtime\*(C'\fR arguments,
if you use them.
.ie n .IP "atime => $time" 4
.el .IP "atime => \f(CW$time\fR" 4
.IX Item "atime => $time"
If defined,
use this time (in epoch seconds) instead of current time for access time.
.ie n .IP "mtime => $time" 4
.el .IP "mtime => \f(CW$time\fR" 4
.IX Item "mtime => $time"
If defined,
use this time (in epoch seconds) instead of current time for modification time.
.SH "Examples"
.IX Header "Examples"
.SS "Update access and modification times, creating nonexistent files"
.IX Subsection "Update access and modification times, creating nonexistent files"
.Vb 4
\& use File::Touch;
\& my @files = (\*(Aqone\*(Aq,\*(Aqtwo\*(Aq,\*(Aqthree\*(Aq);
\& my $count = touch(@files);
\& print "$count files updated\en";
.Ve
.SS "Set access time forward, leave modification time unchanged"
.IX Subsection "Set access time forward, leave modification time unchanged"
.Vb 7
\& use File::Touch;
\& my @files = (\*(Aqone\*(Aq,\*(Aqtwo\*(Aq,\*(Aqthree\*(Aq);
\& my $day = 24*60*60;
\& my $time = time() + 30 * $day;
\& my $ref = File::Touch\->new( atime_only => 1, time => $time );
\& my $count = $ref\->touch(@files);
\& print "$count files updated\en";
.Ve
.SS "Set modification time back, update access time, do not create nonexistent files"
.IX Subsection "Set modification time back, update access time, do not create nonexistent files"
.Vb 7
\& use File::Touch;
\& my @files = (\*(Aqone\*(Aq,\*(Aqtwo\*(Aq,\*(Aqthree\*(Aq);
\& my $day = 24*60*60;
\& my $time = time() \- 30 * $day;
\& my $ref = File::Touch\->new( mtime => $time, no_create => 1 );
\& my $count = $ref\->touch(@files);
\& print "$count files updated\en";
.Ve
.SS "Make a change to a file, keeping its timestamps unchanged"
.IX Subsection "Make a change to a file, keeping its timestamps unchanged"
.Vb 4
\& use File::Touch;
\& my $date_restorer = File::Touch\->new(reference => $file);
\& # Update the contents of $file here.
\& $date_restorer\->touch($file);
.Ve
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilb/File\-Touch>
.SH "AUTHOR"
.IX Header "AUTHOR"
Nigel Wetters Gourlay (nwetters@cpan.org)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001,2007,2009 Nigel Wetters Gourlay. All Rights Reserved.
This module is free software. It may be used, redistributed
and/or modified under the same terms as Perl itself.