1FastRaw(3)            User Contributed Perl Documentation           FastRaw(3)
2
3
4

NAME

6       PDL::IO::FastRaw -- A simple, fast and convenient io format for PerlDL.
7

SYNOPSIS

9        use PDL;
10        use PDL::IO::FastRaw;
11
12        writefraw($pdl,"fname");         # write a raw file
13
14        $pdl2 = readfraw("fname");       # read a raw file
15        $pdl2 = PDL->readfraw("fname");
16
17        $pdl3 = mapfraw("fname2",{ReadOnly => 1}); # mmap a file, don't read yet
18
19        $pdl4 = maptextfraw("fname3",{...}); # map a text file into a 1-D pdl.
20

DESCRIPTION

22       This is a very simple and fast io format for PerlDL.  The disk data
23       consists of two files, a header metadata file in ASCII and a binary
24       file consisting simply of consecutive bytes, shorts or whatever.
25
26       It is hoped that this will not only make for a simple PerlDL module for
27       saving and retrieving these files but also make it easy for other
28       programs to use these files.
29
30       The format of the ASCII header is simply
31
32               <typeid>
33               <ndims>
34               <dim0> <dim1> ...
35
36       The binary files are in general NOT interchangeable between different
37       architectures since the binary file is simply dumped from the memory
38       region of the piddle.  This is what makes the approach efficient.
39
40       It is also possible to mmap the file which can give a large speedup in
41       certain situations as well as save a lot of memory by using a disk file
42       as virtual memory. When a file is mapped, parts of it are read only as
43       they are accessed in the memory (or as the kernel decides: if you are
44       reading the pages in order, it may well preread some for you).
45
46       Note that memory savings and copy-on-write are operating-system
47       dependent - see Core.xs and your operating system documentation for
48       exact semantics of whatever. Basically, if you write to a mmapped file
49       without "ReadOnly", the change will be reflected in the file
50       immediately. "ReadOnly" doesn't really make it impossible to write to
51       the piddle but maps the memory privately so the file will not be
52       changed when you change the piddle. Be aware though that mmapping a
53       40Mb file without "ReadOnly" spends no virtual memory but with
54       "ReadOnly" it does reserve 40Mb.
55

FUNCTIONS

57   readfraw
58       Read a raw format binary file
59
60        $pdl2 = readfraw("fname");
61        $pdl2 = PDL->readfraw("fname");
62
63   writefraw
64       Write a raw format binary file
65
66        writefraw($pdl,"fname");
67
68   mapfraw
69       Memory map a raw format binary file (see the module docs also)
70
71        $pdl3 = mapfraw("fname2",{ReadOnly => 1});
72
73       The "mapfraw" command supports the following options (not all
74       combinations make sense):
75
76       Dims, Datatype
77               If creating a new file or if you want to specify your own
78               header data for the file, you can give an array reference and a
79               scalar, respectively.
80
81       Creat   Create the file. Also writes out a header for the file.
82
83       Trunc   Set the file size. Automatically enabled with "Creat". NOTE:
84               This also clears the file to all zeroes.
85
86       ReadOnly
87               Disallow writing to the file.
88
89   maptextfraw
90       Memory map a text file (see the module docs also).
91
92       Note that this function maps the raw format so if you are using an
93       operating system which does strange things to e.g.  line delimiters
94       upon reading a text file, you get the raw (binary) representation.
95
96       The file doesn't really need to be text but it is just mapped as one
97       large binary chunk.
98
99       This function is just a convenience wrapper which firsts "stat"s the
100       file and sets the dimensions and datatype.
101
102        $pdl4 = maptextfraw("fname", {options}
103
104       The options other than Dims, Datatype of "mapfraw" are supported.
105

BUGS

107       Should be documented better. "writefraw" and "readfraw" should also
108       have options (the author nowadays only uses "mapfraw" ;)
109

AUTHOR

111       Copyright (C) Tuomas J. Lukka 1997.  All rights reserved. There is no
112       warranty. You are allowed to redistribute this software / documentation
113       under certain conditions. For details, see the file COPYING in the PDL
114       distribution. If this file is separated from the PDL distribution, the
115       copyright notice should be included in the file.
116
117
118
119perl v5.12.3                      2009-10-17                        FastRaw(3)
Impressum