Debian Codegraph @

upstream/opensuse-tumbleweed/man3/File::stat.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "File::stat 3pm"
61 .TH File::stat 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 File::stat \- by\-name interface to Perl\*(Aqs built\-in stat() functions
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 5
71 \& use File::stat;
72 \& my $st = stat($file) or die "No $file: $!";
73 \& if ( ($st\->mode & 0111) && ($st\->nlink > 1) ) {
74 \& print "$file is executable with lotsa links\en";
75 \& }
76 \&
77 \& if ( \-x $st ) {
78 \& print "$file is executable\en";
79 \& }
80 \&
81 \& use Fcntl "S_IRUSR";
82 \& if ( $st\->cando(S_IRUSR, 1) ) {
83 \& print "My effective uid can read $file\en";
84 \& }
85 \&
86 \& use File::stat qw(:FIELDS);
87 \& stat($file) or die "No $file: $!";
88 \& if ( ($st_mode & 0111) && ($st_nlink > 1) ) {
89 \& print "$file is executable with lotsa links\en";
90 \& }
91 .Ve
92 .SH DESCRIPTION
93 .IX Header "DESCRIPTION"
94 This module\*(Aqs default exports override the core \fBstat()\fR
95 and \fBlstat()\fR functions, replacing them with versions that return
96 "File::stat" objects. This object has methods that
97 return the similarly named structure field name from the
98 \&\fBstat\fR\|(2) function; namely,
99 dev,
100 ino,
101 mode,
102 nlink,
103 uid,
104 gid,
105 rdev,
106 size,
107 atime,
108 mtime,
109 ctime,
110 blksize,
111 and
112 blocks.
113 .PP
114 As of version 1.02 (provided with perl 5.12) the object provides \f(CW"\-X"\fR
115 overloading, so you can call filetest operators (\f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and so
116 on) on it. It also provides a \f(CW\*(C`\->cando\*(C'\fR method, called like
117 .PP
118 .Vb 1
119 \& $st\->cando( ACCESS, EFFECTIVE )
120 .Ve
121 .PP
122 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
123 Fcntl module, and \fIEFFECTIVE\fR indicates whether to use
124 effective (true) or real (false) ids. The method interprets the \f(CW\*(C`mode\*(C'\fR,
125 \&\f(CW\*(C`uid\*(C'\fR and \f(CW\*(C`gid\*(C'\fR fields, and returns whether or not the current process
126 would be allowed the specified access.
127 .PP
128 If you don\*(Aqt want to use the objects, you may import the \f(CW\*(C`\->cando\*(C'\fR
129 method into your namespace as a regular function called \f(CW\*(C`stat_cando\*(C'\fR.
130 This takes an arrayref containing the return values of \f(CW\*(C`stat\*(C'\fR or
131 \&\f(CW\*(C`lstat\*(C'\fR as its first argument, and interprets it for you.
132 .PP
133 You may also import all the structure fields directly into your namespace
134 as regular variables using the :FIELDS import tag. (Note that this still
135 overrides your \fBstat()\fR and \fBlstat()\fR functions.) Access these fields as
136 variables named with a preceding \f(CW\*(C`st_\*(C'\fR in front their method names.
137 Thus, \f(CW\*(C`$stat_obj\->dev()\*(C'\fR corresponds to \f(CW$st_dev\fR if you import
138 the fields.
139 .PP
140 To access this functionality without the core overrides,
141 pass the \f(CW\*(C`use\*(C'\fR an empty import list, and then access
142 function functions with their full qualified names.
143 On the other hand, the built\-ins are still available
144 via the \f(CW\*(C`CORE::\*(C'\fR pseudo\-package.
145 .SH BUGS
146 .IX Header "BUGS"
147 As of Perl 5.8.0 after using this module you cannot use the implicit
148 \&\f(CW$_\fR or the special filehandle \f(CW\*(C`_\*(C'\fR with \fBstat()\fR or \fBlstat()\fR, trying
149 to do so leads into strange errors. The workaround is for \f(CW$_\fR to
150 be explicit
151 .PP
152 .Vb 1
153 \& my $stat_obj = stat $_;
154 .Ve
155 .PP
156 and for \f(CW\*(C`_\*(C'\fR to explicitly populate the object using the unexported
157 and undocumented \fBpopulate()\fR function with \fBCORE::stat()\fR:
158 .PP
159 .Vb 1
160 \& my $stat_obj = File::stat::populate(CORE::stat(_));
161 .Ve
162 .SH ERRORS
163 .IX Header "ERRORS"
164 .IP "\-%s is not implemented on a File::stat object" 4
165 .IX Item "-%s is not implemented on a File::stat object"
166 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
167 they require more information than just a stat buffer.
168 .SH WARNINGS
169 .IX Header "WARNINGS"
170 These can all be disabled with
171 .PP
172 .Vb 1
173 \& no warnings "File::stat";
174 .Ve
175 .IP "File::stat ignores use filetest \*(Aqaccess\*(Aq" 4
176 .IX Item "File::stat ignores use filetest 'access'"
177 You have tried to use one of the \f(CW\*(C`\-rwxRWX\*(C'\fR filetests with \f(CW\*(C`use
178 filetest \*(Aqaccess\*(Aq\*(C'\fR in effect. \f(CW\*(C`File::stat\*(C'\fR will ignore the pragma, and
179 just use the information in the \f(CW\*(C`mode\*(C'\fR member as usual.
180 .IP "File::stat ignores VMS ACLs" 4
181 .IX Item "File::stat ignores VMS ACLs"
182 VMS systems have a permissions structure that cannot be completely
183 represented in a stat buffer, and unlike on other systems the builtin
184 filetest operators respect this. The \f(CW\*(C`File::stat\*(C'\fR overloads, however,
185 do not, since the information required is not available.
186 .SH NOTE
187 .IX Header "NOTE"
188 While this class is currently implemented using the Class::Struct
189 module to build a struct\-like class, you shouldn\*(Aqt rely upon this.
190 .SH AUTHOR
191 .IX Header "AUTHOR"
192 Tom Christiansen