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

Copyright

336       mod_perl 2.0 and its core modules are copyrighted under The Apache
337       Software License, Version 2.0.
338

Authors

340       The mod_perl development team and numerous contributors.
341
342
343
344perl v5.8.8                       2006-11-19          docs::api::APR::Finfo(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors