Debian Codegraph @

upstream/debian-unstable/man3/File::stat.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "File::stat 3perl"
58 .TH File::stat 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 File::stat \- by\-name interface to Perl's built\-in stat() functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 5
68 \& use File::stat;
69 \& my $st = stat($file) or die "No $file: $!";
70 \& if ( ($st\->mode & 0111) && ($st\->nlink > 1) ) {
71 \& print "$file is executable with lotsa links\en";
72 \& }
73 \&
74 \& if ( \-x $st ) {
75 \& print "$file is executable\en";
76 \& }
77 \&
78 \& use Fcntl "S_IRUSR";
79 \& if ( $st\->cando(S_IRUSR, 1) ) {
80 \& print "My effective uid can read $file\en";
81 \& }
82 \&
83 \& use File::stat qw(:FIELDS);
84 \& stat($file) or die "No $file: $!";
85 \& if ( ($st_mode & 0111) && ($st_nlink > 1) ) {
86 \& print "$file is executable with lotsa links\en";
87 \& }
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 This module's default exports override the core \fBstat()\fR
92 and \fBlstat()\fR functions, replacing them with versions that return
93 "File::stat" objects. This object has methods that
94 return the similarly named structure field name from the
95 \&\fBstat\fR\|(2) function; namely,
96 dev,
97 ino,
98 mode,
99 nlink,
100 uid,
101 gid,
102 rdev,
103 size,
104 atime,
105 mtime,
106 ctime,
107 blksize,
108 and
109 blocks.
110 .PP
111 As of version 1.02 (provided with perl 5.12) the object provides \f(CW"\-X"\fR
112 overloading, so you can call filetest operators (\f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and so
113 on) on it. It also provides a \f(CW\*(C`\->cando\*(C'\fR method, called like
114 .PP
115 .Vb 1
116 \& $st\->cando( ACCESS, EFFECTIVE )
117 .Ve
118 .PP
119 where \fIACCESS\fR is one of \f(CW\*(C`S_IRUSR\*(C'\fR, \f(CW\*(C`S_IWUSR\*(C'\fR or \f(CW\*(C`S_IXUSR\*(C'\fR from the
120 Fcntl module, and \fIEFFECTIVE\fR indicates whether to use
121 effective (true) or real (false) ids. The method interprets the \f(CW\*(C`mode\*(C'\fR,
122 \&\f(CW\*(C`uid\*(C'\fR and \f(CW\*(C`gid\*(C'\fR fields, and returns whether or not the current process
123 would be allowed the specified access.
124 .PP
125 If you don't want to use the objects, you may import the \f(CW\*(C`\->cando\*(C'\fR
126 method into your namespace as a regular function called \f(CW\*(C`stat_cando\*(C'\fR.
127 This takes an arrayref containing the return values of \f(CW\*(C`stat\*(C'\fR or
128 \&\f(CW\*(C`lstat\*(C'\fR as its first argument, and interprets it for you.
129 .PP
130 You may also import all the structure fields directly into your namespace
131 as regular variables using the :FIELDS import tag. (Note that this still
132 overrides your \fBstat()\fR and \fBlstat()\fR functions.) Access these fields as
133 variables named with a preceding \f(CW\*(C`st_\*(C'\fR in front their method names.
134 Thus, \f(CW\*(C`$stat_obj\->dev()\*(C'\fR corresponds to \f(CW$st_dev\fR if you import
135 the fields.
136 .PP
137 To access this functionality without the core overrides,
138 pass the \f(CW\*(C`use\*(C'\fR an empty import list, and then access
139 function functions with their full qualified names.
140 On the other hand, the built-ins are still available
141 via the \f(CW\*(C`CORE::\*(C'\fR pseudo-package.
142 .SH BUGS
143 .IX Header "BUGS"
144 As of Perl 5.8.0 after using this module you cannot use the implicit
145 \&\f(CW$_\fR or the special filehandle \f(CW\*(C`_\*(C'\fR with \fBstat()\fR or \fBlstat()\fR, trying
146 to do so leads into strange errors. The workaround is for \f(CW$_\fR to
147 be explicit
148 .PP
149 .Vb 1
150 \& my $stat_obj = stat $_;
151 .Ve
152 .PP
153 and for \f(CW\*(C`_\*(C'\fR to explicitly populate the object using the unexported
154 and undocumented \fBpopulate()\fR function with \fBCORE::stat()\fR:
155 .PP
156 .Vb 1
157 \& my $stat_obj = File::stat::populate(CORE::stat(_));
158 .Ve
159 .SH ERRORS
160 .IX Header "ERRORS"
161 .IP "\-%s is not implemented on a File::stat object" 4
162 .IX Item "-%s is not implemented on a File::stat object"
163 The filetest operators \f(CW\*(C`\-t\*(C'\fR, \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR are not implemented, as
164 they require more information than just a stat buffer.
165 .SH WARNINGS
166 .IX Header "WARNINGS"
167 These can all be disabled with
168 .PP
169 .Vb 1
170 \& no warnings "File::stat";
171 .Ve
172 .IP "File::stat ignores use filetest 'access'" 4
173 .IX Item "File::stat ignores use filetest 'access'"
174 You have tried to use one of the \f(CW\*(C`\-rwxRWX\*(C'\fR filetests with \f(CW\*(C`use
175 filetest \*(Aqaccess\*(Aq\*(C'\fR in effect. \f(CW\*(C`File::stat\*(C'\fR will ignore the pragma, and
176 just use the information in the \f(CW\*(C`mode\*(C'\fR member as usual.
177 .IP "File::stat ignores VMS ACLs" 4
178 .IX Item "File::stat ignores VMS ACLs"
179 VMS systems have a permissions structure that cannot be completely
180 represented in a stat buffer, and unlike on other systems the builtin
181 filetest operators respect this. The \f(CW\*(C`File::stat\*(C'\fR overloads, however,
182 do not, since the information required is not available.
183 .SH NOTE
184 .IX Header "NOTE"
185 While this class is currently implemented using the Class::Struct
186 module to build a struct-like class, you shouldn't rely upon this.
187 .SH AUTHOR
188 .IX Header "AUTHOR"
189 Tom Christiansen