132
|
1 /*******************************************************************************
|
|
2
|
|
3 copyright: Copyright (c) 2004 Kris Bell. All rights reserved
|
|
4
|
|
5 license: BSD style: $(LICENSE)
|
|
6
|
|
7 version: Initial release: March 2004
|
|
8 Outback release: December 2006
|
|
9
|
|
10 author: $(UL Kris)
|
|
11 $(UL John Reimer)
|
|
12 $(UL Anders F Bjorklund (Darwin patches))
|
|
13 $(UL Chris Sauls (Win95 file support))
|
|
14
|
|
15 *******************************************************************************/
|
|
16
|
|
17 module tango.io.FileConduit;
|
|
18
|
|
19 private import tango.sys.Common;
|
|
20
|
|
21 public import tango.io.FilePath;
|
|
22
|
|
23 private import tango.io.DeviceConduit;
|
|
24
|
|
25 private import Utf = tango.text.convert.Utf;
|
|
26
|
|
27 /*******************************************************************************
|
|
28
|
|
29 Other O/S functions
|
|
30
|
|
31 *******************************************************************************/
|
|
32
|
|
33 version (Win32)
|
|
34 private extern (Windows) BOOL SetEndOfFile (HANDLE);
|
|
35 else
|
|
36 private extern (C) int ftruncate (int, int);
|
|
37
|
|
38
|
|
39 /*******************************************************************************
|
|
40
|
|
41 Implements a means of reading and writing a generic file. Conduits
|
|
42 are the primary means of accessing external data and FileConduit
|
|
43 extends the basic pattern by providing file-specific methods to
|
|
44 set the file size, seek to a specific file position and so on.
|
|
45
|
|
46 Serial input and output is straightforward. In this example we
|
|
47 copy a file directly to the console:
|
|
48 ---
|
|
49 // open a file for reading
|
|
50 auto from = new FileConduit ("test.txt");
|
|
51
|
|
52 // stream directly to console
|
|
53 Stdout.copy (from);
|
|
54 ---
|
|
55
|
|
56 And here we copy one file to another:
|
|
57 ---
|
|
58 // open another for writing
|
|
59 auto to = new FileConduit ("copy.txt", FileConduit.WriteCreate);
|
|
60
|
|
61 // copy file
|
|
62 to.output.copy (new FileConduit("test.txt"));
|
|
63 ---
|
|
64
|
|
65 To load a file directly into memory one might do this:
|
|
66 ---
|
|
67 // open file for reading
|
|
68 auto fc = new FileConduit ("test.txt");
|
|
69
|
|
70 // create an array to house the entire file
|
|
71 auto content = new char[fc.length];
|
|
72
|
|
73 // read the file content. Return value is the number of bytes read
|
|
74 auto bytesRead = fc.input.read (content);
|
|
75 ---
|
|
76
|
|
77 Conversely, one may write directly to a FileConduit, like so:
|
|
78 ---
|
|
79 // open file for writing
|
|
80 auto to = new FileConduit ("text.txt", FileConduit.WriteCreate);
|
|
81
|
|
82 // write an array of content to it
|
|
83 auto bytesWritten = to.output.write (content);
|
|
84 ---
|
|
85
|
|
86 FileConduit can just as easily handle random IO. Here we use seek()
|
|
87 to relocate the file pointer and, for variation, apply a protocol to
|
|
88 perform simple input and output:
|
|
89 ---
|
|
90 // open a file for reading
|
|
91 auto fc = new FileConduit ("random.bin", FileConduit.ReadWriteCreate);
|
|
92
|
|
93 // construct (binary) reader & writer upon this conduit
|
|
94 auto read = new Reader (fc);
|
|
95 auto write = new Writer (fc);
|
|
96
|
|
97 int x=10, y=20;
|
|
98
|
|
99 // write some data, and flush output since protocol IO is buffered
|
|
100 write (x) (y) ();
|
|
101
|
|
102 // rewind to file start
|
|
103 fc.seek (0);
|
|
104
|
|
105 // read data back again
|
|
106 read (x) (y);
|
|
107
|
|
108 fc.close();
|
|
109 ---
|
|
110
|
|
111 See File, FilePath, FileConst, FileScan, and FileSystem for
|
|
112 additional functionality related to file manipulation.
|
|
113
|
|
114 Compile with -version=Win32SansUnicode to enable Win95 & Win32s file
|
|
115 support.
|
|
116
|
|
117 *******************************************************************************/
|
|
118
|
|
119 class FileConduit : DeviceConduit, DeviceConduit.Seek
|
|
120 {
|
|
121 /***********************************************************************
|
|
122
|
|
123 Fits into 32 bits ...
|
|
124
|
|
125 ***********************************************************************/
|
|
126
|
|
127 struct Style
|
|
128 {
|
|
129 align (1):
|
|
130
|
|
131 Access access; /// access rights
|
|
132 Open open; /// how to open
|
|
133 Share share; /// how to share
|
|
134 Cache cache; /// how to cache
|
|
135 }
|
|
136
|
|
137 /***********************************************************************
|
|
138
|
|
139 ***********************************************************************/
|
|
140
|
|
141 enum Access : ubyte {
|
|
142 Read = 0x01, /// is readable
|
|
143 Write = 0x02, /// is writable
|
|
144 ReadWrite = 0x03, /// both
|
|
145 }
|
|
146
|
|
147 /***********************************************************************
|
|
148
|
|
149 ***********************************************************************/
|
|
150
|
|
151 enum Open : ubyte {
|
|
152 Exists=0, /// must exist
|
|
153 Create, /// create or truncate
|
|
154 Sedate, /// create if necessary
|
|
155 Append, /// create if necessary
|
|
156 };
|
|
157
|
|
158 /***********************************************************************
|
|
159
|
|
160 ***********************************************************************/
|
|
161
|
|
162 enum Share : ubyte {
|
|
163 None=0, /// no sharing
|
|
164 Read, /// shared reading
|
|
165 ReadWrite, /// open for anything
|
|
166 };
|
|
167
|
|
168 /***********************************************************************
|
|
169
|
|
170 ***********************************************************************/
|
|
171
|
|
172 enum Cache : ubyte {
|
|
173 None = 0x00, /// don't optimize
|
|
174 Random = 0x01, /// optimize for random
|
|
175 Stream = 0x02, /// optimize for stream
|
|
176 WriteThru = 0x04, /// backing-cache flag
|
|
177 };
|
|
178
|
|
179 /***********************************************************************
|
|
180
|
|
181 Read an existing file
|
|
182
|
|
183 ***********************************************************************/
|
|
184
|
|
185 const Style ReadExisting = {Access.Read, Open.Exists};
|
|
186
|
|
187 /***********************************************************************
|
|
188
|
|
189 Write on an existing file. Do not create
|
|
190
|
|
191 ***********************************************************************/
|
|
192
|
|
193 const Style WriteExisting = {Access.Write, Open.Exists};
|
|
194
|
|
195 /***********************************************************************
|
|
196
|
|
197 Write on a clean file. Create if necessary
|
|
198
|
|
199 ***********************************************************************/
|
|
200
|
|
201 const Style WriteCreate = {Access.Write, Open.Create};
|
|
202
|
|
203 /***********************************************************************
|
|
204
|
|
205 Write at the end of the file
|
|
206
|
|
207 ***********************************************************************/
|
|
208
|
|
209 deprecated const Style WriteAppending = {Access.Write, Open.Append};
|
|
210
|
|
211 /***********************************************************************
|
|
212
|
|
213 Read and write an existing file
|
|
214
|
|
215 ***********************************************************************/
|
|
216
|
|
217 const Style ReadWriteExisting = {Access.ReadWrite, Open.Exists};
|
|
218
|
|
219 /***********************************************************************
|
|
220
|
|
221 Read & write on a clean file. Create if necessary
|
|
222
|
|
223 ***********************************************************************/
|
|
224
|
|
225 const Style ReadWriteCreate = {Access.ReadWrite, Open.Create};
|
|
226
|
|
227 /***********************************************************************
|
|
228
|
|
229 Read and Write. Use existing file if present
|
|
230
|
|
231 ***********************************************************************/
|
|
232
|
|
233 const Style ReadWriteOpen = {Access.ReadWrite, Open.Sedate};
|
|
234
|
|
235
|
|
236
|
|
237
|
|
238 // the file we're working with
|
|
239 private PathView path_;
|
|
240
|
|
241 // the style we're opened with
|
|
242 private Style style_;
|
|
243
|
|
244 /***********************************************************************
|
|
245
|
|
246 Create a FileConduit with the provided path and style.
|
|
247
|
|
248 ***********************************************************************/
|
|
249
|
|
250 this (char[] name, Style style = ReadExisting)
|
|
251 {
|
|
252 this (new FilePath(name), style);
|
|
253 }
|
|
254
|
|
255 /***********************************************************************
|
|
256
|
|
257 Create a FileConduit with the provided path and style.
|
|
258
|
|
259 ***********************************************************************/
|
|
260
|
|
261 this (PathView path, Style style = ReadExisting)
|
|
262 {
|
|
263 // remember who we are
|
|
264 path_ = path;
|
|
265
|
|
266 // open the file
|
|
267 open (this.style_ = style);
|
|
268 }
|
|
269
|
|
270 /***********************************************************************
|
|
271
|
|
272 Return the PathView used by this file.
|
|
273
|
|
274 ***********************************************************************/
|
|
275
|
|
276 PathView path ()
|
|
277 {
|
|
278 return path_;
|
|
279 }
|
|
280
|
|
281 /***********************************************************************
|
|
282
|
|
283 Return the Style used for this file.
|
|
284
|
|
285 ***********************************************************************/
|
|
286
|
|
287 Style style ()
|
|
288 {
|
|
289 return style_;
|
|
290 }
|
|
291
|
|
292 /***********************************************************************
|
|
293
|
|
294 Return the name of the FilePath used by this file.
|
|
295
|
|
296 ***********************************************************************/
|
|
297
|
|
298 override char[] toString ()
|
|
299 {
|
|
300 return path_.toString;
|
|
301 }
|
|
302
|
|
303 /***********************************************************************
|
|
304
|
|
305 Return the current file position.
|
|
306
|
|
307 ***********************************************************************/
|
|
308
|
|
309 long position ()
|
|
310 {
|
|
311 return seek (0, Seek.Anchor.Current);
|
|
312 }
|
|
313
|
|
314 /***********************************************************************
|
|
315
|
|
316 Return the total length of this file.
|
|
317
|
|
318 ***********************************************************************/
|
|
319
|
|
320 long length ()
|
|
321 {
|
|
322 long pos,
|
|
323 ret;
|
|
324
|
|
325 pos = position ();
|
|
326 ret = seek (0, Seek.Anchor.End);
|
|
327 seek (pos);
|
|
328 return ret;
|
|
329 }
|
|
330
|
|
331
|
|
332 /***********************************************************************
|
|
333
|
|
334 Windows-specific code
|
|
335
|
|
336 ***********************************************************************/
|
|
337
|
|
338 version(Win32)
|
|
339 {
|
|
340 private bool appending;
|
|
341
|
|
342 /***************************************************************
|
|
343
|
|
344 Open a file with the provided style.
|
|
345
|
|
346 ***************************************************************/
|
|
347
|
|
348 protected void open (Style style)
|
|
349 {
|
|
350 DWORD attr,
|
|
351 share,
|
|
352 access,
|
|
353 create;
|
|
354
|
|
355 alias DWORD[] Flags;
|
|
356
|
|
357 static const Flags Access =
|
|
358 [
|
|
359 0, // invalid
|
|
360 GENERIC_READ,
|
|
361 GENERIC_WRITE,
|
|
362 GENERIC_READ | GENERIC_WRITE,
|
|
363 ];
|
|
364
|
|
365 static const Flags Create =
|
|
366 [
|
|
367 OPEN_EXISTING, // must exist
|
|
368 CREATE_ALWAYS, // truncate always
|
|
369 OPEN_ALWAYS, // create if needed
|
|
370 OPEN_ALWAYS, // (for appending)
|
|
371 ];
|
|
372
|
|
373 static const Flags Share =
|
|
374 [
|
|
375 0,
|
|
376 FILE_SHARE_READ,
|
|
377 FILE_SHARE_READ | FILE_SHARE_WRITE,
|
|
378 ];
|
|
379
|
|
380 static const Flags Attr =
|
|
381 [
|
|
382 0,
|
|
383 FILE_FLAG_RANDOM_ACCESS,
|
|
384 FILE_FLAG_SEQUENTIAL_SCAN,
|
|
385 0,
|
|
386 FILE_FLAG_WRITE_THROUGH,
|
|
387 ];
|
|
388
|
|
389 attr = Attr[style.cache];
|
|
390 share = Share[style.share];
|
|
391 create = Create[style.open];
|
|
392 access = Access[style.access];
|
|
393
|
|
394 version (Win32SansUnicode)
|
|
395 handle = CreateFileA (path.cString.ptr, access, share,
|
|
396 null, create,
|
|
397 attr | FILE_ATTRIBUTE_NORMAL,
|
|
398 cast(HANDLE) null);
|
|
399 else
|
|
400 {
|
|
401 wchar[256] tmp = void;
|
|
402 auto name = Utf.toString16 (path.cString, tmp);
|
|
403 handle = CreateFileW (name.ptr, access, share,
|
|
404 null, create,
|
|
405 attr | FILE_ATTRIBUTE_NORMAL,
|
|
406 cast(HANDLE) null);
|
|
407 }
|
|
408
|
|
409 if (handle is INVALID_HANDLE_VALUE)
|
|
410 error ();
|
|
411
|
|
412 // move to end of file?
|
|
413 if (style.open is Open.Append)
|
|
414 appending = true;
|
|
415 }
|
|
416
|
|
417 /***************************************************************
|
|
418
|
|
419 Write a chunk of bytes to the file from the provided
|
|
420 array (typically that belonging to an IBuffer)
|
|
421
|
|
422 ***************************************************************/
|
|
423
|
|
424 override uint write (void[] src)
|
|
425 {
|
|
426 DWORD written;
|
|
427
|
|
428 // try to emulate the Unix O_APPEND mode
|
|
429 if (appending)
|
|
430 SetFilePointer (handle, 0, null, Seek.Anchor.End);
|
|
431
|
|
432 return super.write (src);
|
|
433 }
|
|
434
|
|
435 /***************************************************************
|
|
436
|
|
437 Ensures that data is flushed immediately to disk
|
|
438
|
|
439 ***************************************************************/
|
|
440 /+
|
|
441 override void commit ()
|
|
442 {
|
|
443 if (style_.access & Access.Write)
|
|
444 if (! FlushFileBuffers (handle))
|
|
445 error ();
|
|
446 }
|
|
447 +/
|
|
448 /***************************************************************
|
|
449
|
|
450 Set the file size to be that of the current seek
|
|
451 position. The file must be writable for this to
|
|
452 succeed.
|
|
453
|
|
454 ***************************************************************/
|
|
455
|
|
456 void truncate ()
|
|
457 {
|
|
458 // must have Generic_Write access
|
|
459 if (! SetEndOfFile (handle))
|
|
460 error ();
|
|
461 }
|
|
462
|
|
463 /***************************************************************
|
|
464
|
|
465 Set the file seek position to the specified offset
|
|
466 from the given anchor.
|
|
467
|
|
468 ***************************************************************/
|
|
469
|
|
470 long seek (long offset, Seek.Anchor anchor = Seek.Anchor.Begin)
|
|
471 {
|
|
472 LONG high = cast(LONG) (offset >> 32);
|
|
473 long result = SetFilePointer (handle, cast(LONG) offset,
|
|
474 &high, anchor);
|
|
475
|
|
476 if (result is -1 &&
|
|
477 GetLastError() != ERROR_SUCCESS)
|
|
478 error ();
|
|
479
|
|
480 return result + (cast(long) high << 32);
|
|
481 }
|
|
482 }
|
|
483
|
|
484
|
|
485 /***********************************************************************
|
|
486
|
|
487 Unix-specific code. Note that some methods are 32bit only
|
|
488
|
|
489 ***********************************************************************/
|
|
490
|
|
491 version (Posix)
|
|
492 {
|
|
493 /***************************************************************
|
|
494
|
|
495 Open a file with the provided style.
|
|
496
|
|
497 Note that files default to no-sharing. That is,
|
|
498 they are locked exclusively to the host process
|
|
499 unless otherwise stipulated. We do this in order
|
|
500 to expose the same default behaviour as Win32
|
|
501
|
|
502 NO FILE LOCKING FOR BORKED POSIX
|
|
503
|
|
504 ***************************************************************/
|
|
505
|
|
506 protected void open (Style style)
|
|
507 {
|
|
508 alias int[] Flags;
|
|
509
|
|
510 const O_LARGEFILE = 0x8000;
|
|
511
|
|
512 static const Flags Access =
|
|
513 [
|
|
514 0, // invalid
|
|
515 O_RDONLY,
|
|
516 O_WRONLY,
|
|
517 O_RDWR,
|
|
518 ];
|
|
519
|
|
520 static const Flags Create =
|
|
521 [
|
|
522 0, // open existing
|
|
523 O_CREAT | O_TRUNC, // truncate always
|
|
524 O_CREAT, // create if needed
|
|
525 O_APPEND | O_CREAT, // append
|
|
526 ];
|
|
527
|
|
528 static const short[] Locks =
|
|
529 [
|
|
530 F_WRLCK, // no sharing
|
|
531 F_RDLCK, // shared read
|
|
532 ];
|
|
533
|
|
534 auto mode = Access[style.access] | Create[style.open];
|
|
535
|
|
536 // always open as a large file
|
|
537 handle = posix.open (path.cString.ptr, mode | O_LARGEFILE, 0666);
|
|
538 if (handle is -1)
|
|
539 error ();
|
|
540 }
|
|
541
|
|
542 /***************************************************************
|
|
543
|
|
544 Ensures that data is flushed immediately to disk
|
|
545
|
|
546 ***************************************************************/
|
|
547 /+
|
|
548 override void commit ()
|
|
549 {
|
|
550 // no Posix API for this :(
|
|
551 }
|
|
552 +/
|
|
553 /***************************************************************
|
|
554
|
|
555 Set the file size to be that of the current seek
|
|
556 position. The file must be writable for this to
|
|
557 succeed.
|
|
558
|
|
559 ***************************************************************/
|
|
560
|
|
561 void truncate ()
|
|
562 {
|
|
563 // set filesize to be current seek-position
|
|
564 if (ftruncate (handle, position) is -1)
|
|
565 error ();
|
|
566 }
|
|
567
|
|
568 /***************************************************************
|
|
569
|
|
570 Set the file seek position to the specified offset
|
|
571 from the given anchor.
|
|
572
|
|
573 ***************************************************************/
|
|
574
|
|
575 long seek (long offset, Seek.Anchor anchor = Seek.Anchor.Begin)
|
|
576 {
|
|
577 long result = posix.lseek (handle, offset, anchor);
|
|
578 if (result is -1)
|
|
579 error ();
|
|
580 return result;
|
|
581 }
|
|
582 }
|
|
583 }
|