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         $prot   = $finfo->protection; # (stat $file)[2]
16         $nlink  = $finfo->nlink;      # (stat $file)[3]
17         $gid    = $finfo->group;      # (stat $file)[4]
18         $uid    = $finfo->user;       # (stat $file)[5]
19         $size   = $finfo->size;       # (stat $file)[7]
20         $atime  = $finfo->atime;      # (stat $file)[8]
21         $mtime  = $finfo->mtime;      # (stat $file)[9]
22         $ctime  = $finfo->ctime;      # (stat $file)[10]
23
24         $csize = $finfo->csize; # consumed size: not portable!
25
26         $filetype = $finfo->filetype; # file/dir/socket/etc
27
28         $fname = $finfo->fname;
29         $name  = $finfo->name;  # in filesystem case:
30
31         # valid fields that can be queried
32         $valid = $finfo->valid;
33

Description

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

API

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

Copyright

320       mod_perl 2.0 and its core modules are copyrighted under The Apache
321       Software License, Version 2.0.
322

Authors

324       The mod_perl development team and numerous contributors.
325
326
327
328perl v5.12.0                      2007-11-12          docs::api::APR::Finfo(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors