File Coverage

blib/lib/File/lchown.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 11 11 100.0


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2010,2025 -- leonerd@leonerd.org.uk
5              
6             package File::lchown 0.03;
7              
8 3     3   889084 use v5.14;
  3         14  
9 3     3   27 use warnings;
  3         20  
  3         195  
10              
11 3     3   48 use Exporter 'import';
  3         7  
  3         384  
12             our @EXPORT_OK = qw(
13             lchown
14             lutimes
15             );
16              
17             require XSLoader;
18             XSLoader::load( __PACKAGE__, our $VERSION );
19              
20             =head1 NAME
21              
22             C - modify attributes of symlinks without dereferencing them
23              
24             =head1 SYNOPSIS
25              
26             =for highlighter language=perl
27              
28             use File::lchown qw( lchown lutimes );
29              
30             lchown $uid, $gid, $linkpath or die "Cannot lchown() - $!";
31              
32             lutimes $atime, $mtime, $linkpath or die "Cannot lutimes() - $!";
33              
34             =head1 DESCRIPTION
35              
36             The regular C system call will dereference a symlink and apply
37             ownership changes to the file at which it points. Some OSes provide system
38             calls that do not dereference a symlink but instead apply their changes
39             directly to the named path, even if that path is a symlink (in much the same
40             way that C will return attributes of a symlink rather than the file at
41             which it points).
42              
43             =cut
44              
45             =head1 FUNCTIONS
46              
47             =cut
48              
49             =head2 lchown
50              
51             $count = lchown $uid, $gid, @paths;
52              
53             Set the new user or group ownership of the specified paths, without
54             dereferencing any symlinks. Passing the value C<-1> as either the C<$uid> or
55             C<$gid> will leave that attribute unchanged. Returns the number of files
56             successfully changed.
57              
58             =cut
59              
60             =head2 lutimes
61              
62             $count = lutimes $atime, $mtime, @paths;
63              
64             Set the access and modification times on the specified paths, without
65             dereferencing any symlinks. Passing C as both C<$atime> and C<$mtime>
66             will update the times to the current system time.
67              
68             Note that for both C and C, if more than one path is given,
69             if later paths succeed after earlier failures, then the value of C<$!> will
70             not be reliable to indicate the nature of the failure. If you wish to use
71             C<$!> to report on failures, make sure only to pass one path at a time.
72              
73             I either time may be given as a fractional value, or as an
74             ARRAY reference containing at least two elements. In the latter case, the
75             C<[0]> element should contain the integer seconds and C<[1]> the microseconds
76             part of it; in the same style as L.
77              
78             =cut
79              
80             =head1 SEE ALSO
81              
82             =over 4
83              
84             =item *
85              
86             C - change ownership of a file
87              
88             =item *
89              
90             C - change file timestamps
91              
92             =back
93              
94             =head1 AUTHOR
95              
96             Paul Evans
97              
98             =cut
99              
100             0x55AA;