APR::Finfo(3pm)

1docs::api::APR::Finfo(3U)ser Contributed Perl Documentatidooncs::api::APR::Finfo(3)
2
3
4

NAME

6       APR::Finfo - Perl API for APR fileinfo structure
7

Synopsis

9         use APR::Finfo ();
10         use APR::Const -compile => qw(FINFO_NORM);
11         my $finfo = APR::Finfo::stat("/tmp/test", APR::Const::FINFO_NORM, $pool);
12
13         $device = $finfo->device;     # (stat $file)[0]
14         $inode  = $finfo->inode;      # (stat $file)[1]
15         # stat returns an octal number while protection is hex
16         $prot   = $finfo->protection; # (stat $file)[2]
17         $nlink  = $finfo->nlink;      # (stat $file)[3]
18         $gid    = $finfo->group;      # (stat $file)[4]
19         $uid    = $finfo->user;       # (stat $file)[5]
20         $size   = $finfo->size;       # (stat $file)[7]
21         $atime  = $finfo->atime;      # (stat $file)[8]
22         $mtime  = $finfo->mtime;      # (stat $file)[9]
23         $ctime  = $finfo->ctime;      # (stat $file)[10]
24
25         $csize = $finfo->csize; # consumed size: not portable!
26
27         $filetype = $finfo->filetype; # file/dir/socket/etc
28
29         $fname = $finfo->fname;
30         $name  = $finfo->name;  # in filesystem case:
31
32         # valid fields that can be queried
33         $valid = $finfo->valid;
34

Description

36       APR fileinfo structure provides somewhat similar information to Perl's
37       stat() call, but you will want to use this module's API to query an
38       already "stat()'ed" filehandle to avoid an extra system call or to
39       query attributes specific to APR file handles.
40
41       During the HTTP request handlers coming after
42       "PerlMapToStorageHandler", "$r->finfo" already contains the cached
43       values from the apr's stat() call. So you don't want to perform it
44       again, but instead get the "ARP::Finfo" object via:
45
46         my $finfo = $r->finfo;
47

API

49       "APR::Finfo" provides the following functions and/or methods:
50
51   "atime"
52       Get the time the file was last accessed:
53
54         $atime = $finfo->atime;
55
56       obj: $finfo ( "APR::Finfo object" )
57       return: $atime ( integer )
58           Last access time in seconds since the epoch
59
60       since: 2.0.00
61
62       This method returns the same value as Perl's:
63
64         (stat $filename)[8]
65
66       Note that this method may not be reliable on all platforms, most
67       notably Win32 -- FAT32 filesystems appear to work properly, but NTFS
68       filesystems do not.
69
70   "csize"
71       Get the storage size consumed by the file
72
73         $csize = $finfo->csize;
74
75       obj: $finfo ( "APR::Finfo object" )
76       return: $csize ( integer )
77       since: 2.0.00
78
79       Chances are that you don't want to use this method, since its
80       functionality is not supported on most platforms (in which case it
81       always returns 0).
82
83   "ctime"
84       Get the time the file was last changed
85
86         $ctime = $finfo->ctime;
87
88       obj: $finfo ( "APR::Finfo object" )
89       return: $ctime ( integer )
90           Inode change time in seconds since the epoch
91
92       since: 2.0.00
93
94       This method returns the same value as Perl's:
95
96         (stat $filename)[10]
97
98       The ctime field is non-portable.  In particular, you cannot expect it
99       to be a "creation time", see "Files and Filesystems" in the perlport
100       manpage for details.
101
102   "device"
103       Get the id of the device the file is on.
104
105         $device = $finfo->device;
106
107       obj: $finfo ( "APR::Finfo object" )
108       return: $device ( integer )
109       since: 2.0.00
110
111       This method returns the same value as Perl's:
112
113         (stat $filename)[0]
114
115       Note that this method is non-portable. It doesn't work on all
116       platforms, most notably Win32.
117
118   "filetype"
119       Get the type of file.
120
121         $filetype = $finfo->filetype;
122
123       obj: $finfo ( "APR::Finfo object" )
124       return: $filetype ( ":filetype constant" )
125       since: 2.0.00
126
127       For example:
128
129         use APR::Pool;
130         use APR::Finfo;
131         use APR::Const -compile => qw(FILETYPE_DIR FILETYPE_REG FINFO_NORM);
132         my $pool  = APR::Pool->new();
133         my $finfo = APR::Finfo::stat("/tmp", APR::Const::FINFO_NORM, $pool);
134         my $finfo = $finfo->filetype;
135         if ($finfo == APR::Const::FILETYPE_REG) {
136             print "regular file";
137         }
138         elsif ($finfo == APR::Const::FILETYPE_REG) {
139             print "directory";
140         }
141         else {
142             print "other file";
143         }
144
145       Since /tmp is a directory, this will print:
146
147         directory
148
149   "fname"
150       Get the pathname of the file (possibly unrooted)
151
152         $fname = $finfo->fname;
153
154       obj: $finfo ( "APR::Finfo object" )
155       return: $filetype ( string )
156       since: 2.0.00
157
158   "group"
159       Get the group id that owns the file:
160
161         $gid = $finfo->group;
162
163       obj: $finfo ( "APR::Finfo object" )
164       return: $gid ( number )
165       since: 2.0.00
166
167       This method returns the same value as Perl's:
168
169         (stat $filename)[5]
170
171       Note that this method may not be meaningful on all platforms, most
172       notably Win32.  Incorrect results have also been reported on some
173       versions of OSX.
174
175   "inode"
176       Get the inode of the file.
177
178         $inode = $finfo->inode;
179
180       obj: $finfo ( "APR::Finfo object" )
181       return: $inode ( integer )
182       since: 2.0.00
183
184       This method returns the same value as Perl's:
185
186         (stat $filename)[1]
187
188       Note that this method may not be meaningful on all platforms, most
189       notably Win32.
190
191   "mtime"
192       The time the file was last modified
193
194         $mtime = $finfo->mtime;
195
196       obj: $finfo ( "APR::Finfo object" )
197       return: $mtime ( integer )
198           Last modify time in seconds since the epoch
199
200       since: 2.0.00
201
202       This method returns the same value as Perl's:
203
204         (stat $filename)[9]
205
206   "name"
207       Get the file's name (no path) in filesystem case:
208
209         $name = $finfo->name;
210
211       obj: $finfo ( "APR::Finfo object" )
212       return: $device ( string )
213       since: 2.0.00
214
215   "nlink"
216       Get the number of hard links to the file.
217
218         $nlink = $finfo->nlink;
219
220       obj: $finfo ( "APR::Finfo object" )
221       return: $nlink ( integer )
222       since: 2.0.00
223
224       This method returns the same value as Perl's:
225
226         (stat $filename)[3]
227
228   "protection"
229       Get the access permissions of the file.  Mimics Unix access rights.
230
231         $prot = $finfo->protection;
232
233       obj: $finfo ( "APR::Finfo object" )
234       return: $prot ( ":fprot constant" )
235       since: 2.0.00
236
237       This method returns the same value as Perl's:
238
239         (stat $filename)[2]
240
241       Note: Perl's stat returns an octal number while mod_perl's "protection"
242       returns a hex number.
243
244       See perldoc -f stat and APR's file_io for more information on each.
245
246   "size"
247       Get the size of the file
248
249         $size = $finfo->size;
250
251       obj: $finfo ( "APR::Finfo object" )
252       return: $size ( integer )
253           Total size of file, in bytes
254
255       since: 2.0.00
256
257       This method returns the same value as Perl's:
258
259         (stat $filename)[7]
260
261   "stat"
262       Get the specified file's stats.
263
264         $finfo = APR::Finfo::stat($fname, $wanted_fields, $p);
265
266       arg1: $fname ( string )
267           The path to the file to stat().
268
269       arg2: $wanted_fields ( ":finfo constant" )
270           The desired fields, as a bitmask flag of "APR::FINFO_*" constants.
271
272           Notice that you can also use the constants that already combine
273           several elements in one. For example "APR::Const::FINFO_PROT" asks
274           for all protection bits, "APR::Const::FINFO_MIN" asks for the
275           following fields: type, mtime, ctime, atime, size and
276           "APR::Const::FINFO_NORM" asks for all atomic unix apr_stat() fields
277           (similar to perl's stat()).
278
279       arg3: $p ( "APR::Pool object" )
280           the pool to use to allocate the file stat structure.
281
282       ret: $finfo ( "APR::Finfo object" )
283       since: 2.0.00
284
285       For example, here is how to get most of the "stat" fields:
286
287         use APR::Pool ();
288         use APR::Finfo ();
289         use APR::Const -compile => qw(FINFO_NORM);
290         my $pool = APR::Pool->new();
291         my $finfo = APR::Finfo::stat("/tmp/test", APR::Const::FINFO_NORM, $pool);
292
293   "user"
294       Get the user id that owns the file:
295
296         $uid = $finfo->user;
297
298       obj: $finfo ( "APR::Finfo object" )
299       return: $uid ( number )
300       since: 2.0.00
301
302       This method returns the same value as Perl's:
303
304         (stat $filename)[4]
305
306       Note that this method may not be meaningful on all platforms, most
307       notably Win32.
308
309   "valid"
310       The bitmask describing valid fields of this apr_finfo_t structure
311       including all available 'wanted' fields and potentially more
312
313         $valid = $finfo->valid;
314
315       obj: $finfo ( "APR::Finfo object" )
316       arg1: $valid ( bitmask )
317           This bitmask flag should be bit-OR'ed against ":finfo constant"
318           constants.
319
320       since: 2.0.00
321

Copyright

326       mod_perl 2.0 and its core modules are copyrighted under The Apache
327       Software License, Version 2.0.
328

Authors

330       The mod_perl development team and numerous contributors.
331
332
333
334perl v5.38.0                      2023-07-20          docs::api::APR::Finfo(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors