| 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 "Tie::File 3perl" |
| 58 |
.TH Tie::File 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 |
Tie::File \- Access the lines of a disk file via a Perl array |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Tie::File; |
| 69 |
\& |
| 70 |
\& tie @array, \*(AqTie::File\*(Aq, filename or die ...; |
| 71 |
\& |
| 72 |
\& $array[0] = \*(Aqblah\*(Aq; # first line of the file is now \*(Aqblah\*(Aq |
| 73 |
\& # (line numbering starts at 0) |
| 74 |
\& print $array[42]; # display line 43 of the file |
| 75 |
\& |
| 76 |
\& $n_recs = @array; # how many records are in the file? |
| 77 |
\& $#array \-= 2; # chop two records off the end |
| 78 |
\& |
| 79 |
\& |
| 80 |
\& for (@array) { |
| 81 |
\& s/PERL/Perl/g; # Replace PERL with Perl everywhere in the file |
| 82 |
\& } |
| 83 |
\& |
| 84 |
\& # These are just like regular push, pop, unshift, shift, and splice |
| 85 |
\& # Except that they modify the file in the way you would expect |
| 86 |
\& |
| 87 |
\& push @array, new recs...; |
| 88 |
\& my $r1 = pop @array; |
| 89 |
\& unshift @array, new recs...; |
| 90 |
\& my $r2 = shift @array; |
| 91 |
\& @old_recs = splice @array, 3, 7, new recs...; |
| 92 |
\& |
| 93 |
\& untie @array; # all finished |
| 94 |
.Ve |
| 95 |
.SH DESCRIPTION |
| 96 |
.IX Header "DESCRIPTION" |
| 97 |
\&\f(CW\*(C`Tie::File\*(C'\fR represents a regular text file as a Perl array. Each |
| 98 |
element in the array corresponds to a record in the file. The first |
| 99 |
line of the file is element 0 of the array; the second line is element |
| 100 |
1, and so on. |
| 101 |
.PP |
| 102 |
The file is \fInot\fR loaded into memory, so this will work even for |
| 103 |
gigantic files. |
| 104 |
.PP |
| 105 |
Changes to the array are reflected in the file immediately. |
| 106 |
.PP |
| 107 |
Lazy people and beginners may now stop reading the manual. |
| 108 |
.ie n .SS """unicode""" |
| 109 |
.el .SS \f(CWunicode\fP |
| 110 |
.IX Subsection "unicode" |
| 111 |
You can read a unicode (UTF\-8) file by providing a file handle opened with |
| 112 |
the desired encoding. It is not safe to write to one because |
| 113 |
the length in bytes and in characters is often different, Tie::File |
| 114 |
will miscalculate the length of writes, overwriting parts of other records. |
| 115 |
.ie n .SS """recsep""" |
| 116 |
.el .SS \f(CWrecsep\fP |
| 117 |
.IX Subsection "recsep" |
| 118 |
What is a 'record'? By default, the meaning is the same as for the |
| 119 |
\&\f(CW\*(C`<...>\*(C'\fR operator: It's a string terminated by \f(CW$/\fR, which is |
| 120 |
probably \f(CW"\en"\fR. (Minor exception: on DOS and Win32 systems, a |
| 121 |
\&'record' is a string terminated by \f(CW"\er\en"\fR.) You may change the |
| 122 |
definition of "record" by supplying the \f(CW\*(C`recsep\*(C'\fR option in the \f(CW\*(C`tie\*(C'\fR |
| 123 |
call: |
| 124 |
.PP |
| 125 |
.Vb 1 |
| 126 |
\& tie @array, \*(AqTie::File\*(Aq, $file, recsep => \*(Aqes\*(Aq; |
| 127 |
.Ve |
| 128 |
.PP |
| 129 |
This says that records are delimited by the string \f(CW\*(C`es\*(C'\fR. If the file |
| 130 |
contained the following data: |
| 131 |
.PP |
| 132 |
.Vb 1 |
| 133 |
\& Curse these pesky flies!\en |
| 134 |
.Ve |
| 135 |
.PP |
| 136 |
then the \f(CW@array\fR would appear to have four elements: |
| 137 |
.PP |
| 138 |
.Vb 4 |
| 139 |
\& "Curse th" |
| 140 |
\& "e p" |
| 141 |
\& "ky fli" |
| 142 |
\& "!\en" |
| 143 |
.Ve |
| 144 |
.PP |
| 145 |
An undefined value is not permitted as a record separator. Perl's |
| 146 |
special "paragraph mode" semantics (Ã la \f(CW\*(C`$/ = ""\*(C'\fR) are not |
| 147 |
emulated. |
| 148 |
.PP |
| 149 |
Records read from the tied array do not have the record separator |
| 150 |
string on the end; this is to allow |
| 151 |
.PP |
| 152 |
.Vb 1 |
| 153 |
\& $array[17] .= "extra"; |
| 154 |
.Ve |
| 155 |
.PP |
| 156 |
to work as expected. |
| 157 |
.PP |
| 158 |
(See "autochomp", below.) Records stored into the array will have |
| 159 |
the record separator string appended before they are written to the |
| 160 |
file, if they don't have one already. For example, if the record |
| 161 |
separator string is \f(CW"\en"\fR, then the following two lines do exactly |
| 162 |
the same thing: |
| 163 |
.PP |
| 164 |
.Vb 2 |
| 165 |
\& $array[17] = "Cherry pie"; |
| 166 |
\& $array[17] = "Cherry pie\en"; |
| 167 |
.Ve |
| 168 |
.PP |
| 169 |
The result is that the contents of line 17 of the file will be |
| 170 |
replaced with "Cherry pie"; a newline character will separate line 17 |
| 171 |
from line 18. This means that this code will do nothing: |
| 172 |
.PP |
| 173 |
.Vb 1 |
| 174 |
\& chomp $array[17]; |
| 175 |
.Ve |
| 176 |
.PP |
| 177 |
Because the \f(CW\*(C`chomp\*(C'\fRed value will have the separator reattached when |
| 178 |
it is written back to the file. There is no way to create a file |
| 179 |
whose trailing record separator string is missing. |
| 180 |
.PP |
| 181 |
Inserting records that \fIcontain\fR the record separator string is not |
| 182 |
supported by this module. It will probably produce a reasonable |
| 183 |
result, but what this result will be may change in a future version. |
| 184 |
Use 'splice' to insert records or to replace one record with several. |
| 185 |
.ie n .SS """autochomp""" |
| 186 |
.el .SS \f(CWautochomp\fP |
| 187 |
.IX Subsection "autochomp" |
| 188 |
Normally, array elements have the record separator removed, so that if |
| 189 |
the file contains the text |
| 190 |
.PP |
| 191 |
.Vb 3 |
| 192 |
\& Gold |
| 193 |
\& Frankincense |
| 194 |
\& Myrrh |
| 195 |
.Ve |
| 196 |
.PP |
| 197 |
the tied array will appear to contain \f(CW\*(C`("Gold", "Frankincense", |
| 198 |
"Myrrh")\*(C'\fR. If you set \f(CW\*(C`autochomp\*(C'\fR to a false value, the record |
| 199 |
separator will not be removed. If the file above was tied with |
| 200 |
.PP |
| 201 |
.Vb 1 |
| 202 |
\& tie @gifts, "Tie::File", $gifts, autochomp => 0; |
| 203 |
.Ve |
| 204 |
.PP |
| 205 |
then the array \f(CW@gifts\fR would appear to contain \f(CW\*(C`("Gold\en", |
| 206 |
"Frankincense\en", "Myrrh\en")\*(C'\fR, or (on Win32 systems) \f(CW\*(C`("Gold\er\en", |
| 207 |
"Frankincense\er\en", "Myrrh\er\en")\*(C'\fR. |
| 208 |
.ie n .SS """mode""" |
| 209 |
.el .SS \f(CWmode\fP |
| 210 |
.IX Subsection "mode" |
| 211 |
Normally, the specified file will be opened for read and write access, |
| 212 |
and will be created if it does not exist. (That is, the flags |
| 213 |
\&\f(CW\*(C`O_RDWR | O_CREAT\*(C'\fR are supplied in the \f(CW\*(C`open\*(C'\fR call.) If you want to |
| 214 |
change this, you may supply alternative flags in the \f(CW\*(C`mode\*(C'\fR option. |
| 215 |
See Fcntl for a listing of available flags. |
| 216 |
For example: |
| 217 |
.PP |
| 218 |
.Vb 3 |
| 219 |
\& # open the file if it exists, but fail if it does not exist |
| 220 |
\& use Fcntl \*(AqO_RDWR\*(Aq; |
| 221 |
\& tie @array, \*(AqTie::File\*(Aq, $file, mode => O_RDWR; |
| 222 |
\& |
| 223 |
\& # create the file if it does not exist |
| 224 |
\& use Fcntl \*(AqO_RDWR\*(Aq, \*(AqO_CREAT\*(Aq; |
| 225 |
\& tie @array, \*(AqTie::File\*(Aq, $file, mode => O_RDWR | O_CREAT; |
| 226 |
\& |
| 227 |
\& # open an existing file in read\-only mode |
| 228 |
\& use Fcntl \*(AqO_RDONLY\*(Aq; |
| 229 |
\& tie @array, \*(AqTie::File\*(Aq, $file, mode => O_RDONLY; |
| 230 |
.Ve |
| 231 |
.PP |
| 232 |
Opening the data file in write-only or append mode is not supported. |
| 233 |
.ie n .SS """memory""" |
| 234 |
.el .SS \f(CWmemory\fP |
| 235 |
.IX Subsection "memory" |
| 236 |
This is an upper limit on the amount of memory that \f(CW\*(C`Tie::File\*(C'\fR will |
| 237 |
consume at any time while managing the file. This is used for two |
| 238 |
things: managing the \fIread cache\fR and managing the \fIdeferred write |
| 239 |
buffer\fR. |
| 240 |
.PP |
| 241 |
Records read in from the file are cached, to avoid having to re-read |
| 242 |
them repeatedly. If you read the same record twice, the first time it |
| 243 |
will be stored in memory, and the second time it will be fetched from |
| 244 |
the \fIread cache\fR. The amount of data in the read cache will not |
| 245 |
exceed the value you specified for \f(CW\*(C`memory\*(C'\fR. If \f(CW\*(C`Tie::File\*(C'\fR wants |
| 246 |
to cache a new record, but the read cache is full, it will make room |
| 247 |
by expiring the least-recently visited records from the read cache. |
| 248 |
.PP |
| 249 |
The default memory limit is 2Mib. You can adjust the maximum read |
| 250 |
cache size by supplying the \f(CW\*(C`memory\*(C'\fR option. The argument is the |
| 251 |
desired cache size, in bytes. |
| 252 |
.PP |
| 253 |
.Vb 2 |
| 254 |
\& # I have a lot of memory, so use a large cache to speed up access |
| 255 |
\& tie @array, \*(AqTie::File\*(Aq, $file, memory => 20_000_000; |
| 256 |
.Ve |
| 257 |
.PP |
| 258 |
Setting the memory limit to 0 will inhibit caching; records will be |
| 259 |
fetched from disk every time you examine them. |
| 260 |
.PP |
| 261 |
The \f(CW\*(C`memory\*(C'\fR value is not an absolute or exact limit on the memory |
| 262 |
used. \f(CW\*(C`Tie::File\*(C'\fR objects contains some structures besides the read |
| 263 |
cache and the deferred write buffer, whose sizes are not charged |
| 264 |
against \f(CW\*(C`memory\*(C'\fR. |
| 265 |
.PP |
| 266 |
The cache itself consumes about 310 bytes per cached record, so if |
| 267 |
your file has many short records, you may want to decrease the cache |
| 268 |
memory limit, or else the cache overhead may exceed the size of the |
| 269 |
cached data. |
| 270 |
.ie n .SS """dw_size""" |
| 271 |
.el .SS \f(CWdw_size\fP |
| 272 |
.IX Subsection "dw_size" |
| 273 |
(This is an advanced feature. Skip this section on first reading.) |
| 274 |
.PP |
| 275 |
If you use deferred writing (See "Deferred Writing", below) then |
| 276 |
data you write into the array will not be written directly to the |
| 277 |
file; instead, it will be saved in the \fIdeferred write buffer\fR to be |
| 278 |
written out later. Data in the deferred write buffer is also charged |
| 279 |
against the memory limit you set with the \f(CW\*(C`memory\*(C'\fR option. |
| 280 |
.PP |
| 281 |
You may set the \f(CW\*(C`dw_size\*(C'\fR option to limit the amount of data that can |
| 282 |
be saved in the deferred write buffer. This limit may not exceed the |
| 283 |
total memory limit. For example, if you set \f(CW\*(C`dw_size\*(C'\fR to 1000 and |
| 284 |
\&\f(CW\*(C`memory\*(C'\fR to 2500, that means that no more than 1000 bytes of deferred |
| 285 |
writes will be saved up. The space available for the read cache will |
| 286 |
vary, but it will always be at least 1500 bytes (if the deferred write |
| 287 |
buffer is full) and it could grow as large as 2500 bytes (if the |
| 288 |
deferred write buffer is empty.) |
| 289 |
.PP |
| 290 |
If you don't specify a \f(CW\*(C`dw_size\*(C'\fR, it defaults to the entire memory |
| 291 |
limit. |
| 292 |
.SS "Option Format" |
| 293 |
.IX Subsection "Option Format" |
| 294 |
\&\f(CW\*(C`\-mode\*(C'\fR is a synonym for \f(CW\*(C`mode\*(C'\fR. \f(CW\*(C`\-recsep\*(C'\fR is a synonym for |
| 295 |
\&\f(CW\*(C`recsep\*(C'\fR. \f(CW\*(C`\-memory\*(C'\fR is a synonym for \f(CW\*(C`memory\*(C'\fR. You get the |
| 296 |
idea. |
| 297 |
.SH "Public Methods" |
| 298 |
.IX Header "Public Methods" |
| 299 |
The \f(CW\*(C`tie\*(C'\fR call returns an object, say \f(CW$o\fR. You may call |
| 300 |
.PP |
| 301 |
.Vb 2 |
| 302 |
\& $rec = $o\->FETCH($n); |
| 303 |
\& $o\->STORE($n, $rec); |
| 304 |
.Ve |
| 305 |
.PP |
| 306 |
to fetch or store the record at line \f(CW$n\fR, respectively; similarly |
| 307 |
the other tied array methods. (See perltie for details.) You may |
| 308 |
also call the following methods on this object: |
| 309 |
.ie n .SS """flock""" |
| 310 |
.el .SS \f(CWflock\fP |
| 311 |
.IX Subsection "flock" |
| 312 |
.Vb 1 |
| 313 |
\& $o\->flock(MODE) |
| 314 |
.Ve |
| 315 |
.PP |
| 316 |
will lock the tied file. \f(CW\*(C`MODE\*(C'\fR has the same meaning as the second |
| 317 |
argument to the Perl built-in \f(CW\*(C`flock\*(C'\fR function; for example |
| 318 |
\&\f(CW\*(C`LOCK_SH\*(C'\fR or \f(CW\*(C`LOCK_EX | LOCK_NB\*(C'\fR. (These constants are provided by |
| 319 |
the \f(CW\*(C`use Fcntl \*(Aq:flock\*(Aq\*(C'\fR declaration.) |
| 320 |
.PP |
| 321 |
\&\f(CW\*(C`MODE\*(C'\fR is optional; the default is \f(CW\*(C`LOCK_EX\*(C'\fR. |
| 322 |
.PP |
| 323 |
\&\f(CW\*(C`Tie::File\*(C'\fR maintains an internal table of the byte offset of each |
| 324 |
record it has seen in the file. |
| 325 |
.PP |
| 326 |
When you use \f(CW\*(C`flock\*(C'\fR to lock the file, \f(CW\*(C`Tie::File\*(C'\fR assumes that the |
| 327 |
read cache is no longer trustworthy, because another process might |
| 328 |
have modified the file since the last time it was read. Therefore, a |
| 329 |
successful call to \f(CW\*(C`flock\*(C'\fR discards the contents of the read cache |
| 330 |
and the internal record offset table. |
| 331 |
.PP |
| 332 |
\&\f(CW\*(C`Tie::File\*(C'\fR promises that the following sequence of operations will |
| 333 |
be safe: |
| 334 |
.PP |
| 335 |
.Vb 2 |
| 336 |
\& my $o = tie @array, "Tie::File", $filename; |
| 337 |
\& $o\->flock; |
| 338 |
.Ve |
| 339 |
.PP |
| 340 |
In particular, \f(CW\*(C`Tie::File\*(C'\fR will \fInot\fR read or write the file during |
| 341 |
the \f(CW\*(C`tie\*(C'\fR call. (Exception: Using \f(CW\*(C`mode => O_TRUNC\*(C'\fR will, of |
| 342 |
course, erase the file during the \f(CW\*(C`tie\*(C'\fR call. If you want to do this |
| 343 |
safely, then open the file without \f(CW\*(C`O_TRUNC\*(C'\fR, lock the file, and use |
| 344 |
\&\f(CW\*(C`@array = ()\*(C'\fR.) |
| 345 |
.PP |
| 346 |
The best way to unlock a file is to discard the object and untie the |
| 347 |
array. It is probably unsafe to unlock the file without also untying |
| 348 |
it, because if you do, changes may remain unwritten inside the object. |
| 349 |
That is why there is no shortcut for unlocking. If you really want to |
| 350 |
unlock the file prematurely, you know what to do; if you don't know |
| 351 |
what to do, then don't do it. |
| 352 |
.PP |
| 353 |
All the usual warnings about file locking apply here. In particular, |
| 354 |
note that file locking in Perl is \fBadvisory\fR, which means that |
| 355 |
holding a lock will not prevent anyone else from reading, writing, or |
| 356 |
erasing the file; it only prevents them from getting another lock at |
| 357 |
the same time. Locks are analogous to green traffic lights: If you |
| 358 |
have a green light, that does not prevent the idiot coming the other |
| 359 |
way from plowing into you sideways; it merely guarantees to you that |
| 360 |
the idiot does not also have a green light at the same time. |
| 361 |
.ie n .SS """autochomp""" |
| 362 |
.el .SS \f(CWautochomp\fP |
| 363 |
.IX Subsection "autochomp" |
| 364 |
.Vb 2 |
| 365 |
\& my $old_value = $o\->autochomp(0); # disable autochomp option |
| 366 |
\& my $old_value = $o\->autochomp(1); # enable autochomp option |
| 367 |
\& |
| 368 |
\& my $ac = $o\->autochomp(); # recover current value |
| 369 |
.Ve |
| 370 |
.PP |
| 371 |
See "autochomp", above. |
| 372 |
.ie n .SS """defer"", ""flush"", ""discard"", and ""autodefer""" |
| 373 |
.el .SS "\f(CWdefer\fP, \f(CWflush\fP, \f(CWdiscard\fP, and \f(CWautodefer\fP" |
| 374 |
.IX Subsection "defer, flush, discard, and autodefer" |
| 375 |
See "Deferred Writing", below. |
| 376 |
.ie n .SS """offset""" |
| 377 |
.el .SS \f(CWoffset\fP |
| 378 |
.IX Subsection "offset" |
| 379 |
.Vb 1 |
| 380 |
\& $off = $o\->offset($n); |
| 381 |
.Ve |
| 382 |
.PP |
| 383 |
This method returns the byte offset of the start of the \f(CW$n\fRth record |
| 384 |
in the file. If there is no such record, it returns an undefined |
| 385 |
value. |
| 386 |
.SH "Tying to an already-opened filehandle" |
| 387 |
.IX Header "Tying to an already-opened filehandle" |
| 388 |
If \f(CW$fh\fR is a filehandle, such as is returned by \f(CW\*(C`IO::File\*(C'\fR or one |
| 389 |
of the other \f(CW\*(C`IO\*(C'\fR modules, you may use: |
| 390 |
.PP |
| 391 |
.Vb 1 |
| 392 |
\& tie @array, \*(AqTie::File\*(Aq, $fh, ...; |
| 393 |
.Ve |
| 394 |
.PP |
| 395 |
Similarly if you opened that handle \f(CW\*(C`FH\*(C'\fR with regular \f(CW\*(C`open\*(C'\fR or |
| 396 |
\&\f(CW\*(C`sysopen\*(C'\fR, you may use: |
| 397 |
.PP |
| 398 |
.Vb 1 |
| 399 |
\& tie @array, \*(AqTie::File\*(Aq, \e*FH, ...; |
| 400 |
.Ve |
| 401 |
.PP |
| 402 |
Handles that were opened write-only won't work. Handles that were |
| 403 |
opened read-only will work as long as you don't try to modify the |
| 404 |
array. Handles must be attached to seekable sources of data\-\-\-that |
| 405 |
means no pipes or sockets. If \f(CW\*(C`Tie::File\*(C'\fR can detect that you |
| 406 |
supplied a non-seekable handle, the \f(CW\*(C`tie\*(C'\fR call will throw an |
| 407 |
exception. (On Unix systems, it can detect this.) |
| 408 |
.PP |
| 409 |
Note that Tie::File will only close any filehandles that it opened |
| 410 |
internally. If you passed it a filehandle as above, you "own" the |
| 411 |
filehandle, and are responsible for closing it after you have untied |
| 412 |
the \f(CW@array\fR. |
| 413 |
.PP |
| 414 |
Tie::File calls \f(CW\*(C`binmode\*(C'\fR on filehandles that it opens internally, |
| 415 |
but not on filehandles passed in by the user. For consistency, |
| 416 |
especially if using the tied files cross-platform, you may wish to |
| 417 |
call \f(CW\*(C`binmode\*(C'\fR on the filehandle prior to tying the file. |
| 418 |
.SH "Deferred Writing" |
| 419 |
.IX Header "Deferred Writing" |
| 420 |
(This is an advanced feature. Skip this section on first reading.) |
| 421 |
.PP |
| 422 |
Normally, modifying a \f(CW\*(C`Tie::File\*(C'\fR array writes to the underlying file |
| 423 |
immediately. Every assignment like \f(CW\*(C`$a[3] = ...\*(C'\fR rewrites as much of |
| 424 |
the file as is necessary; typically, everything from line 3 through |
| 425 |
the end will need to be rewritten. This is the simplest and most |
| 426 |
transparent behavior. Performance even for large files is reasonably |
| 427 |
good. |
| 428 |
.PP |
| 429 |
However, under some circumstances, this behavior may be excessively |
| 430 |
slow. For example, suppose you have a million-record file, and you |
| 431 |
want to do: |
| 432 |
.PP |
| 433 |
.Vb 3 |
| 434 |
\& for (@FILE) { |
| 435 |
\& $_ = "> $_"; |
| 436 |
\& } |
| 437 |
.Ve |
| 438 |
.PP |
| 439 |
The first time through the loop, you will rewrite the entire file, |
| 440 |
from line 0 through the end. The second time through the loop, you |
| 441 |
will rewrite the entire file from line 1 through the end. The third |
| 442 |
time through the loop, you will rewrite the entire file from line 2 to |
| 443 |
the end. And so on. |
| 444 |
.PP |
| 445 |
If the performance in such cases is unacceptable, you may defer the |
| 446 |
actual writing, and then have it done all at once. The following loop |
| 447 |
will perform much better for large files: |
| 448 |
.PP |
| 449 |
.Vb 5 |
| 450 |
\& (tied @a)\->defer; |
| 451 |
\& for (@a) { |
| 452 |
\& $_ = "> $_"; |
| 453 |
\& } |
| 454 |
\& (tied @a)\->flush; |
| 455 |
.Ve |
| 456 |
.PP |
| 457 |
If \f(CW\*(C`Tie::File\*(C'\fR's memory limit is large enough, all the writing will |
| 458 |
done in memory. Then, when you call \f(CW\*(C`\->flush\*(C'\fR, the entire file |
| 459 |
will be rewritten in a single pass. |
| 460 |
.PP |
| 461 |
(Actually, the preceding discussion is something of a fib. You don't |
| 462 |
need to enable deferred writing to get good performance for this |
| 463 |
common case, because \f(CW\*(C`Tie::File\*(C'\fR will do it for you automatically |
| 464 |
unless you specifically tell it not to. See "Autodeferring", |
| 465 |
below.) |
| 466 |
.PP |
| 467 |
Calling \f(CW\*(C`\->flush\*(C'\fR returns the array to immediate-write mode. If |
| 468 |
you wish to discard the deferred writes, you may call \f(CW\*(C`\->discard\*(C'\fR |
| 469 |
instead of \f(CW\*(C`\->flush\*(C'\fR. Note that in some cases, some of the data |
| 470 |
will have been written already, and it will be too late for |
| 471 |
\&\f(CW\*(C`\->discard\*(C'\fR to discard all the changes. Support for |
| 472 |
\&\f(CW\*(C`\->discard\*(C'\fR may be withdrawn in a future version of \f(CW\*(C`Tie::File\*(C'\fR. |
| 473 |
.PP |
| 474 |
Deferred writes are cached in memory up to the limit specified by the |
| 475 |
\&\f(CW\*(C`dw_size\*(C'\fR option (see above). If the deferred-write buffer is full |
| 476 |
and you try to write still more deferred data, the buffer will be |
| 477 |
flushed. All buffered data will be written immediately, the buffer |
| 478 |
will be emptied, and the now-empty space will be used for future |
| 479 |
deferred writes. |
| 480 |
.PP |
| 481 |
If the deferred-write buffer isn't yet full, but the total size of the |
| 482 |
buffer and the read cache would exceed the \f(CW\*(C`memory\*(C'\fR limit, the oldest |
| 483 |
records will be expired from the read cache until the total size is |
| 484 |
under the limit. |
| 485 |
.PP |
| 486 |
\&\f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR, and \f(CW\*(C`splice\*(C'\fR cannot be |
| 487 |
deferred. When you perform one of these operations, any deferred data |
| 488 |
is written to the file and the operation is performed immediately. |
| 489 |
This may change in a future version. |
| 490 |
.PP |
| 491 |
If you resize the array with deferred writing enabled, the file will |
| 492 |
be resized immediately, but deferred records will not be written. |
| 493 |
This has a surprising consequence: \f(CW\*(C`@a = (...)\*(C'\fR erases the file |
| 494 |
immediately, but the writing of the actual data is deferred. This |
| 495 |
might be a bug. If it is a bug, it will be fixed in a future version. |
| 496 |
.SS Autodeferring |
| 497 |
.IX Subsection "Autodeferring" |
| 498 |
\&\f(CW\*(C`Tie::File\*(C'\fR tries to guess when deferred writing might be helpful, |
| 499 |
and to turn it on and off automatically. |
| 500 |
.PP |
| 501 |
.Vb 3 |
| 502 |
\& for (@a) { |
| 503 |
\& $_ = "> $_"; |
| 504 |
\& } |
| 505 |
.Ve |
| 506 |
.PP |
| 507 |
In this example, only the first two assignments will be done |
| 508 |
immediately; after this, all the changes to the file will be deferred |
| 509 |
up to the user-specified memory limit. |
| 510 |
.PP |
| 511 |
You should usually be able to ignore this and just use the module |
| 512 |
without thinking about deferring. However, special applications may |
| 513 |
require fine control over which writes are deferred, or may require |
| 514 |
that all writes be immediate. To disable the autodeferment feature, |
| 515 |
use |
| 516 |
.PP |
| 517 |
.Vb 1 |
| 518 |
\& (tied @o)\->autodefer(0); |
| 519 |
.Ve |
| 520 |
.PP |
| 521 |
or |
| 522 |
.PP |
| 523 |
.Vb 1 |
| 524 |
\& tie @array, \*(AqTie::File\*(Aq, $file, autodefer => 0; |
| 525 |
.Ve |
| 526 |
.PP |
| 527 |
Similarly, \f(CW\*(C`\->autodefer(1)\*(C'\fR re-enables autodeferment, and |
| 528 |
\&\f(CW\*(C`\->autodefer()\*(C'\fR recovers the current value of the autodefer setting. |
| 529 |
.SH "CONCURRENT ACCESS TO FILES" |
| 530 |
.IX Header "CONCURRENT ACCESS TO FILES" |
| 531 |
Caching and deferred writing are inappropriate if you want the same |
| 532 |
file to be accessed simultaneously from more than one process. Other |
| 533 |
optimizations performed internally by this module are also |
| 534 |
incompatible with concurrent access. A future version of this module will |
| 535 |
support a \f(CW\*(C`concurrent => 1\*(C'\fR option that enables safe concurrent access. |
| 536 |
.PP |
| 537 |
Previous versions of this documentation suggested using \f(CW\*(C`memory |
| 538 |
=> 0\*(C'\fR for safe concurrent access. This was mistaken. Tie::File |
| 539 |
will not support safe concurrent access before version 0.96. |
| 540 |
.SH CAVEATS |
| 541 |
.IX Header "CAVEATS" |
| 542 |
(That's Latin for 'warnings'.) |
| 543 |
.IP \(bu 4 |
| 544 |
Reasonable effort was made to make this module efficient. Nevertheless, |
| 545 |
changing the size of a record in the middle of a large file will |
| 546 |
always be fairly slow, because everything after the new record must be |
| 547 |
moved. |
| 548 |
.IP \(bu 4 |
| 549 |
The behavior of tied arrays is not precisely the same as for regular |
| 550 |
arrays. For example: |
| 551 |
.Sp |
| 552 |
.Vb 2 |
| 553 |
\& # This DOES print "How unusual!" |
| 554 |
\& undef $a[10]; print "How unusual!\en" if defined $a[10]; |
| 555 |
.Ve |
| 556 |
.Sp |
| 557 |
\&\f(CW\*(C`undef\*(C'\fR\-ing a \f(CW\*(C`Tie::File\*(C'\fR array element just blanks out the |
| 558 |
corresponding record in the file. When you read it back again, you'll |
| 559 |
get the empty string, so the supposedly\-\f(CW\*(C`undef\*(C'\fR'ed value will be |
| 560 |
defined. Similarly, if you have \f(CW\*(C`autochomp\*(C'\fR disabled, then |
| 561 |
.Sp |
| 562 |
.Vb 3 |
| 563 |
\& # This DOES print "How unusual!" if \*(Aqautochomp\*(Aq is disabled |
| 564 |
\& undef $a[10]; |
| 565 |
\& print "How unusual!\en" if $a[10]; |
| 566 |
.Ve |
| 567 |
.Sp |
| 568 |
Because when \f(CW\*(C`autochomp\*(C'\fR is disabled, \f(CW$a[10]\fR will read back as |
| 569 |
\&\f(CW"\en"\fR (or whatever the record separator string is.) |
| 570 |
.Sp |
| 571 |
There are other minor differences, particularly regarding \f(CW\*(C`exists\*(C'\fR |
| 572 |
and \f(CW\*(C`delete\*(C'\fR, but in general, the correspondence is extremely close. |
| 573 |
.IP \(bu 4 |
| 574 |
I have supposed that since this module is concerned with file I/O, |
| 575 |
almost all normal use of it will be heavily I/O bound. This means |
| 576 |
that the time to maintain complicated data structures inside the |
| 577 |
module will be dominated by the time to actually perform the I/O. |
| 578 |
When there was an opportunity to spend CPU time to avoid doing I/O, I |
| 579 |
usually tried to take it. |
| 580 |
.IP \(bu 4 |
| 581 |
You might be tempted to think that deferred writing is like |
| 582 |
transactions, with \f(CW\*(C`flush\*(C'\fR as \f(CW\*(C`commit\*(C'\fR and \f(CW\*(C`discard\*(C'\fR as |
| 583 |
\&\f(CW\*(C`rollback\*(C'\fR, but it isn't, so don't. |
| 584 |
.IP \(bu 4 |
| 585 |
There is a large memory overhead for each record offset and for each |
| 586 |
cache entry: about 310 bytes per cached data record, and about 21 bytes |
| 587 |
per offset table entry. |
| 588 |
.Sp |
| 589 |
The per-record overhead will limit the maximum number of records you |
| 590 |
can access per file. Note that \fIaccessing\fR the length of the array |
| 591 |
via \f(CW\*(C`$x = scalar @tied_file\*(C'\fR accesses \fBall\fR records and stores their |
| 592 |
offsets. The same for \f(CW\*(C`foreach (@tied_file)\*(C'\fR, even if you exit the |
| 593 |
loop early. |
| 594 |
.SH SUBCLASSING |
| 595 |
.IX Header "SUBCLASSING" |
| 596 |
This version promises absolutely nothing about the internals, which |
| 597 |
may change without notice. A future version of the module will have a |
| 598 |
well-defined and stable subclassing API. |
| 599 |
.ie n .SH "WHAT ABOUT ""DB_File""?" |
| 600 |
.el .SH "WHAT ABOUT \f(CWDB_File\fP?" |
| 601 |
.IX Header "WHAT ABOUT DB_File?" |
| 602 |
People sometimes point out that DB_File will do something similar, |
| 603 |
and ask why \f(CW\*(C`Tie::File\*(C'\fR module is necessary. |
| 604 |
.PP |
| 605 |
There are a number of reasons that you might prefer \f(CW\*(C`Tie::File\*(C'\fR. |
| 606 |
A list is available at \f(CW\*(C`<http://perl.plover.com/TieFile/why\-not\-DB_File>\*(C'\fR. |
| 607 |
.SH AUTHOR |
| 608 |
.IX Header "AUTHOR" |
| 609 |
Mark Jason Dominus |
| 610 |
.PP |
| 611 |
To contact the author, send email to: \f(CW\*(C`mjd\-perl\[email protected]\*(C'\fR |
| 612 |
.PP |
| 613 |
To receive an announcement whenever a new version of this module is |
| 614 |
released, send a blank email message to |
| 615 |
\&\f(CW\*(C`mjd\-perl\-tiefile\[email protected]\*(C'\fR. |
| 616 |
.PP |
| 617 |
The most recent version of this module, including documentation and |
| 618 |
any news of importance, will be available at |
| 619 |
.PP |
| 620 |
.Vb 1 |
| 621 |
\& http://perl.plover.com/TieFile/ |
| 622 |
.Ve |
| 623 |
.SH LICENSE |
| 624 |
.IX Header "LICENSE" |
| 625 |
\&\f(CW\*(C`Tie::File\*(C'\fR version 0.96 is copyright (C) 2003 Mark Jason Dominus. |
| 626 |
.PP |
| 627 |
This library is free software; you may redistribute it and/or modify |
| 628 |
it under the same terms as Perl itself. |
| 629 |
.PP |
| 630 |
These terms are your choice of any of (1) the Perl Artistic Licence, |
| 631 |
or (2) version 2 of the GNU General Public License as published by the |
| 632 |
Free Software Foundation, or (3) any later version of the GNU General |
| 633 |
Public License. |
| 634 |
.PP |
| 635 |
This library is distributed in the hope that it will be useful, |
| 636 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 637 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 638 |
GNU General Public License for more details. |
| 639 |
.PP |
| 640 |
You should have received a copy of the GNU General Public License |
| 641 |
along with this library program; it should be in the file \f(CW\*(C`COPYING\*(C'\fR. |
| 642 |
If not, write to the Free Software Foundation, Inc., 51 Franklin Street, |
| 643 |
Fifth Floor, Boston, MA 02110\-1301, USA |
| 644 |
.PP |
| 645 |
For licensing inquiries, contact the author at: |
| 646 |
.PP |
| 647 |
.Vb 3 |
| 648 |
\& Mark Jason Dominus |
| 649 |
\& 255 S. Warnock St. |
| 650 |
\& Philadelphia, PA 19107 |
| 651 |
.Ve |
| 652 |
.SH WARRANTY |
| 653 |
.IX Header "WARRANTY" |
| 654 |
\&\f(CW\*(C`Tie::File\*(C'\fR version 0.98 comes with ABSOLUTELY NO WARRANTY. |
| 655 |
For details, see the license. |
| 656 |
.SH THANKS |
| 657 |
.IX Header "THANKS" |
| 658 |
Gigantic thanks to Jarkko Hietaniemi, for agreeing to put this in the |
| 659 |
core when I hadn't written it yet, and for generally being helpful, |
| 660 |
supportive, and competent. (Usually the rule is "choose any one.") |
| 661 |
Also big thanks to Abhijit Menon-Sen for all of the same things. |
| 662 |
.PP |
| 663 |
Special thanks to Craig Berry and Peter Prymmer (for VMS portability |
| 664 |
help), Randy Kobes (for Win32 portability help), Clinton Pierce and |
| 665 |
Autrijus Tang (for heroic eleventh-hour Win32 testing above and beyond |
| 666 |
the call of duty), Michael G Schwern (for testing advice), and the |
| 667 |
rest of the CPAN testers (for testing generally). |
| 668 |
.PP |
| 669 |
Special thanks to Tels for suggesting several speed and memory |
| 670 |
optimizations. |
| 671 |
.PP |
| 672 |
Additional thanks to: |
| 673 |
Edward Avis / |
| 674 |
Mattia Barbon / |
| 675 |
Tom Christiansen / |
| 676 |
Gerrit Haase / |
| 677 |
Gurusamy Sarathy / |
| 678 |
Jarkko Hietaniemi (again) / |
| 679 |
Nikola Knezevic / |
| 680 |
John Kominetz / |
| 681 |
Nick Ing-Simmons / |
| 682 |
Tassilo von Parseval / |
| 683 |
H. Dieter Pearcey / |
| 684 |
Slaven Rezic / |
| 685 |
Eric Roode / |
| 686 |
Peter Scott / |
| 687 |
Peter Somu / |
| 688 |
Autrijus Tang (again) / |
| 689 |
Tels (again) / |
| 690 |
Juerd Waalboer / |
| 691 |
Todd Rinaldo |
| 692 |
.SH TODO |
| 693 |
.IX Header "TODO" |
| 694 |
More tests. (Stuff I didn't think of yet.) |
| 695 |
.PP |
| 696 |
Paragraph mode? |
| 697 |
.PP |
| 698 |
Fixed-length mode. Leave-blanks mode. |
| 699 |
.PP |
| 700 |
Maybe an autolocking mode? |
| 701 |
.PP |
| 702 |
For many common uses of the module, the read cache is a liability. |
| 703 |
For example, a program that inserts a single record, or that scans the |
| 704 |
file once, will have a cache hit rate of zero. This suggests a major |
| 705 |
optimization: The cache should be initially disabled. Here's a hybrid |
| 706 |
approach: Initially, the cache is disabled, but the cache code |
| 707 |
maintains statistics about how high the hit rate would be *if* it were |
| 708 |
enabled. When it sees the hit rate get high enough, it enables |
| 709 |
itself. The STAT comments in this code are the beginning of an |
| 710 |
implementation of this. |
| 711 |
.PP |
| 712 |
Record locking with \fBfcntl()\fR? Then the module might support an undo |
| 713 |
log and get real transactions. What a tour de force that would be. |
| 714 |
.PP |
| 715 |
Keeping track of the highest cached record. This would allow reads-in-a-row |
| 716 |
to skip the cache lookup faster (if reading from 1..N with empty cache at |
| 717 |
start, the last cached value will be always N\-1). |
| 718 |
.PP |
| 719 |
More tests. |